
# The web and deep links

The routes are the addresses of the app everywhere: in a browser's address bar, in the pages the build writes for search engines, and in links that open the app from outside (deep links). The browser's addresses have no `#` by default; the deep links are written into the iOS, macOS and Android projects from properties.

## Why

Deep links need edits in `Info.plist`, an entitlements file, the Android manifest, and two JSON files on the web server, each in its own format, kept in step by hand. Here they are a few properties; the generator writes each file, and every link goes through the routes, so a guarded screen still asks for the login.

## Example

```yaml
# lib/resources/application.yml
spring:
  flutter:
    navigation:
      web:
        url-strategy: path
      deep-links:
        scheme: neonbooks                     # neonbooks://catalog/books/1
        domains: [books.example.com]          # https://books.example.com/catalog/books/1
        exclude: [/checkout, /admin/**]
```

```yaml
# lib/resources/application-android.yml
spring:
  flutter:
    navigation:
      deep-links:
        sha256-cert-fingerprints:
          - 14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5
```

## Addresses in a browser

| `url-strategy` | The address bar | The host |
|---|---|---|
| `path` (default) | `/catalog/books/1` | Must answer every address of the app with `index.html` (or the build writes a page per path) |
| `hash` | `/#/catalog/books/1` | Serves `index.html` only (Flutter's own default) |

With `path`, the starter keeps the `#heading` part of an address. Opening `/docs/beans#bean-methods` directly (a shared link, a search engine result) opens the page scrolled to that heading. Before, the `#` part was dropped on the first load.

## Pages for search engines

With `spring.flutter.web.seo.enabled` and `from-routes: true`, the build writes a page per route, with its title, its description (`@RouteInfo`) and its Markdown text, in every language of `spring.flutter.navigation.languages`:

| Screen | Pages |
|---|---|
| A path without variables (`/about`) | One page at that path |
| A path without variables and a `content:` file | One page, with the file's Markdown |
| A path ending in `{*name}` with a `content:` folder | A page per Markdown file of the folder |
| A path with other variables (`/books/{isbn}`) | None, unless `@RouteInfo(paths: [...])` lists its addresses |
| The not-found screen | None |

`@RouteInfo(index: false)` keeps a page out of the sitemap (`noindex`). See [Pages for search engines](../spring-core-dart-generator/flutter/seo.md) and, step by step, [SEO](../spring-boot-starter-flutter/seo.md).

## Deep links

The generator writes the platforms' files from `spring.flutter.navigation.deep-links.*`; at run time only `exclude` is read. A value for one platform goes into its profile file (`application-ios.yml`, `application-android.yml`).

| Platform | File | What |
|---|---|---|
| iOS | `ios/Runner/Info.plist` | `FlutterDeepLinkingEnabled` and the scheme (`CFBundleURLTypes`) |
| iOS | `ios/Runner/Runner.entitlements` | `applinks:<domain>` for each domain, when the file exists (create it in Xcode with the Associated Domains capability; the build only warns when it is missing) |
| macOS | `macos/Runner/Info.plist` | The scheme |
| Android | `android/app/src/main/AndroidManifest.xml` | In the main activity: `flutter_deeplinking_enabled`, an intent filter for the scheme and a verified (`autoVerify`) one for the domains |
| Each domain | `web/.well-known/` (a web app), else `build/spring/well-known/` | `apple-app-site-association` and `assetlinks.json`, which the domain serves under `https://<domain>/.well-known/`; the excluded paths are left out of Apple's file |

- Windows and Linux get no deep links yet.
- Every link that opens the app goes through its routes: a screen with `@RouteInfo(link: false)` or under `exclude` opens the first screen instead, and a guarded screen asks for the login first.
- The generator writes its blocks between `spring:deep-links:start` and `spring:deep-links:end` comments with their hash: a block changed by hand, or a key of the block the file declares outside it (`CFBundleURLTypes`), fails the build. It never edits the Xcode project.

See [Deep links](../spring-core-dart-generator/flutter/deep-links.md) for the builder.

## The properties

| Key | Type | Default | Read | Meaning |
|---|---|---|---|---|
| `spring.flutter.navigation.web.url-strategy` | `path`, `hash` | `path` | at the start | How a browser's address bar shows the route |
| `spring.flutter.navigation.deep-links.enabled` | bool | `true` | by the generator | Whether the deep links are written; `false` in a platform's profile file turns them off there |
| `spring.flutter.navigation.deep-links.scheme` | URL scheme | none | by the generator | The app's own scheme (`neonbooks://catalog/books/1`). Not verified: another app may claim it, so links people share go through `domains` |
| `spring.flutter.navigation.deep-links.domains` | list of host names | none | by the generator | The domains whose `https` links open the app (Universal Links, App Links): host names, no scheme or path |
| `spring.flutter.navigation.deep-links.exclude` | list of path patterns | none | at the start and by the generator | Addresses a link does not open (the first screen opens instead), as `@RouteInfo(link: false)`; excluded in Apple's file too |
| `spring.flutter.navigation.deep-links.app-id` | `TEAMID.bundle.id` | from the Xcode project | by the generator | The iOS app id of `apple-app-site-association` |
| `spring.flutter.navigation.deep-links.package` | Android package | the Gradle file's `applicationId` | by the generator | The package of `assetlinks.json` |
| `spring.flutter.navigation.deep-links.sha256-cert-fingerprints` | list | none | by the generator | The SHA-256 fingerprints of the Android signing keys (the upload key's and Google Play's); without them `assetlinks.json` is not written and Android does not verify the domain |

## See also

- [Filters, guards and errors](filters-and-guards.md)
- [The web](../spring-boot-starter-flutter/web.md)
- [SEO](../spring-boot-starter-flutter/seo.md)
- [Deep links in the generator](../spring-core-dart-generator/flutter/deep-links.md)
