プライバシーサンドボックスの一部のテクノロジーは段階的に廃止されます。

プライバシーサンドボックステクノロジーに関する計画の最新情報をご覧ください。

プライバシーサンドボックスの機能のステータスでは、個々の API とプラットフォーム機能のステータスについて詳しく説明しています。

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

Attribution Reporting のデバッグレポートを設定する

アトリビューションレポートのデバッグに関する 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 の問題にはさまざまな種類があります。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 が存在する場合にのみ生成されます。

デモコード: デバッグ Cookie

デバッグレポートは、サードパーティ Cookie のサポート終了に向けたテストと準備を容易にするためにサードパーティ Cookie が無効になっているモード B のブラウザで有効にできます。モード 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 を開きます。
Attribution Reporting で設定されたサイトでアトリビューション（コンバージョン）をトリガーします。このコンバージョンの前に広告エンゲージメント（インプレッションまたはクリック）がなかったため、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 つの詳細レポート。ただし、イベントレベルレポートと集計可能レポートの失敗理由が同じ場合は、1 つの詳細レポートのみが生成されます（例: trigger-no-matching-source）。

次の動画

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

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

用語集

実装に関する質問

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

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

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

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

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