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

# 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
# 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>:

	<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:

<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:

        <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/:

// web/.well-known/apple-app-site-association
{
  "applinks": {
    "details": [
      {
        "appIDs": [
          "ABCDE12345.com.example.books"
        ],
        "components": [
          {
            "/": "/checkout",
            "exclude": true
          },
          {
            "/": "/admin/*",
            "exclude": true
          },
          {
            "/": "*"
          }
        ]
      }
    ]
  }
}
// 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 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:

<!-- 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:

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:

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.
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.

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.