Attribution Reporting のデバッグに関するパート 2/3。デバッグ レポートを設定します。
用語集
- レポート送信元は、Attribution Reporting の「ソース」ヘッダーとトリガー ヘッダーを設定する送信元です。ブラウザによって生成されたすべてのレポートは、このオリジンに送信されます。このガイダンスでは、レポート送信元の例として
https://adtech.example
を使用します。 - アトリビューション レポート(レポート)は、リクエストした測定データを含む最終的なレポート(イベントレベルまたは集計可能)です。
- デバッグ レポートには、アトリビューション レポート、ソースイベント、トリガー イベントに関する追加データが含まれます。デバッグ レポートを受け取っても、必ずしも正しく動作していないわけではありません。2 種類のデバッグ レポート
- 移行デバッグ レポートは、生成と送信のために Cookie の設定が必要なデバッグ レポートです。Cookie が設定されていない場合、およびサードパーティ Cookie のサポートが終了すると、移行デバッグ レポートは利用できなくなります。このガイドで説明するデバッグ レポートはすべて移行デバッグ レポートです。
- 成功デバッグ レポートでは、アトリビューション レポートの正常な生成を追跡できます。アトリビューション レポートと直接関連しています。成功デバッグ レポートは、Chrome 101(2022 年 4 月)から利用できます。
- 詳細なデバッグ レポートは、欠落しているレポートを追跡し、欠落している理由を特定するのに役立ちます。ブラウザがソースイベントまたはトリガー イベントを記録しなかった(つまりアトリビューション レポートを生成しない)ケースと、なんらかの理由でアトリビューション レポートを生成または送信できないケースを示します。詳細なデバッグ レポートには、ソースイベント、トリガー イベント、アトリビューション レポートが生成されなかった理由を示す
type
フィールドが含まれています。詳細なデバッグ レポートは、Chrome 109(2023 年 1 月の安定版)からご利用いただけます。 - デバッグキーは、ソース側とトリガー側の両方で設定できる一意の識別子です。デバッグキーを使用すると、Cookie ベースのコンバージョンとアトリビューション ベースのコンバージョンをマッピングできます。デバッグ レポートを生成し、デバッグキーを設定するようにシステムをセットアップすると、ブラウザのすべてのアトリビューション レポートとデバッグ レポートにこれらのデバッグキーが含まれるようになります。
ドキュメント全体で使用されているコンセプトと主な用語については、プライバシー サンドボックスの用語集をご覧ください。
実装に関する質問
デバッグ レポートの設定中に問題が発生した場合は、デベロッパー サポート リポジトリで問題を作成してください。Google がトラブルシューティングをお手伝いします。
デバッグ レポートの設定を準備する
デバッグ レポートを設定する前に、次の手順を行います。
API の統合に関するベスト プラクティスが適用されていることを確認する
コードが機能検出で制限されていることを確認します。API が Permissions-Policy によってブロックされないようにするには、次のコードを実行します。
if (document.featurePolicy.allowsFeature('attribution-reporting')) { // the Attribution Reporting API is enabled }
機能検出チェックが true を返した場合、チェックが実行されたコンテキスト(ページ)で API が許可されます。
(テストフェーズでは不要: Permissions-Policy が設定されていることを確認します)。
統合に関する基本的な問題を解決する
デバッグ レポートは損失を大規模に検出して分析するのに役立ちますが、統合の問題の中にはローカルで検出できるものもあります。ソースとトリガーのヘッダーの構成ミス、JSON 解析の問題、安全でないコンテキスト(HTTPS 以外)、API の動作を妨げるその他の問題は、DevTools の [Issues] タブに表示されます。
DevTools の問題には、さまざまなタイプがあります。invalid header
の問題が発生した場合は、ヘッダー検証ツールにヘッダーをコピーします。これにより、問題の原因となっているフィールドを特定して修正できます。
![スクリーンショット: ヘッダー検証ツール](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/screenshot-header-valida-6fe8347784caf.png?authuser=6&hl=ja)
デバッグ レポートの設定: 成功レポートと詳細レポートに共通する手順
レポート元に次の Cookie を設定します。
Set-Cookie: ar_debug=1; SameSite=None; Secure; Path=/; HttpOnly
ブラウザは、ソース登録とトリガー登録の両方でこの Cookie の有無をチェックします。成功デバッグ レポートは、Cookie が両方の時刻に存在する場合にのみ生成されます。
なお、デバッグ レポートはモード B のブラウザでも有効にできます。この場合、サードパーティ Cookie は無効になり、サードパーティ Cookie のサポート終了に対するテストや準備が容易になります。モード B のブラウザでは、デバッグ Cookie を設定してデバッグ レポートを有効にする必要はありません。ステップ 2 に進んで、成功デバッグ レポートのデバッグキーを設定します。
ステップ 2: デバッグキーを設定する
各デバッグキーは、10 進数の文字列としてフォーマットされた 64 ビット符号なし整数である必要があります。各デバッグキーを一意の ID にします。成功デバッグ レポートは、デバッグキーが設定されている場合にのみ生成されます。
- ソース側のデバッグキーを、デバッグに関連すると思われる追加のソースタイム情報にマッピングします。
- トリガー側のデバッグキーを、デバッグに関連すると思われる追加のトリガー時間情報にマッピングします。
たとえば、次のデバッグキーを設定できます。
- Cookie ID + ソース デバッグキーとしてのソース タイムスタンプ(同じタイムスタンプを Cookie ベースのシステムでキャプチャする)
- Cookie ID + トリガー デバッグキーとしてのトリガー タイムスタンプ(同じタイムスタンプを Cookie ベースのシステムでキャプチャ)
これにより、Cookie ベースのコンバージョン情報を使用して、対応するデバッグ レポートまたはアトリビューション レポートを検索できます。詳しくは、パート 3: クックブックをご覧ください。
ソース側のデバッグキーを source_event_id
とは異なるものにすると、同じソースイベント ID を持つ個々のレポートを区別できます。
Attribution-Reporting-Register-Source:
{
// … Usual fields for Attribution-Reporting-Register-Source
"debug_key":"647775351539539"
}
Attribution-Reporting-Register-Trigger:
{
// … Usual fields for Attribution-Reporting-Register-Trigger
"debug_key":"938321351539743"
}
デモコード: ソース デバッグキー デモコード: トリガー デバッグキー
成功デバッグ レポートを設定する
このセクションのサンプルコードでは、イベントレベル レポートと集計可能レポートの両方について、成功デバッグ レポートを生成します。イベントレベル レポートと集計可能レポートでは、同じデバッグキーが使用されます。
ステップ 3: 成功デバッグ レポートを収集するエンドポイントを設定する
デバッグ レポートを収集するためのエンドポイントを設定します。このエンドポイントは、パスに追加の debug
文字列がある、メインのアトリビューション エンドポイントと同様である必要があります。
- イベントレベルの成功デバッグ レポートのエンドポイント:
https://adtech.example/.well-known/attribution-reporting/debug/report-event-attribution
- 集計可能成功デバッグ レポートのエンドポイント:
https://adtech.example/.well-known/attribution-reporting/debug/report-aggregate-attribution
- 集計可能成功デバッグ レポートのエンドポイント:
アトリビューションがトリガーされると、ブラウザは直ちに POST
リクエストを介してこのエンドポイントにデバッグ レポートを送信します。受信成功デバッグ レポートを処理するサーバーコードは次のようになります(ここではノード エンドポイントにあります)。
// Handle incoming event-Level Success Debug reports
adtech.post(
'/.well-known/attribution-reporting/debug/report-event-attribution',
async (req, res) => {
// Debug report is in req.body
res.sendStatus(200);
}
);
// Handle incoming aggregatable Success Debug reports
adtech.post(
'/.well-known/attribution-reporting/debug/report-aggregate-attribution',
async (req, res) => {
// Debug report is in req.body
res.sendStatus(200);
}
);
デモコード: イベントレベル デバッグ レポート エンドポイント
ステップ 4: 設定で成功デバッグ レポートが生成されることを確認する
- ブラウザで
chrome://attribution-internals
を開きます。 - [イベントレベル レポート] タブと [集計可能レポート] タブで、[デバッグ レポートを表示] チェックボックスがオンになっていることを確認します。
- Attribution Reporting を実装したサイトを開きます。アトリビューション レポートの生成に使用する手順を完了します。同じ手順で成功デバッグ レポートが生成されます。
chrome://attribution-internals
で以下を実行します。- アトリビューション レポートが正しく生成されていることを確認する
- [イベントレベル レポート] タブと [集計可能レポート] タブで、成功デバッグ レポートも生成されていることを確認します。青色の
debug
パスでリスト内で識別します。
![スクリーンショット: アトリビューションの仕組み](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/screenshot-attribution-i-e7d3e5d9e396.png?authuser=6&hl=ja)
- サーバーで、エンドポイントがこれらの成功デバッグ レポートをすぐに受信することを確認します。イベントレベルのデバッグ レポートと集計可能な成功デバッグ レポートの両方を確認してください。
![スクリーンショット: 送信元サーバーのログの報告](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/screenshot-reporting-ori-89d44854473d7.png?authuser=6&hl=ja)
ステップ 5: 成功デバッグ レポートを確認する
成功デバッグ レポートはアトリビューション レポートと同じで、ソース側とトリガー側の両方のデバッグキーが含まれます。
{
"attribution_destination": "https://advertiser.example",
"randomized_trigger_rate": 0.0000025,
"report_id": "7d76ef29-d59e-4954-9fff-d97a743b4715",
"source_debug_key": "647775351539539",
"source_event_id": "760938763735530",
"source_type": "event",
"trigger_data": "0",
"trigger_debug_key": "156477391437535"
}
{
"aggregation_service_payloads": [
{
"debug_cleartext_payload": "omRkYXRhgqJldmFsdWVEAACAAGZidWNrZXRQPPhnkD+7c+wm1RjAlowp3KJldmFsdWVEAAARMGZidWNrZXRQJFJl9DLxbnMm1RjAlowp3GlvcGVyYXRpb25paGlzdG9ncmFt",
"key_id": "d5f32b96-abd5-4ee5-ae23-26490d834012",
"payload": "0s9mYVIuznK4WRV/t7uHKquHPYCpAN9mZHsUGNiYd2G/9cg87Y0IjlmZkEtiJghMT7rmg3GtWVPWTJU5MvtScK3HK3qR2W8CVDmKRAhqqlz1kPZfdGUB4NsXGyVCy2UWapklE/r7pmRDDP48b4sQTyDMFExQGUTE56M/8WFVQ0qkc7UMoLI/uwh2KeIweQCEKTzw"
}
],
"shared_info": "{\"api\":\"attribution-reporting\",\"attribution_destination\":\"https://advertiser.example\",\"debug_mode\":\"enabled\",\"report_id\":\"4a04f0ff-91e7-4ef6-9fcc-07d000c20495\",\"reporting_origin\":\"https://adtech.example\",\"scheduled_report_time\":\"1669888617\",\"source_registration_time\":\"1669852800\",\"version\":\"0.1\"}",
"source_debug_key": "647775351539539",
"trigger_debug_key": "156477391437535"
}
詳細なデバッグ レポートを設定する
ステップ 3: ソースヘッダーとトリガー ヘッダーで詳細デバッグを有効にする
Attribution-Reporting-Register-Source
と Attribution-Reporting-Register-Trigger
の両方で debug_reporting
を true
に設定します。
Attribution-Reporting-Register-Source:
{
// … Usual fields for Attribution-Reporting-Register-Source
"debug_key":"938321351539743",
"debug_reporting": true // defaults to false if not present
}
Attribution-Reporting-Register-Trigger:
{
// … Usual fields for Attribution-Reporting-Register-Trigger
"debug_key":"938321351539743",
"debug_reporting": true // defaults to false if not present
}
ステップ 4: 詳細なデバッグ レポートを収集するようにエンドポイントを設定する
デバッグ レポートを収集するためのエンドポイントを設定します。このエンドポイントは、パスに追加の debug/verbose
文字列がある、メインのアトリビューション エンドポイントと同様である必要があります。
https://adtech.example/.well-known/attribution-reporting/debug/verbose
詳細デバッグ レポートが生成される場合、つまりソースまたはトリガーが登録されていない場合、ブラウザは直ちに POST
リクエストを介してこのエンドポイントに詳細なデバッグ レポートを送信します。受信した詳細デバッグ レポートを処理するサーバーコードは次のようになります(ここではノード エンドポイントにあります)。
// Handle incoming verbose debug reports
adtech.post(
'/.well-known/attribution-reporting/debug/verbose',
async (req, res) => {
// List of verbose debug reports is in req.body
res.sendStatus(200);
}
);
成功デバッグ レポートとは異なり、詳細レポート用のエンドポイントは 1 つだけです。イベントレベルのレポートと集計レポートに関連する詳細レポートはすべて、同じエンドポイントに送信されます。
ステップ 5: 設定で詳細なデバッグ レポートが生成されることを確認する
詳細デバッグ レポートにはさまざまなタイプがありますが、1 つのタイプの詳細デバッグ レポートで詳細デバッグの設定をチェックすれば十分です。この 1 種類の詳細デバッグ レポートが正しく生成され、受信されると、すべての詳細デバッグ レポートが同じ構成を使用し、同じエンドポイントに送信されるため、すべてのタイプの詳細デバッグ レポートが正しく生成され、受信されます。
- ブラウザで
chrome://attribution-internals
を開きます。 - Attribution Reporting が設定されているサイトでアトリビューション(コンバージョン)をトリガーする。このコンバージョンの前に広告エンゲージメント(インプレッションまたはクリック)がなかった場合、タイプ
trigger-no-matching-source
の詳細なデバッグ レポートが生成されます。 chrome://attribution-internals
で [Verbose debug Reports] タブを開き、タイプtrigger-no-matching-source
の詳細デバッグ レポートが生成されていることを確認します。- サーバーで、エンドポイントがこの詳細なデバッグ レポートをすぐに受信したことを確認します。
ステップ 6: 詳細なデバッグ レポートを確認する
トリガー時に生成される詳細なデバッグ レポートには、ソース側とトリガー側のデバッグキーの両方が含まれます(トリガーに一致するソースがある場合)。ソース時に生成された詳細なデバッグ レポートには、ソース側のデバッグキーが含まれます。
ブラウザから送信された、詳細なデバッグ レポートを含むリクエストの例:
[
{
"body": {
"attribution_destination": "http://arapi-advertiser.localhost",
"randomized_trigger_rate": 0.0000025,
"report_id": "92b7f4fd-b157-4925-999e-aad6361de759",
"source_debug_key": "282273499788483",
"source_event_id": "480041649210491",
"source_type": "event",
"trigger_data": "1",
"trigger_debug_key": "282273499788483"
},
"type": "trigger-event-low-priority"
},
{
"body": {
"attribution_destination": "http://arapi-advertiser.localhost",
"limit": "65536",
"source_debug_key": "282273499788483",
"source_event_id": "480041649210491",
"source_site": "http://arapi-publisher.localhost",
"trigger_debug_key": "282273499788483"
},
"type": "trigger-aggregate-insufficient-budget"
}
]
詳細レポートには、次のフィールドがあります。
Type
- レポートが生成された原因。すべての詳細レポートタイプと、タイプごとに取るべきアクションについては、パート 3: デバッグ クックブックにある詳細レポートのリファレンスをご覧ください。
Body
- レポートの本文。その種類によって異なります。パート 3: デバッグ クックブックの詳細レポートのリファレンスをご覧ください。
リクエストの本文には、詳細レポートが 1 つ以上、最大 2 つ含まれます。
- エラーがイベントレベルのレポートのみに影響する場合(または集計可能レポートにのみ影響する場合)は、1 つの詳細レポートを作成します。ソースまたはトリガーの登録失敗の理由が 1 つだけであるため、失敗ごとに、およびレポートタイプ(イベントレベルまたは集計可能)ごとに 1 つの詳細レポートを生成できます。
- 失敗がイベントレベル レポートと集計可能レポートの両方に影響する場合、2 つの詳細レポート。例外として、イベントレベル レポートと集計可能レポートで失敗の理由が同じ場合、1 つの詳細レポートのみが生成されます(例:
trigger-no-matching-source
)。