iOS: Universal Links#

https://example.com/items/123 のような 通常の HTTPS URL が、アプリがインストールされていればアプリで開かれ、未インストールであれば Safari で Web ページとして開かれる仕組み。

• ドメインの所有者であることを Apple に検証させる
• 検証ファイル: https://example.com/.well-known/apple-app-site-association (AASA)
• AASA は Content-Type が application/json、リダイレクトなし、HTTPS 必須

AASA の例:

1
{
2
  "applinks": {
3
    "apps": [],
4
    "details": [
5
      {
6
        "appID": "TEAMID.com.example.myapp",
7
        "paths": [ "/items/*", "/users/*", "NOT /admin/*" ]
8
      }
9
    ]
10
  }
11
}

• appID は <TeamID>.<BundleID> の形式
• iOS 13 以降は details の appIDs(複数) と components を使う新フォーマットも推奨

iOS 側設定:

• Xcode の Signing & Capabilities で Associated Domains を追加
• applinks:example.com を登録

Android: App Links#

https://example.com/items/123 のような HTTPS URL をアプリで処理する仕組み。Android 12 以降は デフォルトで未検証のリンクはアプリで開かれなくなった ので、Web 検証が必須に近い扱いとなっている。

• 検証ファイル: https://example.com/.well-known/assetlinks.json
• アプリ署名証明書の SHA-256 fingerprint を記載

assetlinks.json の例:

1
[
2
  {
3
    "relation": ["delegate_permission/common.handle_all_urls"],
4
    "target": {
5
      "namespace": "android_app",
6
      "package_name": "com.example.myapp",
7
      "sha256_cert_fingerprints": [
8
        "AA:BB:CC:..."
9
      ]
10
    }
11
  }
12
]

• Google Play App Signing を使っている場合は Play Console の「アプリの署名」から アプリ署名鍵の SHA-256 を取得する(アップロード鍵ではない)
• 検証コマンド:

1
adb shell pm verify-app-links --re-verify com.example.myapp
2
adb shell pm get-app-links com.example.myapp

BundleID/カスタム URI スキーム (myapp://...)#

myapp://item/123 のようにアプリ独自のスキームを宣言してアプリを開く方式。 歴史的に最初に使われたディープリンクで、今でも OAuth コールバックなど一部用途では現役。

Deferred Deep Link (DDL)#

通常のディープリンクは「アプリがインストール済み」が前提だが、Deferred Deep Link は 未インストール時のフローも含めて目的画面まで誘導する 仕組み。

典型的なフロー:

1. ユーザーが広告/SNS のリンクを踏む
2. アプリ未インストールなので App Store / Play Store に誘導
3. インストール後、初回起動時に「本来開きたかった画面」へ自動遷移
4. ついでにインストールアトリビューション(どの広告から来たか)も取得

実装はストア側で URL パラメータを保持できないため、サードパーティ SDK の利用が一般的。

• AppsFlyer
• Adjust
• Branch.io
• Firebase Dynamic Links (※ 2025/8/25 にサービス終了済み)

Firebase Dynamic Links が終了したことで、現状新規構築する場合は AppsFlyer / Adjust / Branch などの有償 SDK か、自前実装(初回起動時にクリップボードや IP+UserAgent でマッチング)するしかない。 自前実装は精度・プライバシー両面で難があるため、本格運用では SDK 採用が現実的。

Dart 側: app_links を使う#

1
import 'package:app_links/app_links.dart';
2
import 'package:flutter/material.dart';
3

4
class DeepLinkHandler extends StatefulWidget {
5
  final Widget child;
6
  const DeepLinkHandler({super.key, required this.child});
7

8
  @override
9
  State<DeepLinkHandler> createState() => _DeepLinkHandlerState();
10
}
11

12
class _DeepLinkHandlerState extends State<DeepLinkHandler> {
13
  final _appLinks = AppLinks();
14

15
  @override
16
  void initState() {
17
    super.initState();
18
    _initDeepLinks();
19
  }
20

21
  Future<void> _initDeepLinks() async {
22
    // 起動時に URI で開かれた場合
23
    final initialUri = await _appLinks.getInitialAppLink();
24
    if (initialUri != null) {
25
      _handleUri(initialUri);
26
    }
27

28
    // 起動中にリンクで叩かれた場合
29
    _appLinks.uriLinkStream.listen(_handleUri);
30
  }
31

32
  void _handleUri(Uri uri) {
33
    // /items/123 のようなパスを解析してナビゲーション
34
    debugPrint('deep link: $uri');
35
  }
36

37
  @override
38
  Widget build(BuildContext context) => widget.child;
39
}

go_router を使う場合は GoRouter の redirect や routes で uri.path をそのままハンドリングできるので、より簡潔に書ける。

iOS 側設定#

1. ios/Runner/Runner.entitlements に Associated Domains を追加

1
<key>com.apple.developer.associated-domains</key>
2
<array>
3
  <string>applinks:example.com</string>
4
</array>

2. Xcode の Signing & Capabilities でも同じ設定を行う
3. https://example.com/.well-known/apple-app-site-association を HTTPS かつ Content-Type application/json かつリダイレクトなし で配置
4. カスタムスキームも併用する場合は Info.plist に追加

1
<key>CFBundleURLTypes</key>
2
<array>
3
  <dict>
4
    <key>CFBundleURLName</key>
5
    <string>com.example.myapp</string>
6
    <key>CFBundleURLSchemes</key>
7
    <array>
8
      <string>myapp</string>
9
    </array>
10
  </dict>
11
</array>

Android 側設定#

android/app/src/main/AndroidManifest.xml の <activity> に intent-filter を追加:

1
<activity
2
    android:name=".MainActivity"
3
    android:exported="true"
4
    ... >
5

6
    <!-- App Links (HTTPS) -->
7
    <intent-filter android:autoVerify="true">
8
        <action android:name="android.intent.action.VIEW" />
9
        <category android:name="android.intent.category.DEFAULT" />
10
        <category android:name="android.intent.category.BROWSABLE" />
11
        <data android:scheme="https"
12
              android:host="example.com"
13
              android:pathPrefix="/items" />
14
    </intent-filter>
15

16
    <!-- カスタムスキーム (任意) -->
17
    <intent-filter>
18
        <action android:name="android.intent.action.VIEW" />
19
        <category android:name="android.intent.category.DEFAULT" />
20
        <category android:name="android.intent.category.BROWSABLE" />
21
        <data android:scheme="myapp" />
22
    </intent-filter>
23
</activity>

• android:autoVerify="true" を付けることで App Links として OS が assetlinks.json を自動取得・検証する
• Play Store にアップロード後は アプリ署名鍵 の SHA-256 を assetlinks.json に登録する必要がある(ローカルビルド時のデバッグ署名とは別物)

動作確認コマンド#

1
# iOS Simulator
2
xcrun simctl openurl booted "https://example.com/items/123"
3
xcrun simctl openurl booted "myapp://item/123"
4

5
# Android (実機 / エミュレータ)
6
adb shell am start -a android.intent.action.VIEW -d "https://example.com/items/123" com.example.myapp
7
adb shell am start -a android.intent.action.VIEW -d "myapp://item/123" com.example.myapp

1. アプリ未起動 / 起動済みで挙動が違う#

• コールドスタート: getInitialAppLink() で取得
• バックグラウンドから復帰: uriLinkStream (StreamSubscription) で受け取り

両方を実装しないと「起動済みのときだけ動かない」「初回だけ動かない」というバグが起きやすい。

2. ナビゲーションスタックの設計#

ディープリンクで深い階層に直接飛ばす場合、戻るボタンの遷移先がない、というのが頻出問題。

• 例: 商品詳細にディープリンクで飛んできたユーザーが「戻る」を押したらアプリが落ちる
• 対策: ホーム→商品一覧→詳細、のようにスタックを擬似的に積む or go_router の initialLocation 設計をする

3. ログインが必要な画面への遷移#

ディープリンクで飛ばしたい画面が認証必須の場合、

1. リンク受信 → 認証状態チェック
2. 未認証ならログイン画面へ、ログイン後に本来の URI へ復元

という「保留 URI」の管理が必要。go_router の redirect と state.matchedLocation が便利。

4. AASA / assetlinks.json のキャッシュ#

• iOS は AASA を Apple の CDN 経由でキャッシュ してから端末に配布する仕組みのため、自社サーバの AASA を更新しても すぐには端末に反映されない
• 開発中は アプリの再インストール と、設定 > 開発者 > Associated Domains Development の有効化が役立つ
• Android は adb shell pm verify-app-links --re-verify で再検証可能

1
https://app-site-association.cdn-apple.com/a/v1/<domain-name>

1
# Apple CDN にキャッシュされた example.com の AASA を確認
2
curl -sS https://app-site-association.cdn-apple.com/a/v1/example.com | jq .
3

4
# 自社サーバ上の AASA との差分を見たい場合
5
diff \
6
  <(curl -sS https://example.com/.well-known/apple-app-site-association | jq -S .) \
7
  <(curl -sS https://app-site-association.cdn-apple.com/a/v1/example.com   | jq -S .)

5. 検証ツール#

• iOS: Apple の App Search API Validation Tool
• Android: Asset Links Tool / Statement List Generator

6. プライバシーへの配慮#

クリップボード経由で deferred deep link を実装すると、iOS 14 以降は クリップボードアクセス通知 がユーザーに表示されたり、App Tracking Transparency (ATT) の同意が必要になるケースがある。3rd party SDK を使う場合も、SDK が裏でやっている挙動を把握しておく。

7. ブラウザ → アプリ起動の “クッション”#

SNS の WebView (Instagram, LINE 内ブラウザ等) からは Universal Links が WebView 内で開いてしまい、アプリに飛ばない ことがある。 これに対しては中継ページで「アプリで開く」ボタンを置く、intent:// URI (Android Chrome) を使う、などのフォールバックを検討する。