ディープリンク & ディファードディープリンク(DDL) トラブルシューティングガイド - FAQ

考えられる原因:

• ディープリンクハンドラーがアプリに完全に実装されていない
• アプリが Singular SDK から解決されたディープリンクを読み取っていない
• DDL の前提条件が完全に満たされていない

確認すべき事項:

1. ディープリンクを（Singular リンクを経由せずに）直接テストします。
2. SingularLinkHandler が実装されており、以下を正しく読み取っているか確認します:
   • getDeeplink()
   • isDeferred()
   • getPassthrough()
3. DDL が有効になっているか確認します ( should_index_ddl = true )。

直接テストしたときはディープリンクが機能するが、Singular リンクを通じては機能しない場合、問題はほぼ常にリンク自体ではなく、アプリのナビゲーションロジックにあります。

iOS（Universal Links）の場合: これは通常、Universal Link の構成が不完全であることを意味します。以下を確認してください:

• Team ID と iOS App Scheme が Singular に正しく設定されている
• Associated Domains が Xcode に追加されている
• AASA ファイルが存在し、正しいリンク ID を含んでいる

開発/QA ビルドのヒント: 開発または QA ビルドでテストしている場合、デバイスにまだ最新の AASA ファイルがない可能性があります。デバイスを再起動した後にアプリを再インストールしてみてください。

Android の場合: これは通常、誤って構成されたインテントフィルターを示しています。以下を確認してください:

• App Links SHA256 フィンガープリントが正しく設定されている（App Links を使用している場合）
• assetlinks.json が Singular ドメインでアクセス可能である
• インテントフィルターが Singular Apps ページで構成されているものと一致している

上記のすべてが確認できても問題が続く場合、問題はディープリンクハンドラーのロジックにある可能性が最も高いです。

典型的なエラー: 「アドレスが無効なため、Safari はページを開けません。」

これが発生する理由:

• Safari には、新規ユーザーに対する特定の Universal Links の処理に既知の制限があります
• _force_redirect=1 がリンクに含まれています

これは予期された動作であり 、フローは次のように続くはずです: ユーザーがエラーを見る → OK をタップする → App Store を開くよう促される。

考えられる原因: パススルーパラメータ（ _p ）が適切に追加されていないか、URL エンコードされていません。

ベストプラクティス:

• リンクに追加する前に、常に JSON 値を URL エンコードしてください
• 次からパススルーデータを読み取ります: singularLinkParams.passthrough

パススルーデータはディープリンクとディファードディープリンクの 両方 で利用できるため、欠落している場合、問題はほぼ常にエンコードまたは取得にあります。

これが発生する理由: Singular リンクがディープリンクで作成されると、アプリがインストールされている場合は常にアプリを開こうとします。これは OS レベルで制御されます:

• iOS: AASA ファイルによって管理される
• Android: SHA256 証明書の関連付けによって管理される

後からこれをオーバーライドする方法はありません。 常にユーザーをストアに送るリンクが必要な場合は、最初からディープリンク なし で作成する必要があります。

根本原因: デバイスで Apple の iCloud Private Relay が有効になっています。

DDL が壊れる理由: Private Relay はクリックとインストールの間で IP アドレスを変更するため、クリック IP とインストール IP が一致しません — これは確率的アトリビューションを壊します。

推奨事項:

• テスト中は iCloud Private Relay を無効にしてください
• 代わりに Chrome または Safari 以外のブラウザを使用してテストしてください

これが発生する理由: リンクがディープリンクで構成されており、アプリがインストールされている場合は常にランディングページより優先されます。

重要なルール: アプリ + ディープリンクは常にランディングページより優先されます。ソーシャルランディングページは、アプリが本当に開けない場合にのみ表示されます。

考えられる原因: テストに使用しているトラッキングリンクが二重に URL エンコードされており、デバイスや Singular が解決できません。

これが発生する理由: ディープリンクパラメータ（ _dl や _p など）を含む Singular Link が特定の環境（例: Slack、メールクライアント、メッセージングツール）からコピーされると、URL が 2 回目のエンコードをされる場合があります。例えば:

• 正しい（シングルエンコード）: https://yourapp.sng.link/Xxxxx/yyyy?_dl=myapp%3A%2F%2Fstory&_p=%7B%22story_id%22%3A%22BananaStory%22%7D
• 無効（ダブルエンコード）: https%3A%2F%2Fyourapp.sng.link%2FXxxxx%2Fyyyy%3F_dl%3Dmyapp%3A%2F%2Fstory%26_p%3D%7B%22story_id%22%3A%22BananaStory%22%7D

ダブルエンコードされたリンクは正しくリダイレクトされず、その結果生じるインストールやクリックが Singular のアトリビューションログに表示されない場合があります。

確認すべき事項:

1. 常に Singular Manage Links ページから直接トラッキングリンクをコピーしてください — URL を再エンコードした可能性のある Slack メッセージや他のツールからではなく。
2. リンクが https:// で始まっているか確認してください（ https%3A%2F%2F ではなく）。URL の一番最初にパーセントエンコードされた文字が見える場合、リンク全体がダブルエンコードされています。
3. URL デコーダーツール（例: urldecoder.org ）を使用して、リンクが有効な Singular Link 形式にデコードされるか確認してください。
4. リンクを一度デコードし、その結果の URL をテストに使用してください。

問題: Samsung Internet ブラウザから Singular リンクをクリックするユーザーは、アプリがすでにインストールされていてリンクが正しく構成されている場合でも、Google Play Store にリダイレクトされることがあります。

観察された事項:

• Google Chrome: リンクは期待どおりにアプリを開きます
• Samsung Internet: 同じリンクが代わりに Play Store にリダイレクトされます

これは、リンクを Samsung Internet で直接開いても、Web ページに埋め込んでそこからクリックしても発生する可能性があります。

根本原因: Samsung Internet には、デフォルトでアプリが外部から開かれるのをブロックする組み込みのプライバシー設定があります。

• 有効な場合: ブラウザがディープリンクをブロックし、Play Store にフォールバックします
• 無効な場合: リンクはアプリを正しく開き、Chrome の動作と一致します

これが Singular の構成問題ではなくブラウザの設定問題 であることを確認しました — Android App Links と SHA-256 フィンガープリントは正しく設定されており、この設定をオフにすればリンクの動作はどこでも一貫します。

これがあなたにとって意味すること: 一部の Samsung ユーザーは、個々のブラウザのプライバシー設定によっては、アプリがインストールされていても Play Store に到達する場合があります。これは当社側でプログラム的に制御することはできません。

影響を受けるユーザーを案内したい場合: Samsung Internet がデフォルトでアプリを開くリンクをブロックする可能性があること、そして Samsung Internet のプライバシー設定で「外部アプリを開く」（または同様のもの）を有効にすると、期待されるアプリ内エクスペリエンスが復元されることを伝えることができます。

これが発生する理由: ユーザーが特定のソーシャルメディアのアプリ内ブラウザ内から Singular Link をクリックすると、ブラウザが標準の iOS Universal Links または Android App Links をブロックする場合があります。その結果、アプリは正常に開いてもディープリンクがアプリに渡されず、ユーザーが意図した目的地ではなくデフォルトのホーム画面に到達してしまいます。

これに対処するため、Singular は ソーシャルランディングページ を提供しています。これは、ディープリンクを保持し、ユーザーを正しいアプリ内の目的地に確実にルーティングするのに役立つ中間ランディングページです。

どのプラットフォームがサポートされていますか?

ソーシャルランディングページは以下をサポートしています:

• iOS
• Android（Facebook、Facebook Messenger、Facebook Messenger Lite、Instagram のアプリ内ブラウザ）
• パートナーリンク、以下を含む:
  • Facebook Web
  • TikTok Ads Web
  • X (Twitter) Web
  • Snapchat Web

ソーシャルランディングページを有効にするにはどうすればよいですか?

Singular Link を作成または編集する際に、 Social Link Settings の下で Landing Page を有効にします。

このオプションは以下で利用できます:

• Custom Source リンク
• Mobile Web-to-App リンク
• パートナーリンク

ソーシャルランディングページはいつ使用すべきですか?

サポートされているソーシャルプラットフォームを通じて web-to-app キャンペーンを実施する場合は、常にソーシャルランディングページを有効にしてください。これにより、ユーザーがアプリのホーム画面ではなく、意図したアプリ内コンテンツに誘導されるようになり、ディープリンクのエクスペリエンスが向上し、ソーシャルメディアのアプリ内ブラウザによって引き起こされる失敗したディープリンクを減らすのに役立ちます。