ディープリンク

ディープリンクとは、アプリの外からアプリをあるルートで開くリンクです。neonbooks://catalog/books/1 (アプリ独自のスキーム) や、https://books.example.com/catalog/books/1 (アプリのドメイン。iOS では Universal Links、Android では App Links) です。各プラットフォームは、どのリンクがアプリに属するかを自身のファイルから知ります。ビルダー spring_flutter_deep_links は、spring_boot_starter_flutter_navigation のプロパティ spring.flutter.navigation.deep-links.* からそれらのファイルを書き、各ドメインが配信しなければならない二つのファイルも書き出します。

使う理由

手作業では、一つのディープリンクの設定に、三つの形式の四つのファイルが必要です。iOS と macOS のスキームのための plist の配列、iOS のドメインのためのエンタイトルメント、Android マニフェストの二つのインテントフィルター、そして Web サーバー上の二つの JSON ファイルです。それらは互いに、そしてアプリのルートと一致していなければならず、アプリが変わるにつれてずれていきます。

ビルダーを使えば、スキームとドメインを、アプリがすでに読んでいる設定に一度書くだけです。ビルドは実行のたびにそれらからすべてのプラットフォームのファイルを書き、プロパティがなくなると書いたものを取り除きます。アプリが除外するルートは、Apple のファイルでも除外されます。

例

# 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/**'] # これらのリンクは最初の画面を開く
# lib/resources/application-android.properties
# 署名鍵のフィンガープリントが必要なのは Android だけ。
spring.flutter.navigation.deep-links.sha256-cert-fingerprints=AB:CD:EF

dart run build_runner build の後、ios/Runner/Info.plist の最後の </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 はドメインを受け取ります。

<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 は、メインアクティビティの末尾にブロックを受け取ります。

        <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 は CFBundleURLTypes の部分 (スキーム) だけを受け取ります。そして、アプリに Web 版がある (web/index.html が存在する) ので、二つのドメインのファイルは 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"
      ]
    }
  }
]

アプリ ID ABCDE12345.com.example.books は Xcode プロジェクト (DEVELOPMENT_TEAM と PRODUCT_BUNDLE_IDENTIFIER) から、パッケージ com.example.books は android/app/build.gradle.kts の applicationId から来ています。JSON の上のコメントはファイル名を示すだけで、ファイル自体にはコメントはありません。

プロパティ

すべてのキーは spring.flutter.navigation.deep-links の下にあります。

キー 型 デフォルト ビルドがそれで行うこと
enabled true / false true false では、それを読むプラットフォームには何も書かず、以前に書いたブロックを取り除きます。プラットフォームのプロファイルのファイル (application-macos.yml) に置くと、そこでだけリンクを無効にできます。
scheme URL スキーム なし アプリ独自のスキーム。iOS と macOS の Info.plist の CFBundleURLTypes、Android のインテントフィルターになります。検証されないので、別のアプリが同じスキームを主張する可能性があります。
domains ホスト名のリスト なし https のリンクがアプリを開くドメイン。Runner.entitlements の applinks: エントリー、Android の検証済み (autoVerify) のインテントフィルター、二つのドメインのファイルになります。
exclude パスパターンのリスト なし リンクがその画面を開かない Spring のパスパターン。apple-app-site-association の "exclude": true のコンポーネントになります。
app-id TEAMID.bundle.id ios/Runner.xcodeproj/project.pbxproj から apple-app-site-association のアプリ ID。application-ios.yml で設定します。
package Android のパッケージ android/app/build.gradle.kts の applicationId、なければ build.gradle assetlinks.json の package_name。
sha256-cert-fingerprints リスト なし Android アプリの署名に使う鍵 (アップロード鍵と Google Play のもの) の SHA-256 フィンガープリント。これがなければ assetlinks.json は書き出されません。

リストはどの形でも書けます。YAML のリスト、インデックス付きのキー (domains[0]=...)、カンマ区切りの一つの値 (domains=a.example.com, b.example.com) です。

実行時に、ナビゲーションのスターターが読むのは exclude だけです。その他のキーはビルドのためにあります。

設定の読み方

ビルドは設定を プラットフォームごとに一度、そのプラットフォームでアプリが読むのと同じように 読みます。アプリは起動時にプラットフォームのプロファイルを追加するので、ビルドも同じことを行います。

プラットフォーム 読まれるプロファイル 書き出されるファイル
iOS mobile、次に ios ios/Runner/Info.plist、ios/Runner/Runner.entitlements、apple-app-site-association
Android mobile、次に android android/app/src/main/AndroidManifest.xml、assetlinks.json
macOS desktop、次に macos macos/Runner/Info.plist

各プラットフォームについて、ビルドはアプリが使うのと同じ設定ローダーで lib/resources/ のファイルを読み込みます。application.*、次にそれらのプロファイルのファイルをその順で (application-mobile.yml、次に application-ios.yml。アプリと同じく、プラットフォーム自身のファイルが優先されます)、それらの中で spring.profiles.active が指定するプロファイルのファイル、spring.config.import が指定する resources: のファイルです。環境変数や --dart-define だけが与えられる値はビルド時には不明です。デフォルト付きのプレースホルダー (${APP_SCHEME:neonbooks}) はデフォルトを使い、それに依存するプロファイル名やインポートの場所は警告とともに除外されます。すべての Web とプラットフォームのビルダーに共通する詳細は ビルドが読むプロパティ を参照してください。

そのため、application-android.properties の値は Android にだけ適用され、application-macos.yml の enabled: false は macOS のブロックを取り除き、iOS と Android は自身のブロックを保ちます。キーが application-mobile.yml と application-ios.yml の両方にある場合、アプリと同じく、iOS では iOS のファイルが優先されます。

Windows と Linux は何も受け取りません。ビルダーにはそれらの対象がありません。

ビルダーが動くとき

spring_flutter_deep_links は、ジェネレーターに依存するすべてのパッケージに適用され (auto_apply: dependents)、出力を宣言しません。変更するファイルはアプリのものだからです。ビルドのたびに:

  1. lib/resources/ のテキストファイルを読みます。どれにも deep-links や deepLinks が含まれていなければ、設定の読み込みはまったく行わず、すべてのプラットフォームを「ディープリンクなし」とみなします。
  2. そうでなければ、プラットフォームごとに設定を読みます (上記)。プラットフォームにディープリンクがあるのは、enabled が false でなく、scheme または一つ以上のドメインが設定されている場合です。
  3. 存在する対象ファイルごとに、マーカーの間に新しいブロックを入れるか、古いものを置き換えるか、プラットフォームにディープリンクがなければそれを取り除きます。存在しないファイルはスキップされます。ビルドが Info.plist やマニフェストを作ることはありません。
  4. ドメインがあれば、ドメインのファイルを書き出します (下記)。

純粋な Dart サーバーのような、ディープリンクのないパッケージには触れません。挿入するものも、取り除く古いブロックもないからです。

ブロックとそのマーカー

すべてのブロックは二つの XML コメントの間にあります。

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

sha= の値は、ブロックの本体の SHA-256 の最初の 12 桁の 16 進数です。これにより、ビルドは自身のブロックと誰かが編集したブロックを見分けられます。

ブロックの置き場所。 最初は、ブロックはアンカーより一段深いインデントで挿入されます。ファイルがタブでインデントされていればタブを、そうでなければ四つのスペースを使います。

ファイル アンカー
Info.plist、Runner.entitlements </plist> が続く最後の </dict> の前
AndroidManifest.xml android.intent.category.LAUNCHER のインテントを持つアクティビティ (Flutter の MainActivity) を閉じる </activity> の前

その後は、ブロックはその場所で置き換えられます。

各ブロックの内容。

ファイル 内容
ios/Runner/Info.plist FlutterDeepLinkingEnabled = true (Flutter がリンクをルーターに渡すように)。スキームが設定されていれば、スキームを持つ CFBundleURLTypes
ios/Runner/Runner.entitlements 各ドメインについて applinks:<domain> を持つ com.apple.developer.associated-domains
macos/Runner/Info.plist スキームを持つ CFBundleURLTypes。スキームがなければブロックなし
AndroidManifest.xml flutter_deeplinking_enabled のメタデータ。スキームのためのインテントフィルター。ドメインごとに一つの <data android:host> を持つ、https のための autoVerify のインテントフィルター

Runner.entitlements は存在しなければなりません。 Xcode は、Runner ターゲットに Associated Domains のケイパビリティを追加したときにそれを作ります。ビルドは Xcode プロジェクトを編集しないので、そのファイルを作ることもリンクすることもできません。ドメインが設定されていてそのファイルがない場合、ビルドは警告します。

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.

エラー

次の問題はビルドを失敗させ (重大なログ)、ファイルはそのまま残ります。

問題 メッセージ (短縮)
ブロックが手で編集された: その本体がもはや 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.
ブロックが書くキーが、ブロックの外でもファイルにある (たとえば自分の CFBundleURLTypes)。プラットフォームが読むのは一つだけ <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.
アンカーがない (</dict></plist> がない、ランチャーのアクティビティがない) no place for the deep links (the end of the main activity not found).
scheme が URL スキームでない (英字で始まり、その後に英字、数字、+、-、. が続かなければならない) spring.flutter.navigation.deep-links.scheme "..." is no URL scheme ...
scheme が http または https ... scheme cannot be https: put the site in spring.flutter.navigation.deep-links.domains instead.
ドメインにスキームやパスがある (https://books.example.com) ... domains: "https://books.example.com" is no host name (no scheme, no path: books.example.com).

間違ったスキームやドメインが止めるのは、そのプラットフォームのディープリンクだけです。ワイルドカードのドメイン (*.example.com) は受け付けられます。

編集されたブロックを変更するには、変更をプロパティに移し、ブロックを二つのマーカーごと削除し、再びビルドします。

各ドメインが配信するファイル

プラットフォームがドメインを信頼するのは、ドメインが https://<domain>/.well-known/ の下でファイルを配信して確認した場合だけです。

ファイル 対象 書き出される条件
apple-app-site-association iOS (Universal Links) iOS にドメインがあり、アプリ ID がわかっている: app-id、なければ Xcode プロジェクトの DEVELOPMENT_TEAM と、Tests で終わらない最初の PRODUCT_BUNDLE_IDENTIFIER
assetlinks.json Android (App Links) Android にドメインがあり、パッケージがわかっていて (package、なければ Gradle の applicationId)、sha256-cert-fingerprints が設定されている

置き場所。 アプリに Web 版がある (web/index.html が存在する) 場合は web/.well-known/ に置かれます。flutter build web がそれらをコピーするので、サイトがそれらを配信します。そうでなければ build/spring/well-known/ に置かれ、ドメインにアップロードするのは自分です。

サイト全体がアプリを開きます。 Apple のファイルは、exclude のパターンごとに "exclude": true のコンポーネントを一つ列挙し、その後に他のすべてのための "/": "*" を置きます。Spring のパターンは Apple のパターンになります。変数や ** は * になります (/admin/** は /admin/*、/books/{isbn}/notes は /books/*/notes、/docs/{*path} は /docs/*)。Android は検証済みのドメインのパスを除外できないので、Android では除外されたリンクもアプリを開き、@RouteInfo(link: false) の画面と同じく、アプリは最初の画面を表示します。

何かが足りない場合、ビルドは警告し、そのファイルをスキップします。

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.

ドメインのファイルは、内容が変わったときにだけ書き直されます。ドメインがなくなっても取り除かれません。

同じスキームでのログインのリダイレクト

アプリでの OAuth2 ログインは、リダイレクト URI を通して戻ってきます。それはしばしば独自のスキームです。いずれかの設定ファイルの redirect-uri がディープリンクのスキームを使っている場合、ビルドは警告します。ログインウィンドウとアプリの両方がそれらのリンクを主張してしまうからです。

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.

再ビルド

同じプロパティでの二回目のビルドは何も変えません。プロパティを変えて再びビルドすると、各ブロックは置き換えられるか、そのプラットフォームにもうディープリンクがなければ取り除かれます。すべての deep-links プロパティを取り除くと、マーカーも含めてすべてのブロックがなくなり、ファイルは以前の状態に戻ります。