Skip to content

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

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

カスタムスキームのディープリンク（例：myapp://products/123）がアプリを開くものの、意図した画面に遷移しない場合：

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

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

    ここでリンクが機能しない場合、問題はアプリのURL処理にあり、Brazeの問題ではありません。

  4. URLの形式を確認します。 Campaignに設定されたURLが、ハンドラーが期待する形式と一致しているか確認してください。よくある間違いには、パスコンポーネントの欠落や大文字小文字の誤りがあります。

ユニバーサルリンク（例：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

長押しの問題を確認する

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

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

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

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

ESP固有の設定手順については、ユニバーサルリンクとアプリリンクを参照してください。

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

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

テスト方法：

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

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にルーティングせず直接処理します。

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ドメイン上で自動的にホストします）。

問題を切り分けるために、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シミュレーターでは限定的なサポートしかありません。正確な結果を得るために、必ず物理デバイスでテストしてください。シミュレーターでテストする必要がある場合は、Copy Bundle Resources ビルドフェーズに.entitlementsファイルを追加してください。
New Stuff!