ディープリンクのトラブルシューティング

このページでは、iOSにおける一般的なディープリンクの問題を診断する方法について説明します。適切なリンクタイプの選び方については、iOSディープリンクガイドを参照してください。実装の詳細については、ディープリンクを参照してください。

ここから始めましょう: 症状を確認する

以下のテーブルで発生している動作を見つけ、該当セクションの手順に従ってください。どのセクションが該当するか分からない場合は、標準調査パスを使用してください。

標準的な調査パス

すべてのディープリンクの問題に対して、このワークフローを使用してください。ステップ1から開始します。

1. Braze の外部でリンクをテストします。カスタムスキームの場合、ターミナルで xcrun simctl openurl booted "<URL>" を実行します（例: xcrun simctl openurl booted "myapp://products/123"）。ユニバーサルリンクの場合、物理デバイスのメモアプリにURLを貼り付けてタップします。
2. 詳細ログを有効にし、問題を再現します。Opening '<URL>': エントリで channel、useWebView、isUniversalLink を確認します。
3. ユニバーサルリンクの場合、AASAファイルと Associated Domains エンタイトルメントを検証します。
4. メールリンクの場合、クリックトラッキングドメインが有効なAASAファイルをホストしていることを確認します。
5. BrazeDelegate.braze(_:shouldOpenURL:) を実装している場合、すべてのチャネルでリンクが一貫して処理されていることを確認します。
6. 問題が解決しない場合は、詳細ログとリンクURLを添えて Braze サポートに連絡してください。

カスタムスキームのディープリンクが正しいビューを開かない

症状: カスタムスキームのディープリンク（例: myapp://products/123）でアプリは開きますが、意図した画面に遷移しません。

1. スキームが登録されていることを確認します。 Xcodeで、Info.plistのCFBundleURLTypesにスキームが登録されているか確認してください。
2. ハンドラーを確認します。 application(_:open:options:)にブレークポイントを設定し、呼び出されていることとurlパラメーターの内容を確認してください。
3. リンクを単独でテストします。 ターミナルから以下のコマンドを実行して、Braze外でディープリンクをテストしてください:

   1
   xcrun simctl openurl booted "myapp://products/123"
   

   ここでリンクが動作しない場合、問題はBrazeではなくアプリのURL処理にあります。

4. URLの形式を確認します。 キャンペーンのURLがハンドラーの期待する形式と一致しているか確認してください。よくある間違いとして、パスコンポーネントの欠落や大文字・小文字の不一致があります。

ユニバーサルリンクがアプリではなくSafariで開く

症状： ユニバーサルリンク（例：https://myapp.com/products/123）がアプリではなくSafariで開きます。

Associated Domainsエンタイトルメントを確認する

Xcodeで、アプリターゲット > Signing & Capabilities に移動し、Associated Domains の下にapplinks:yourdomain.comがリストされていることを確認してください。

AASAファイルを検証する

Apple App Site Association（AASA）ファイルは、以下のいずれかの場所にホストされている必要があります：

• https://yourdomain.com/.well-known/apple-app-site-association
• https://yourdomain.com/apple-app-site-association

以下を確認してください：

• ファイルが有効な証明書を使用してHTTPS経由で提供されていること。
• Content-Typeがapplication/jsonであること。
• ファイルサイズが128 KB未満であること。
• appIDがチームIDとバンドルIDに一致していること（例：ABCDE12345.com.example.myapp）。
• pathsまたはcomponents配列に、期待するURLパターンが含まれていること。

AASAの検証は、Appleの検索検証ツールを使用するか、以下のコマンドを実行して行えます：

1
swcutil dl -d yourdomain.com

AppDelegateを確認する

application(_:continue:restorationHandler:)がAppDelegateに実装されており、NSUserActivityを正しく処理していることを確認してください：

1
2
3
4
5
6
7
8
9
10
func application(_ application: UIApplication,
                 continue userActivity: NSUserActivity,
                 restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
  guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
        let url = userActivity.webpageURL else {
    return false
  }
  // Handle the URL
  return true
}

Braze SDKの設定を確認する

Brazeから配信されるプッシュ通知、アプリ内メッセージ、またはContent Cardsからユニバーサルリンクを使用している場合、forwardUniversalLinksが有効になっていることを確認してください：

1
2
let configuration = Braze.Configuration(apiKey: "<BRAZE_API_KEY>", endpoint: "<BRAZE_ENDPOINT>")
configuration.forwardUniversalLinks = true

注

ユニバーサルリンクの転送には、アプリケーションのエンタイトルメントへのアクセスが必要です。シミュレーターで実行している場合、これらのエンタイトルメントは直接利用できません。シミュレーターでテストするには、Copy Bundle Resources ビルドフェーズに.entitlementsファイルを追加してください。

長押しの問題を確認する

ユニバーサルリンクを長押しして開くを選択すると、iOSがそのドメインのユニバーサルリンクの関連付けを「解除」する場合があります。これはiOSの既知の動作です。リセットするには、リンクをもう一度長押しして[アプリ名]で開くを選択してください。

メールからのディープリンクでアプリが開かない

症状: メール内のリンクがユニバーサルリンクを通じてアプリを開きません。

メールのリンクはメールサービスプロバイダー (ESP) のクリックトラッキングシステムを経由するため、リンクがトラッキングドメインでラップされます（例: https://click.yourdomain.com/...）。メールからユニバーサルリンクを機能させるには、プライマリドメインだけでなく、クリックトラッキングドメインにもAASAファイルを設定する必要があります。

クリックトラッキングドメインのAASAを確認する

1. メールサービスプロバイダー (ESP) の設定（SendGrid、SparkPost、またはAmazon SES）からクリックトラッキングドメインを特定します。
2. https://your-click-tracking-domain/.well-known/apple-app-site-association にAASAファイルをホストします。
3. クリックトラッキングドメインのAASAファイルに、同じappIDと有効なパスパターンが含まれていることを確認します。

メールサービスプロバイダー (ESP) 固有の設定手順については、ユニバーサルリンクとApp Linksを参照してください。

リダイレクトチェーンを確認する

一部のメールサービスプロバイダー (ESP) は、クリックトラッキングURLから最終URLへのリダイレクトを実行します。ユニバーサルリンクは、iOSが最初のドメイン（クリックトラッキングドメイン）をアプリに関連付けられたものとして認識した場合にのみ機能します。リダイレクトがAASAチェックをバイパスすると、リンクはSafariで開かれます。

テスト方法:

1. 自分宛てにテストメールを送信します。
2. リンクを長押ししてURLを確認します — これがクリックトラッキングURLです。
3. このドメインに有効なAASAファイルがあることを確認します。

すべてのメールリンクがアプリを開いてしまう

症状: メール内のすべてのリンクがアプリを開いてしまい、ブラウザで開くことを想定しているリンクも含まれます。

クリックトラッキングドメインのAASAファイルで、そのドメイン上のすべてのURLに一致するpaths（例: * や /*）が使用されています。そのため、iOSはクリックトラッキングされたすべてのメールリンクをユニバーサルリンクとして処理します。

pathsをアプリで開くべきURLのみに制限してください。SendGridの場合は、/uni/に一致させ、該当するリンクにのみuniversal="true"を追加してください。

AndroidのpathPrefix値を含むESP固有の設定については、ユニバーサルリンクとApp Linksを参照してください。

ディープリンクがプッシュでは動作するがアプリ内メッセージでは動作しない（またはその逆）

症状: 同じディープリンクが、あるBrazeチャネルでは動作するが、別のチャネルでは動作しません。

BrazeDelegateを確認する

BrazeDelegate.braze(_:shouldOpenURL:) を実装している場合、チャネル間でリンクが一貫して処理されているか確認してください。context パラメーターにはソースチャネルが含まれています。特定のチャネルからのリンクを誤ってフィルタリングしている条件分岐がないか確認してください。

詳細ログを有効にする

詳細ログを有効にして、問題を再現してください。Opening ログエントリを確認します：

1
2
3
4
Opening '<URL>':
- channel: <SOURCE_CHANNEL>
- useWebView: <true/false>
- isUniversalLink: <true/false>

動作するチャネルと動作しないチャネルのログ出力を比較してください。useWebView や isUniversalLink の違いは、SDKがリンクをどのように異なる方法で解釈しているかを示しています。

カスタム表示デリゲートを確認する

カスタムのアプリ内メッセージ表示デリゲートやContent Cardsクリックハンドラーを使用している場合、リンクイベントが正しくBraze SDKに渡されて処理されているか確認してください。

「アプリ内でWeb URLを開く」で空白ページや壊れたページが表示される

症状： アプリ内でWeb URLを開くを選択すると、WebViewが空白または壊れた状態で表示されます。

1. URLがHTTPSを使用していることを確認します。 SDKのWebViewはATS準拠のURLを必要とします。HTTPリンクはサイレントに失敗します。
2. Content Security Policyヘッダーを確認します。 対象のWebページがX-Frame-Options: DENYまたは制限的なContent-Security-Policyを設定している場合、WebViewでのレンダリングがブロックされます。
3. カスタムスキームへのリダイレクトを確認します。 Webページがカスタムスキーム（例：myapp://）にリダイレクトする場合、WebViewはそれを処理できません。
4. SafariでURLをテストします。 デバイス上のSafariでページが読み込まれない場合、WebViewでも読み込まれません。

BranchとBrazeのトラブルシューティング

Branchをリンクプロバイダーとして使用している場合：

BrazeDelegateがBranchにルーティングしていることを確認する

BrazeDelegateがBranchリンクをインターセプトし、Branch SDKに渡す必要があります。以下を確認してください：

1
2
3
4
5
6
7
8
9
func braze(_ braze: Braze, shouldOpenURL context: Braze.URLContext) -> Bool {
  if let host = context.url.host, host.contains("app.link") {
    // Route to Branch SDK
    Branch.getInstance.handleDeepLink(context.url)
    return false
  }
  // Let Braze handle other links
  return true
}

shouldOpenURLがBranchリンクに対してtrueを返す場合、BrazeはBranchにルーティングせず直接処理します。

Branchリンクドメインを確認する

BrazeDelegate内のBranchドメインが、実際のBranchリンクドメインと一致していることを確認してください。Branchはいくつかのドメイン形式を使用します：

• yourapp.app.link（デフォルト）
• yourapp-alternate.app.link（代替）
• カスタムドメイン（Branchダッシュボードで設定されている場合）

両方のSDKのログを有効にする

リンクがチェーンのどこで途切れているかを診断するには：

1. Brazeの詳細ログを有効にします。SDKがリンクを受信したことを確認するために、Opening '<URL>':エントリを探してください。
2. Branchテストモードを有効にします。Branchダッシュボードでリンククリックイベントを確認してください。
3. Brazeがリンクを記録しているのにBranchがクリックを認識しない場合、BrazeDelegateのルーティングロジックに問題がある可能性が高いです。

Branchダッシュボードの設定を確認する

Branchダッシュボードで以下を確認してください：

• アプリのバンドルIDとチームIDがXcodeプロジェクトと一致していること。
• Associated DomainsにBranchリンクドメインが含まれていること。
• BranchのAASAファイルが有効であること（Branchはapp.linkドメイン上で自動的にホストします）。

Branchリンクを単独でテストする

問題を切り分けるために、Brazeの外でBranchリンクをテストしてください：

1. デバイスのSafariでBranchリンクを開きます。アプリが開かない場合、問題はBranchまたはAASAの設定にあり、Brazeの問題ではありません。
2. Branchリンクをメモアプリに貼り付けてタップします。ユニバーサルリンクは、Safariのアドレスバーからよりもメモアプリからの方が確実に動作します。

一般的なデバッグのヒント

詳細ログを使用する

詳細ログを有効にすることで、SDKがリンクをどのように処理しているかを正確に確認できます。確認すべき主なエントリは以下のとおりです。

これらのログの読み方について詳しくは、詳細ログの読み方を参照してください。

リンクを単独でテストする

Brazeを通じてテストする前に、ディープリンクまたはユニバーサルリンクが単独で動作するか確認してください。

• カスタムスキーム: ターミナルで xcrun simctl openurl booted "myapp://path" を実行します。
• ユニバーサルリンク: 実機のメモアプリにURLを貼り付けてタップします。Safariのアドレスバーからはテストしないでください。iOSでは入力されたURLとタップされたリンクの処理が異なります。
• Branchリンク: 実機のメモアプリからBranchリンクを開きます。

実機でテストする

ユニバーサルリンクはiOSシミュレーターでのサポートが限定的です。正確な結果を得るには、必ず実機でテストしてください。シミュレーターでテストする必要がある場合は、.entitlements ファイルを Copy Bundle Resources ビルドフェーズに追加してください。