ソースを登録して、クリックやビューを適切なイベントに結び付ける方法を説明します。
アトリビューション ソースは広告関連のイベント(クリックまたはビュー)であり、広告テクノロジーはこれに次の種類の情報を追加できます。
- 広告クリエイティブ ID、キャンペーンに関する情報、地域などのコンテキスト レポートデータ。
- コンバージョンの発生先(ユーザーがコンバージョンに至ると想定するサイト)。
このドキュメントの手順に沿って操作することで、発生元(広告のインプレッションまたはクリック)を登録し、ブラウザがこれらのコンバージョンに関連付けることができます。
登録方法
アトリビューション ソースを登録するには、HTML 要素または JavaScript 呼び出しを使用します。
<a>
タグ<img>
タグ<script>
タグfetch
個の電話番号XMLHttpRequest
window.open
個の電話番号
これによりネットワーク リクエストが生成され、ソース登録の HTTP レスポンス ヘッダーで応答します。
クリックまたは視聴のソースを登録する
クリックまたは視聴のアトリビューション ソースを登録する手順は、次のとおりです。詳しい手順については、こちらをご覧ください。概要は次のとおりです。
- ソースの登録を開始します。HTML 要素または JavaScript 呼び出しを使用してリクエストを行います。後で確認するように、このステップはクリック数と視聴では異なります。
ソース登録ヘッダーで応答して、ソースの登録を完了します。そのリクエストを受け取ったら、ヘッダー
Attribution-Reporting-Register-Source
で応答します。そのヘッダーで、目的の Attribution Reporting 構成を指定します。このステップは、クリック数と視聴回数の両方で同じです。概要レポートの例:
{ "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
が省略可の場合、使用すると、リクエストは Attribution Reporting の対象になることを示します。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
を単独で追加する代わりに、次のように 1 つの 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 を 1 つだけ指定することもできます。また、URL をスペースで区切ったリストを使用することもできます。
URL を使用すると、ブラウザは Attribution-Reporting-Eligible
リクエスト ヘッダーを含む個別のキープアライブ取得リクエストを開始します(URL ごとに 1 つずつ)。
これは、要素のメイン リクエストとは別のリクエストに応答してソース登録を行う場合に便利です。
たとえば、アンカー要素のクリックのソースを登録する必要がある場合、実際にはデスティネーションを制御できないことがあります。この場合、ソース登録ヘッダーを、ナビゲーションとは別にリクエストに対するレスポンスとして送信し、完全に制御できる構成が必要になります。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 が 1 つの場合:
<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 ensure 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"}
次のステップ
詳しくは、アトリビューション トリガーを登録する方法をご覧ください。