このページは Cloud Translation API によって翻訳されました。

Attribution Reporting のデバッグレポートを設定する
bookmark_border コレクションでコンテンツを整理必要に応じて、コンテンツの保存と分類を行います。

アトリビューションレポートのデバッグに関する 3 部構成のパート 2。デバッグレポートを設定します。

用語集

レポート送信元は、Attribution Reporting の「ソース」ヘッダーとトリガーヘッダーを設定する送信元です。ブラウザによって生成されたすべてのレポートは、このオリジンに送信されます。このガイダンスでは、レポート送信元の例として https://adtech.example を使用します。
アトリビューションレポート（レポート）は、リクエストした測定データを含む最終的なレポート（イベントレベルまたは集計可能）です。
デバッグレポートには、アトリビューションレポート、ソースイベント、トリガーイベントに関する追加データが含まれます。デバッグレポートを受け取っても、必ずしも正しく動作していないわけではありません。2 種類のデバッグレポート
移行デバッグレポートは、生成と送信のために Cookie の設定が必要なデバッグレポートです。Cookie が設定されていない場合、およびサードパーティ Cookie のサポートが終了すると、移行デバッグレポートは利用できなくなります。このガイドで説明するデバッグレポートはすべて移行デバッグレポートです。
成功デバッグレポートでは、アトリビューションレポートの正常な生成を追跡できます。アトリビューションレポートと直接関連しています。成功デバッグレポートは、Chrome 101（2022 年 4 月）から利用できます。
詳細なデバッグレポートは、欠落しているレポートを追跡し、欠落している理由を特定するのに役立ちます。ブラウザがソースイベントまたはトリガーイベントを記録しなかった（つまりアトリビューションレポートを生成しない）ケースと、なんらかの理由でアトリビューションレポートを生成または送信できないケースを示します。詳細なデバッグレポートには、ソースイベント、トリガーイベント、アトリビューションレポートが生成されなかった理由を示す type フィールドが含まれています。詳細なデバッグレポートは、Chrome 109（2023 年 1 月の安定版）からご利用いただけます。
デバッグキーは、ソース側とトリガー側の両方で設定できる一意の識別子です。デバッグキーを使用すると、Cookie ベースのコンバージョンとアトリビューションベースのコンバージョンをマッピングできます。デバッグレポートを生成し、デバッグキーを設定するようにシステムをセットアップすると、ブラウザのすべてのアトリビューションレポートとデバッグレポートにこれらのデバッグキーが含まれるようになります。

ドキュメント全体で使用されているコンセプトと主な用語については、プライバシーサンドボックスの用語集をご覧ください。

実装に関する質問

デバッグレポートの設定中に問題が発生した場合は、デベロッパーサポートリポジトリで問題を作成してください。トラブルシューティングをお手伝いいたします。

デバッグレポートの設定の準備

デバッグレポートを設定する前に、次の手順を行います。

API 統合のベストプラクティスが適用されていることを確認する

コードが機能検出によって制限されていることを確認します。API が Permissions-Policy によってブロックされていないことを確認するには、次のコードを実行します。
```
if (document.featurePolicy.allowsFeature('attribution-reporting')) {
// the Attribution Reporting API is enabled
}
```
この機能検出チェックが true を返した場合、チェックが実行されるコンテキスト（ページ）で API が許可されます。
（テストフェーズでは不要: Permissions-Policy が設定されていることを確認してください）

統合に関する基本的な問題を解決する

デバッグレポートは、大規模な損失を検出して分析するのに役立ちますが、一部の統合の問題はローカルで検出できます。ソースとトリガーヘッダーの構成ミス、JSON 解析の問題、安全でないコンテキスト（HTTPS 以外）、API の機能の妨げとなるその他の問題は、DevTools の [問題] タブに表示されます。

DevTools の問題にはさまざまな種類があります。invalid header の問題が発生した場合は、ヘッダーをヘッダー検証ツールにコピーします。これにより、問題の原因となっているフィールドを特定して修正できます。

アトリビューションレポートのヘッダーを検証する

ヘッダーバリデータを使用して、Attribution Reporting API に関連するヘッダーを検証できます。ブラウザから発生した検証エラーをモニタリングして、API のデバッグを容易にできます。

デバッグレポートの受信を有効にするには、Attribution-Reporting-Info レスポンスヘッダーの一部として report-header-errors を返します。

Attribution-Reporting-Info: report-header-errors

Attribution-Reporting-Info は辞書構造のヘッダーAttribution-Reporting-Info であるため、ブール値 report-header-errors キーを指定すると、true 値が暗黙的に指定されます。

デバッグレポートは、レポートエンドポイントにすぐに送信されます。

https://<reporting origin>/.well-known/attribution-reporting/debug/verbose

レポートデータは、次の形式のオブジェクトの JSON リストとしてリクエスト本文に含まれます。

[{
  "type": "header-parsing-error",
  "body": {
    "context_site": "https://source.example",
    "header": "Attribution-Reporting-Register-Source",
    "value": "!!!", // header value received in the response
    "error": "invalid JSON" // optional error details that may vary across browsers or different versions of the same browser
  }
}]

デバッグレポートを設定する: 成功レポートと詳細レポートに共通の手順

レポート送信元に次の 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 を開きます。
[イベントレベルレポート] タブと [集計可能レポート] タブの両方で、[デバッグレポートを表示] チェックボックスがオンになっていることを確認します。
アトリビューションレポートを実装したサイトを開きます。アトリビューションレポートの生成手順を完了します。この手順と同じ手順で、成功デバッグレポートが生成されます。
chrome://attribution-internals で以下を実行します。
- アトリビューションレポートが正しく生成されていることを確認します。
- [イベントレベルレポート] タブと [集計可能なレポート] タブで、成功したデバッグレポートも生成されていることを確認します。リスト内の青い debug パスで認識できます。

サーバー上で、エンドポイントがこれらの成功デバッグレポートを直ちに受信することを確認します。イベントレベルと集計可能な成功デバッグレポートの両方を確認してください。

ステップ 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 種類の詳細なデバッグレポートが正しく生成されて受信された場合、すべての種類の詳細なデバッグレポートも正しく生成されて受信されます。これは、すべての詳細なデバッグレポートが同じ構成を使用し、同じエンドポイントに送信されるためです。

重要なポイント: テストが簡単な詳細なデバッグレポートを選択します。trigger-no-matching-source は、変換によって生成できるため、適切な候補です。トリガーイベントに関連する詳細レポートは、より適切な候補となる傾向があります。ソースイベントに関連する詳細レポートタイプは、意図的に生成するのが面倒です。

ブラウザで chrome://attribution-internals を開きます。
アトリビューションレポートで設定されているサイトでアトリビューション（コンバージョン）をトリガーします。このコンバージョンの前に広告エンゲージメント（インプレッションまたはクリック）がなかったため、trigger-no-matching-source タイプの詳細なデバッグレポートが生成されます。
chrome://attribution-internals で [詳細なデバッグレポート] タブを開き、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 つの詳細レポート（例: trigger-no-matching-source）: 障害がイベントレベルレポートと集計可能レポートの両方に影響する場合。ただし、イベントレベルレポートと集計可能レポートの障害理由が同じ場合は、詳細レポートが 1 つだけ生成されます。

次の動画

パート 3: デバッグクックブック

Attribution Reporting のデバッグ レポートを設定する bookmark_borderbookmark コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

用語集

実装に関する質問

デバッグ レポートの設定の準備

アトリビューション レポートのヘッダーを検証する

デバッグ レポートを設定する: 成功レポートと詳細レポートに共通の手順

成功デバッグ レポートを設定する

詳細なデバッグ レポートを設定する