概要

Singular のトラッキングリンクにディープリンクとディファードディープリンクを実装し、ユーザーがキャンペーンからアプリ内の特定の画面へシームレスに移動できるようにします。

ディープリンクとは、アプリ内の特定のコンテンツを開くクリック可能なリンクです。対応すべきシナリオは 2 つあります。

• ディープリンク（ダイレクト）： ユーザーがすでにアプリをインストールしている場合。Singular Link をタップすると、アプリが正しいコンテンツで直接開きます。
• ディファードディープリンク（DDL）： ユーザーがまだアプリを持っていない場合。リンクをタップしてストアからインストールすると、初回起動時にアプリが目的のコンテンツへユーザーを誘導します。

SDK 連携では、Singular がこの処理のほとんどを自動的に行います。server-to-server（S2S）連携ではデバイス上に SDK が存在しないため、お客様のチームが 2 つの追加作業を担う必要があります。アプリが受け取ったディープリンクを Singular に渡すことと、Singular が返すディファードディープリンクを読み取ってユーザーを誘導することです。どちらも SESSION エンドポイントを通じて行われます。

GET https://s2s.singular.net/api/v1/launch

リソース： ディープリンク FAQ | Singular Links FAQ

3 つの設定の概要

ステップ 1：アプリレベルの設定

ディープリンクが機能する前に、Singular Links が OS によって iOS Universal Links および Android App Links として認識され、リンクをタップした際にブラウザではなくアプリが開くようにする必要があります。従来の URI アプリスキームはフォールバックとしてサポートされています。

詳細なプラットフォーム別の手順については正規のセットアップガイドに従い、その後で以下の各項目が完了していることを確認してください。詳細な手順は Singular Links 前提条件 および ディープリンクの設定方法 に記載されています。ここでのチェックリストは、必要な順序と、チームが最も見落としやすいポイントを示します。

設定チェックリスト：

1. リンクのサブドメインを追加 します。 Attribution > Manage Links > Manage Link Domains で追加します（例： yourbrand.sng.link ）。これは Singular Links が使用するホストです。
2. iOS — Universal Links： applinks:yourbrand.sng.link に対して Associated Domains 機能を有効にし、Apple Developer Portal から App Prefix / Team ID を Settings > Apps > [iOS app] > Show Advanced Settings にコピーします。任意で、Xcode で URL Type としてアプリスキームのフォールバックを登録できます。
3. Android — App Links： SHA-256 署名フィンガープリントを生成し（本番環境は Play Console、デバッグ環境は keytool ）、Singular ドメイン向けの autoVerify インテントフィルターを AndroidManifest.xml に追加し、そのフィンガープリントを Settings > Apps > [Android app] > Show Advanced Settings > App Links SHA256 fingerprints に貼り付けます。
4. ディープリンクを定義 します。 Attribution > Manage Links > Create Link で定義します（以下のフィールドマッピングを参照）。

Manage Links のリダイレクトフィールドのマッピング

リンクを作成する際、3 つのリダイレクトフィールドは、後で API で使用する 3 つのディープリンクの概念に直接対応します。

開発者への引き継ぎ： エンジニアリングチームは、プラットフォームごとのディープリンクスキームと遷移先 URL のリストを提供する必要があります（例： myapp://autumnfashion ）。

ステップ 2：SESSION（インバウンド）— ディープリンクを Singular に送信する

アプリが Singular Link から開かれたら、開いた URL の全体をキャプチャし、SESSION リクエストの openuri パラメータ（URL エンコード済み）で Singular に送信します。これにより Singular はセッションをリンクに帰属させ、ディープリンクの結果をレポートします。Singular Links を使用する場合は必須です。

URL に付与される Singular Link パラメータ

アプリで開いた URL をキャプチャする

アプリには、開いた URL を受け取り、SESSION リクエストに含めるためにサーバーへ転送するハンドラーコードが必要です。

iOS（Swift）：

// Custom scheme / direct opens
func scene(_ scene: UIScene,
           openURLContexts URLContexts: Set<UIOpenURLContext>) {
    guard let url = URLContexts.first?.url else { return }
    SessionReporter.report(openURL: url.absoluteString)
}

// Universal Links arrive via:
func scene(_ scene: UIScene,
           continue userActivity: NSUserActivity) {
    if let url = userActivity.webpageURL {
        SessionReporter.report(openURL: url.absoluteString)
    }
}

Android（Kotlin）：

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    intent?.data?.let { uri ->
        SessionReporter.report(uri.toString())
    }
}

override fun onNewIntent(intent: Intent?) {
    super.onNewIntent(intent)
    intent?.data?.let { SessionReporter.report(it.toString()) }
}

openuri を付けて SESSION リクエストを送信する

サーバーから、キャプチャした URL（URL エンコード済み）を openuri として含めます。

curl -G https://s2s.singular.net/api/v1/launch \
  --data-urlencode "a=<SDK key>" \
  --data-urlencode "p=Android" \
  --data-urlencode "i=com.yourcompany.app" \
  --data-urlencode "aifa=<GAID>" \
  --data-urlencode "n=YourAppName" \
  --data-urlencode "openuri=myapp://home/page?queryparam1=value1"

ショートリンクの解決

ユーザーが短縮された Singular Link を開いた場合は、 singular_link_resolve_required=true も送信してください。Singular が展開されたロングリンクを返すので、ディープリンクとパススルー値を解析できます。

レスポンスのサンプル：

{
  "status": "ok",
  "resolved_singular_link": "https://myapp.sng.link/A59c0/nha7?_dl=myapp%3A%2F%2Fdeeplink&_ddl=myapp%3A%2F%2Fdeferred-deeplink&_p=passthroughvalue"
}

動的パススルーパラメータ

組織がリンクに動的パススルーを設定している場合、ディープリンク URL には、コンテンツルーティング用の URL エンコード済み JSON 文字列または非構造化文字列を持つ _p パラメータが含まれます。 動的パススルーパラメータ を参照してください。

リファレンス： SESSION エンドポイント API リファレンス （ディープリンクパラメータ）。

ステップ 3：SESSION（アウトバウンド）— ディファードディープリンクをアプリへ中継する

リンクをタップした後にアプリをインストールしたユーザーの場合、ディファードディープリンクは、インストール後の最初のセッションで Singular が SESSION レスポンスで返します。お客様のサーバーは、その値をアプリへ中継して、ユーザーを誘導できるようにする必要があります。

最初のセッションで DDL をリクエストする

インストール後の最初の SESSION リクエストで、次の 2 つのパラメータを追加します。

SESSION リクエストのサンプル（install + DDL 有効）：

curl -G https://s2s.singular.net/api/v1/launch \
  --data-urlencode "a=<SDK key>" \
  --data-urlencode "p=Android" \
  --data-urlencode "i=com.yourcompany.app" \
  --data-urlencode "aifa=<GAID>" \
  --data-urlencode "n=YourAppName" \
  --data-urlencode "install=true" \
  --data-urlencode "ddl_enabled=true"

レスポンスを読み取ってアプリへ中継する

インストールがディファードディープリンクを持つトラッキングリンクから発生した場合、Singular は次の値を返します。

SESSION レスポンスのサンプル：

{
  "deferred_deeplink": "myapp://deferred-deeplink",
  "status": "ok",
  "deferred_passthrough": "passthroughvalue"
}

テストと検証

• ディファードディープリンク： アプリがないデバイスでリンクをタップし、ストアに到達することを確認します。インストールして開くと、アプリが目的のコンテンツを表示するはずです。
• ダイレクトディープリンク： アプリをインストールした状態でリンクをタップし、アプリが目的のコンテンツで直接開くことを確認します。
• SESSION の順序： いかなるイベントよりも前に単一の SESSION が受信されること、および SESSION レスポンスが解析されてクライアントへ渡されることを確認します（ディファードディープリンクにとって重要です）。
• openuri の設定： ディープリンクによる起動時には、タイムアウトウィンドウにかかわらず、 openuri を設定した SESSION が送信されることを確認します。

テストガイド： 連携のテスト | トラッキングリンクのテスト