概要

Web Server-to-Server（Web S2S）は、モバイル V2 連携と同じ EVENT エンドポイントを使用して、Web のコンバージョンイベントおよびエンゲージメントイベントをサーバーから直接 Singular に送信します。Web パスは、platform パラメーター p=Web によって区別されます。

Web S2S は ブラウザー支援型アーキテクチャ です。アトリビューションに関連するいくつかの値は、ブラウザーでのみ取得可能です。 location.href 、 document.referrer 、およびブラウザーの userAgent は、バックエンドで再構築することはできません。軽量なクライアントサイドスニペットがこれらの値を収集し、エンドポイントを直接呼び出すか、またはそれらをバックエンドに転送し、バックエンドが S2S 呼び出しを行う必要があります。

Web には SESSION エンドポイントはありません 。最初の __PAGE_VISIT__ コンバージョンイベントがモバイルの launch 呼び出しに代わり、その訪問のアトリビューションのベースラインを確立します。

エンドポイント

Web S2S は、モバイル V2 EVENT エンドポイントと同じホスト、パス、POST メソッドを使用します。リクエストをウェブアトリビューションパスにルーティングするには、p=Web を設定します。

POST https://s2s.singular.net/api/v2/evt

必須ヘッダー：

Content-Type: application/x-www-form-urlencoded

SDID の生成と永続化

Singular デバイス ID（ sdid ）は、1 つのブラウザーからのすべてのイベントを 1 台の Web デバイスに紐付けます。最初のページ読み込み時に、 localStorage に global_singular_id が存在しない場合は、UUID v4 を生成して保存します。 localStorage がクリアされるまで、そのブラウザーからのすべてのイベントで同じ値を sdid として再利用します。

function getOrCreateSDID() {
  var KEY = 'global_singular_id';
  var sdid = localStorage.getItem(KEY);
  if (!sdid) {
    sdid = crypto.randomUUID(); // UUID v4
    localStorage.setItem(KEY, sdid);
  }
  return sdid;
}

__PAGE_VISIT__ パターン

新しい訪問の最初のイベントは、必ず conversion_event=true を指定した __PAGE_VISIT__ でなければなりません。これにより、後続のイベントが継承するアトリビューションのベースラインが確立されます。

非コンバージョンイベント（例えば sng_registration_complete や sng_purchase ）は、 conversion_event=false を使用し、 attribution_data を 省略します 。これらは、直近の __PAGE_VISIT__ からアトリビューションを継承します。

custom_user_id のルール

• 登録またはログイン後、およびそれ以降のすべてのイベントに custom_user_id を含めてください。
• これを localStorage またはファーストパーティ Cookie に永続化してください。
• ログアウト時には削除してください。
• PII は決して含めないでください。ハッシュ化された ID または内部 ID を使用してください。

パラメーター

Web SDK は __PAGE_VISIT__ でおよそ 40 個のパラメーターを送信しますが、そのほとんどは SDK 内部のテレメトリであり、S2S の開発者が再現すべきものではありません。以下の表では、必須および推奨のパラメーターセットのみを扱います。

必須パラメーター

推奨パラメーター

デバイス識別情報や上記に記載されていないその他の共有パラメーターについては、ここで再度記載するのではなく、EVENT エンドポイントリファレンスを参照してください。

attribution_data

attribution_data パラメーターは、広告ネットワークからのクリックスルーデータを URL エンコードされた JSON として保持します。 __PAGE_VISIT__ コンバージョンイベントでのみ送信してください。

{
  "partner_name": "Snapchat",
  "is_attributed": "true",
  "touch_timestamp": "",
  "partner_campaign_id": "",
  "partner_campaign_name": "Snap_campaign_1234",
  "partner_creative_id": "",
  "partner_creative_name": "",
  "partner_keyword": "",
  "partner_site": "",
  "partner_site_id": "",
  "partner_site_name": "",
  "partner_sub_site": "",
  "partner_sub_site_name": "",
  "partner_subcampaign_id": "",
  "partner_subcampaign_name": "",
  "_p": ""
}

必須フィールド

任意フィールド

e パラメーターでの Web クリック ID

ネットワークのクリック ID は、各パートナーが期待する JSON キーを使用して、イベントの e ペイロードで渡します。

Web-to-App アトリビューション

Web キャンペーンのコンテキストをモバイルクリックに引き継ぐには、ランディングページから Singular Link を構築し、取得したランディングのクエリ文字列を追加します。これにより、マーケティングパラメーターがモバイルクリックに転送され、アプリのインストールをアトリビューションできるようになります。

ランディング時に、マーケティングパラメーターを含む場合は window.location.search （およびフラグメント）を取得し、永続化します。アプリストアリンクまたはスマートバナーリンクをレンダリングする際には、次のように構築します。

function buildWebToAppLink(baseLink, webUrl, deeplink, passthrough, deferredDeeplink) {
  var url = new URL(baseLink); // preserves existing base-link params
  if (webUrl) {
    var q = new URL(webUrl);
    var captured = q.search.slice(1) + (q.hash || ''); // landing query string (+fragment)
    url.searchParams.set('_web_params', captured); // URL-encoded on serialization
  }
  if (deeplink)         url.searchParams.set('_dl', deeplink);
  if (passthrough)      url.searchParams.set('_p', passthrough);
  if (deferredDeeplink) url.searchParams.set('_ddl', deferredDeeplink);
  return url.toString();
}

クリップボードアトリビューション（遅延ディープリンク）

クリップボードアトリビューションは、遅延ディープリンクに対して決定論的なマッチを提供します。Web スニペットが一意のトークンをクリップボードに書き込み、新しくインストールされたアプリがそれを読み戻し、トークンの一致でマッチングします。

function openAppWithClipboardDdl(baseLink, deeplink, passthrough, deferredDeeplink) {
  // 1. Build the web-to-app link (see Web-to-App Attribution).
  var link = buildWebToAppLink(baseLink, capturedWebUrl, deeplink, passthrough, deferredDeeplink);

  // 2. Generate a UUID v4 and form the token.
  var uuid = crypto.randomUUID();
  var tokenUrl = location.protocol + '//' + location.hostname + '/__singular_ddl__/' + uuid;

  // 3. Write ONLY the token to the clipboard (execCommand fallback).
  copyToClipboard(tokenUrl);

  // 4. Append the token to the click as ecid.
  var url = new URL(link);
  url.searchParams.set('ecid', tokenUrl);

  // 5. Open the app / store.
  window.open(url.toString());
}

function copyToClipboard(text) {
  if (navigator.clipboard && navigator.clipboard.writeText) {
    navigator.clipboard.writeText(text);
    return;
  }
  var ta = document.createElement('textarea');
  ta.value = text;
  document.body.appendChild(ta);
  ta.select();
  document.execCommand('copy');
  document.body.removeChild(ta);
}

イベントシーケンスの例

初回訪問と登録

1. ユーザーが Google Ads から到着します。最初のページ訪問を送信します。

   • n=__PAGE_VISIT__
   • conversion_event=true
   • sdid=3730aecb-47ba-4d13-bd17-52b4b700956f
   • attribution_data={ "partner_name": "googleadwords_int", "is_attributed": "true", "partner_campaign_name": "brand_us_en" }

2. ユーザーが登録します。登録イベントを送信します。

   • n=sng_registration_complete
   • conversion_event=false
   • sdid=3730aecb-47ba-4d13-bd17-52b4b700956f （同じ SDID）
   • custom_user_id=user_12345abc
   • attribution_data なし

新しいキャンペーンから戻ってきたユーザー

1. 同じブラウザーが別のキャンペーンから戻ってきます。新しいページ訪問を送信します。

   • n=__PAGE_VISIT__
   • conversion_event=true
   • sdid=3730aecb-47ba-4d13-bd17-52b4b700956f （同じ SDID）
   • attribution_data={ "partner_name": "facebook", "is_attributed": "true", "partner_campaign_name": "retargeting_Q1" }

2. ユーザーが購入します。購入イベントを送信します。

   • n=sng_purchase
   • conversion_event=false
   • sdid=3730aecb-47ba-4d13-bd17-52b4b700956f （同じ SDID）
   • 永続化された custom_user_id
   • attribution_data なし