アトリビューション ソースを登録する

クリックとビューを適切なイベントに帰属させるためにソースを登録する方法について説明します。

アトリビューション ソースは、広告関連のイベント（クリックまたはビュー）です。広告テクノロジー企業は、このイベントに次の種類の情報を付加できます。

  • 広告クリエイティブ ID、キャンペーンに関する情報、地域などのコンテキスト レポート データ。
  • コンバージョン ドメイン（ユーザーのコンバージョンが期待できるサイト）。

このドキュメントの手順に沿って操作すると、ブラウザがコンバージョンを割り当てるソース（広告インプレッションまたはクリック）を登録できます。

登録方法

アトリビューション ソースを登録するには、HTML 要素または JavaScript 呼び出しを使用します。

  • <a> タグ
  • <img> タグ
  • <script> タグ
  • fetch 個の電話番号
  • XMLHttpRequest
  • window.open 個の電話番号

これによりネットワーク リクエストが生成され、ソース登録 HTTP レスポンス ヘッダーで応答します。

クリックまたはビューのソースを登録する

クリックまたはビューのアトリビューション ソースを登録するには、こちらの手順に沿って操作してください。完全な手順は次のとおりです。概要は次のとおりです。

  1. ソース登録を開始します。リクエストを行うには、HTML 要素または JavaScript 呼び出しを使用します。この手順は、クリック数とビュー数で異なります。次のセクションで説明します。

  2. ソース登録ヘッダーで応答して、ソース登録を完了します。リクエストを受け取ったら、ヘッダー Attribution-Reporting-Register-Source で応答します。そのヘッダーで、選択したアトリビューション レポート構成を指定します。この手順は、クリックとビューの両方で同じです。

    概要レポートの例:

    {
  "aggregation_keys": {
    "campaignCounts": "0x159",
    "geoValue": "0x5"
  },
  "aggregatable_report_window": "86400",
  "destination": "https://example.com"
}

    イベントレベル レポートの例:

    {
  "source_event_id": "12340873456",
  "destination": "[eTLD+1]",
  "expiry": "[64-bit signed integer]",
  "priority": "[64-bit signed integer]",
  "event_report_window": "[64-bit signed integer]"
}

必須属性と省略可能な属性

HTML 要素を使用したり、JavaScript 呼び出しを行ってソースを登録したりする際に、attributionsrc または attributionReporting を使用する必要がある場合があります。これらの要件がいつ必要になるかについては、次の表をご覧ください。

attributionsrc が省略可能な場合、これを使用すると、リクエストがアトリビューション レポートの対象となることを示します。attributionsrc を使用すると、ブラウザは Attribution-Reporting-Eligible ヘッダーを送信します。アプリからウェブへの測定にも役立ちます。attributionsrc が存在する場合、ブラウザは Attribution-Reporting-Support ヘッダーを送信します。

登録方法 ソース
<a> タグ （ナビゲーション ソース）
attributionsrc は必須です。
<img> タグ （イベントソース）
attributionsrc は必須です。
<script> タグ （イベントソース）
attributionsrc は必須です。
fetch 個の電話番号 attributionReporting オプションは必須です。
XMLHttpRequest attributionReporting オプションは必須です。
window.open 個の電話番号 （ナビゲーション ソース）
attributionsrc は必須です。

ステップ 1: ソース登録を開始する

ステップ 1 はクリック数と視聴回数で異なります。

クリックのアトリビューション ソースを登録するには、<a> タグまたは JavaScript window.open() を使用します。

アンカーを使用する

インプレッション数またはクリック数を測定する既存の <a> タグに attributionsrc を追加します。

<a href="https://shoes.example/..." attributionsrc>Click me</a>

詳細については、サンプルコードをご覧ください。

スクリプトを使用する

attributionsrc を使用して window.open() を呼び出します。

window.open(
  "https://shoes.example/...",
  "_blank",
  "attributionsrc");

このメソッドは、ユーザー操作から 5 秒以内に呼び出す必要があります。

attributionsrc を単独で追加する代わりに、画像またはスクリプトに対して単一の URL 値を指定できます。

<a href=... attributionsrc="https://a.example/register-source">Click me</a>

JavaScript の場合、attributionsrc に値を指定するときは、= などの特殊文字が含まれている場合に、パラメータが正しく解析されないことがないよう、URL をエンコードしてください。

次のようにエンコードします。

const encodedUrl = encodeURIComponent(
  "https://adtech.example/attribution_source?ad_id=...");
window.open(
  "https://shoes.example/landing",
   "_blank",
   `attributionsrc=${encodedUrl}`);

attributionsrc は、<a> タグで示されているように、スペース区切りの URL リストを受け取ることもできます。

<a href=... attributionsrc="https://a.example/register-source
  https://b.example/register-source">Click me</a>

または、window.open() を使用してここにあるようにします。

window.open("...", "_blank", `attributionsrc=${encodedUrl1}
  attributionsrc=${encodedUrl2}`)

このような場合、両方の URL がナビゲーション ソースの対象となる attributionsrc リクエスト（Attribution-Reporting-Eligible ヘッダーを含むリクエスト）を受け取ります。

値の有無にかかわらず attributionsrc

前述のように、URL を指定せずに attributionsrc を指定できます。単一の URL を指定することもできます。また、URL のスペース区切りリストを使用することもできます。

URL を使用すると、ブラウザは 個別のキープアライブ取得リクエスト（URL ごとに 1 つ）を開始します。このリクエストには Attribution-Reporting-Eligible リクエスト ヘッダーが含まれます。

これは、要素のメイン リクエストとは別のリクエストに応答してソース登録を行う場合に便利です。

たとえば、アンカー要素のクリックのソースを登録する必要がある場合、実際にはリンク先を制御できないことがあります。この場合、ナビゲーションとは別のリクエストに対するレスポンスとしてソース登録ヘッダーを送信し、完全に制御できる構成が必要になります。attributionsrc に明示的な値を指定することで、ブラウザにその追加リクエストを行うよう指示し、その宛先を構成します。

ビューのアトリビューション ソースを登録するには、attributionsrc 属性を追加する画像タグまたはスクリプトタグを使用します。

または、JavaScript の fetch() または XMLHttpRequest() を使用することもできます。

画像付き

<img attributionsrc
src="https://adtech.example/attribution_source?ad_id=...">

スクリプトを使用する

<script attributionsrc
  src="https://adtech.example/attribution_source?ad_id=..."></script>

必要に応じて、クリックの場合と同じように attributionsrc の URL 値を指定できます。つまり、画像またはスクリプトの場合、次のように attributionsrc の URL を設定できます。

単一の URL の場合:

<img attributionsrc="https://adtech.example/attribution_source?ad_id=123">

URL のリストを使用する場合:

<img attributionsrc="https://a.example/register-source
  https://b.example/register-source">

fetch() または XMLHttpRequest() の使用

このコードは、attributionsrc を使用した HTML リクエストの動作を効果的にシミュレートします。

const attributionReporting = {
  eventSourceEligible: true,
  triggerEligible: false,
};

// Optionally set keepalive to make sure the request outlives the page.
window.fetch("https://adtech.example/attribution_source?my_ad_id=123",
  { keepalive: true, attributionReporting });

const attributionReporting = {
  eventSourceEligible: true,
  triggerEligible: false,
};

const req = new XMLHttpRequest();
req.open("GET", url);
req.setAttributionReporting(attributionReporting);
req.send();

ステップ 2: ヘッダー（クリック数と視聴回数）で応答する

クリックとビューの両方で、次のステップは Attribution-Reporting-Register-Source ヘッダーで応答することです。

詳細については、サンプルコードをご覧ください。

サーバーでブラウザ リクエストを受け取ったら、レスポンスを送信し、レスポンスに Attribution-Reporting-Register-Source ヘッダーを含めます。

res.set(
  "Attribution-Reporting-Register-Source",
  JSON.stringify({
    // Use source_event_id to map it to any granular information
    // you need at ad-serving time
    source_event_id: "412444888111012",
    destination: "https://advertiser.example",
    // Optional fields
    expiry: "604800",
    priority: "100",
    debug_key: "122939999"
  })
);

文字列化すると、ヘッダーは次のようになります。

{"source_event_id":"412444888111012","destination":"https://advertiser.example","expiry":"604800","priority":"100","debug_key":"122939999"}

次のステップ

アトリビューション トリガーを登録する方法を学習する。