
# Deep links

A deep link is a link from outside the app that opens it at a route: `neonbooks://catalog/books/1` (the app's own scheme), or `https://books.example.com/catalog/books/1` (a domain of the app: Universal Links on iOS, App Links on Android). Each platform learns which links belong to the app from its own files. The builder `spring_flutter_deep_links` writes those files from the properties `spring.flutter.navigation.deep-links.*` of `spring_boot_starter_flutter_navigation`, and writes the two files each domain must serve.

## Why

By hand, one deep link setup means four files in three formats: a plist array for the scheme on iOS and macOS, an entitlement for the domains on iOS, two intent filters in the Android manifest, and two JSON files on the web server. They must agree with each other and with the app's routes, and they drift apart as the app changes.

With the builder, you write the scheme and the domains once, in the configuration the app already reads. The build writes every platform file from them on each run, and removes what it wrote when the properties go away. A route the app excludes is excluded in Apple's file too.

## Example

```yaml
# lib/resources/application.yml
spring:
  flutter:
    navigation:
      deep-links:
        scheme: neonbooks                  # neonbooks://catalog/books/1
        domains: [books.example.com]       # https://books.example.com/...
        exclude: ['/checkout', '/admin/**'] # these links open the first screen
```

```properties
# lib/resources/application-android.properties
# Only Android needs the fingerprints of its signing keys.
spring.flutter.navigation.deep-links.sha256-cert-fingerprints=AB:CD:EF
```

After `dart run build_runner build`, `ios/Runner/Info.plist` has a new block before its last `</dict>`:

```xml
	<key>CFBundleName</key>
	<string>books</string>
	<!-- spring:deep-links:start sha=449287e501d5 (generated from spring.flutter.navigation.deep-links.*; do not edit) -->
	<key>FlutterDeepLinkingEnabled</key>
	<true/>
	<key>CFBundleURLTypes</key>
	<array>
		<dict>
			<key>CFBundleURLName</key>
			<string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
			<key>CFBundleURLSchemes</key>
			<array>
				<string>neonbooks</string>
			</array>
		</dict>
	</array>
	<!-- spring:deep-links:end -->
</dict>
</plist>
```

`ios/Runner/Runner.entitlements` gets the domain:

```xml
<dict>
    <!-- spring:deep-links:start sha=00fcfd7129e2 (generated from spring.flutter.navigation.deep-links.*; do not edit) -->
    <key>com.apple.developer.associated-domains</key>
    <array>
    	<string>applinks:books.example.com</string>
    </array>
    <!-- spring:deep-links:end -->
</dict>
```

`android/app/src/main/AndroidManifest.xml` gets a block at the end of the main activity:

```xml
        <activity android:name=".MainActivity" android:exported="true">
            <intent-filter>
                <action android:name="android.intent.action.MAIN"/>
                <category android:name="android.intent.category.LAUNCHER"/>
            </intent-filter>
            <!-- spring:deep-links:start sha=a2fba4aa3350 (generated from spring.flutter.navigation.deep-links.*; do not edit) -->
            <meta-data android:name="flutter_deeplinking_enabled" android:value="true" />
            <intent-filter>
                <action android:name="android.intent.action.VIEW" />
                <category android:name="android.intent.category.DEFAULT" />
                <category android:name="android.intent.category.BROWSABLE" />
                <data android:scheme="neonbooks" />
            </intent-filter>
            <intent-filter android:autoVerify="true">
                <action android:name="android.intent.action.VIEW" />
                <category android:name="android.intent.category.DEFAULT" />
                <category android:name="android.intent.category.BROWSABLE" />
                <data android:scheme="https" />
                <data android:host="books.example.com" />
            </intent-filter>
            <!-- spring:deep-links:end -->
        </activity>
```

`macos/Runner/Info.plist` gets the `CFBundleURLTypes` part only (the scheme). And, because the app has a web version (`web/index.html` exists), the two domain files go into `web/.well-known/`:

```json
// web/.well-known/apple-app-site-association
{
  "applinks": {
    "details": [
      {
        "appIDs": [
          "ABCDE12345.com.example.books"
        ],
        "components": [
          {
            "/": "/checkout",
            "exclude": true
          },
          {
            "/": "/admin/*",
            "exclude": true
          },
          {
            "/": "*"
          }
        ]
      }
    ]
  }
}
```

```json
// web/.well-known/assetlinks.json
[
  {
    "relation": [
      "delegate_permission/common.handle_all_urls"
    ],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example.books",
      "sha256_cert_fingerprints": [
        "AB:CD:EF"
      ]
    }
  }
]
```

The app id `ABCDE12345.com.example.books` came from the Xcode project (`DEVELOPMENT_TEAM` and `PRODUCT_BUNDLE_IDENTIFIER`), and the package `com.example.books` from `applicationId` in `android/app/build.gradle.kts`. The comments above the JSON only name the file; the files have none.

## The properties

All keys are under `spring.flutter.navigation.deep-links`.

| Key | Type | Default | What the build does with it |
|---|---|---|---|
| `enabled` | `true` / `false` | `true` | `false` writes nothing for the platform that reads it, and removes the blocks written before. Put it in a platform's profile file (`application-macos.yml`) to turn the links off there only. |
| `scheme` | URL scheme | none | The app's own scheme: `CFBundleURLTypes` in the `Info.plist` of iOS and macOS, an intent filter on Android. Not verified: another app may claim the same scheme. |
| `domains` | list of host names | none | The domains whose `https` links open the app: `applinks:` entries in `Runner.entitlements`, a verified (`autoVerify`) intent filter on Android, and the two domain files. |
| `exclude` | list of path patterns | none | Spring path patterns whose links do not open their screen. They become `"exclude": true` components in `apple-app-site-association`. |
| `app-id` | `TEAMID.bundle.id` | from `ios/Runner.xcodeproj/project.pbxproj` | The app id in `apple-app-site-association`. Set it in `application-ios.yml`. |
| `package` | Android package | `applicationId` of `android/app/build.gradle.kts`, else `build.gradle` | The `package_name` in `assetlinks.json`. |
| `sha256-cert-fingerprints` | list | none | The SHA-256 fingerprints of the keys the Android app is signed with (your upload key's and Google Play's). Without them `assetlinks.json` is not written. |

Lists can be written either way: as a YAML list, as indexed keys (`domains[0]=...`), or as one comma-separated value (`domains=a.example.com, b.example.com`).

At run time, the navigation starter reads only `exclude`. The other keys exist for the build.

## How the configuration is read

The build reads the configuration **once per platform, as the app reads it on that platform**. The app adds its platform's profiles when it starts, so the build does the same:

| Platform | Profiles read | Files written |
|---|---|---|
| iOS | `mobile`, then `ios` | `ios/Runner/Info.plist`, `ios/Runner/Runner.entitlements`, `apple-app-site-association` |
| Android | `mobile`, then `android` | `android/app/src/main/AndroidManifest.xml`, `assetlinks.json` |
| macOS | `desktop`, then `macos` | `macos/Runner/Info.plist` |

For each platform, the build loads the files of `lib/resources/` with the same configuration loader the app uses: `application.*`, then the files of those profiles in that order (`application-mobile.yml`, then `application-ios.yml`, so the platform's own file wins, as in the app), the files of the profiles that `spring.profiles.active` names in them, and the `resources:` files that `spring.config.import` names. A value only an environment variable or a `--dart-define` can give is unknown at build time: a placeholder with a default (`${APP_SCHEME:neonbooks}`) uses the default, and a profile name or import location that depends on one is left out with a warning. See [Properties the build reads](../build-properties.md) for the details shared by all web and platform builders.

So a value in `application-android.properties` applies to Android only, and `enabled: false` in `application-macos.yml` removes the macOS block while iOS and Android keep theirs. When a key is in both `application-mobile.yml` and `application-ios.yml`, the iOS file wins on iOS, as it does in the app.

Windows and Linux get nothing: the builder has no target for them.

## When the builder runs

`spring_flutter_deep_links` applies to every package that depends on the generator (`auto_apply: dependents`), and declares no outputs: the files it changes belong to the app. On each build:

1. It reads the text files of `lib/resources/`. If none of them contains `deep-links` or `deepLinks`, it does not load the configuration at all, and every platform counts as "no deep links".
2. Otherwise it reads the configuration for each platform (above). A platform has deep links when `enabled` is not `false` and a `scheme` or at least one domain is set.
3. For each target file that exists, it puts the new block between the markers, replaces the old one, or removes it when the platform has no deep links. A file that does not exist is skipped: the build never creates `Info.plist` or the manifest.
4. It writes the domain files when there are domains (below).

A package without deep links, such as a pure Dart server, is not touched: there is nothing to insert, and no old block to remove.

## The blocks and their markers

Every block sits between two XML comments:

```xml
<!-- spring:deep-links:start sha=449287e501d5 (generated from spring.flutter.navigation.deep-links.*; do not edit) -->
...
<!-- spring:deep-links:end -->
```

The `sha=` value is the first 12 hex digits of the SHA-256 of the block's body. It lets the build tell its own block from a block someone edited.

**Where the block goes.** The first time, the block is inserted one indentation level deeper than its anchor, using tabs when the file is indented with tabs and four spaces otherwise:

| File | Anchor |
|---|---|
| `Info.plist`, `Runner.entitlements` | before the last `</dict>` that is followed by `</plist>` |
| `AndroidManifest.xml` | before the `</activity>` that closes the activity with the `android.intent.category.LAUNCHER` intent: Flutter's `MainActivity` |

After that, the block is replaced where it is.

**What each block holds.**

| File | Content |
|---|---|
| `ios/Runner/Info.plist` | `FlutterDeepLinkingEnabled` = `true`, so Flutter hands the link to the router; and `CFBundleURLTypes` with the scheme, when one is set |
| `ios/Runner/Runner.entitlements` | `com.apple.developer.associated-domains` with `applinks:<domain>` for each domain |
| `macos/Runner/Info.plist` | `CFBundleURLTypes` with the scheme; no block without a scheme |
| `AndroidManifest.xml` | `flutter_deeplinking_enabled` meta-data; an intent filter for the scheme; an `autoVerify` intent filter for `https` with one `<data android:host>` per domain |

**`Runner.entitlements` must exist.** Xcode creates it when you add the Associated Domains capability to the Runner target. The build never edits the Xcode project, so it cannot create the file or link it. With domains set and no such file, the build warns:

```text
ios/Runner/Runner.entitlements is missing, so iOS does not open the links of books.example.com: add the Associated Domains capability to the Runner target in Xcode (it makes the file); the build then writes the domains into it.
```

## Errors

These problems fail the build (a severe log) and leave the file as it is:

| Problem | Message (shortened) |
|---|---|
| The block was edited by hand: its body no longer matches its `sha=` | `the block between "<!-- spring:deep-links:start" and "<!-- spring:deep-links:end -->" was changed by hand. Make the change in the spring.flutter.navigation.deep-links.* properties instead and delete the block (it is written again), or remove the properties.` |
| A key the block writes is also in the file outside the block, for example your own `CFBundleURLTypes`: the platform reads only one | `<key>CFBundleURLTypes</key> is written outside the generated block too; the platform reads one. Remove it from the file ... or turn the deep links off.` |
| The anchor is missing (no `</dict></plist>`, no launcher activity) | `no place for the deep links (the end of the main activity not found).` |
| `scheme` is no URL scheme (it must be a letter, then letters, digits, `+`, `-` or `.`) | `spring.flutter.navigation.deep-links.scheme "..." is no URL scheme ...` |
| `scheme` is `http` or `https` | `... scheme cannot be https: put the site in spring.flutter.navigation.deep-links.domains instead.` |
| A domain has a scheme or a path (`https://books.example.com`) | `... domains: "https://books.example.com" is no host name (no scheme, no path: books.example.com).` |

A wrong scheme or domain stops the deep links of that platform only. A wildcard domain (`*.example.com`) is accepted.

To change an edited block: move your change into the properties, delete the block with its two markers, and build again.

## The files each domain serves

A platform trusts a domain only when the domain confirms it, by serving a file under `https://<domain>/.well-known/`:

| File | For | Written when |
|---|---|---|
| `apple-app-site-association` | iOS (Universal Links) | iOS has domains and the app id is known: `app-id`, else `DEVELOPMENT_TEAM` and the first `PRODUCT_BUNDLE_IDENTIFIER` not ending in `Tests` in the Xcode project |
| `assetlinks.json` | Android (App Links) | Android has domains, the package is known (`package`, else the Gradle `applicationId`) and `sha256-cert-fingerprints` is set |

**Where they go.** When the app has a web version (`web/index.html` exists), into `web/.well-known/`: `flutter build web` copies them, so the site serves them. Otherwise into `build/spring/well-known/`, for you to upload to the domain.

**The whole site opens the app.** Apple's file lists one component per `exclude` pattern with `"exclude": true`, then `"/": "*"` for everything else. A Spring pattern becomes Apple's pattern: a variable or `**` becomes `*` (`/admin/**` is `/admin/*`, `/books/{isbn}/notes` is `/books/*/notes`, `/docs/{*path}` is `/docs/*`). Android cannot exclude paths of a verified domain, so on Android an excluded link still opens the app, which shows its first screen, as it does for a screen with `@RouteInfo(link: false)`.

When something is missing, the build warns and skips that file:

```text
The iOS app id (Team ID and bundle ID) is unknown: set spring.flutter.navigation.deep-links.app-id in application-ios.yml (ABCDE12345.com.example.app); web/.well-known/apple-app-site-association is not written.
```

```text
Android App Links need the package and the SHA-256 fingerprints of the signing keys (spring.flutter.navigation.deep-links.package, spring.flutter.navigation.deep-links.sha256-cert-fingerprints in application-android.yml); web/.well-known/assetlinks.json is not written, so Android does not verify the domain.
```

The domain files are rewritten only when their content changes. They are not removed when the domains go away.

## A login redirect on the same scheme

An OAuth2 login in the app returns through a redirect URI, often on a custom scheme. When a `redirect-uri` in any config file uses the deep links' scheme, the build warns: the login window and the app would both claim those links.

```text
spring.flutter.navigation.deep-links.scheme "neonbooks" is also the scheme of a login redirect (redirect-uri); the login window and the app would both claim its links. Give the deep links a scheme of their own.
```

## Rebuilding

A second build with the same properties changes nothing. Change a property and build again: each block is replaced, or removed when its platform no longer has deep links. Remove all `deep-links` properties and every block goes, markers included, leaving the files as they were before.
