デバッグレポートをセットアップする

• The reporting origin is the origin that sets the Attribution Reporting source and trigger headers. All reports generated by the browser are sent to this origin. In this guidance, we use https://adtech.example as the example reporting origin.
• An attribution report (report for short) is the final report (event-level or aggregatable) that contains the measurement data you've requested.
• A debug report contains additional data about an attribution report, or about a source or trigger event. Receiving a debug report does not necessarily mean that something is working incorrectly! There are two types of debug reports
• A transitional debug report is a debug report that requires a cookie to be set in order to be generated and sent. Transitional debug reports will be unavailable if a cookie is not set, and once third-party cookies are deprecated. All debug reports described in this guide are transitional debug reports.
• Success debug reports track successful generation of an attribution report. They relate directly to an attribution report. Success debug reports have been available since Chrome 101 (April 2022).
• Verbose debug reports can track missing reports and help you determine why they're missing. They indicate cases where the browser did not record a source or trigger event, (which means it will not generate an attribution report), and cases where an attribution report can't be generated or sent for some reason. Verbose debug reports include a type field that describes the reason why a source event, trigger event or attribution report was not generated. Verbose debug reports are available starting in Chrome 109 (Stable in January 2023).
• Debug keys are unique identifiers you can set on both the source side and the trigger side. Debug keys enable you to map cookie-based conversions and attribution-based conversions. When you've set up your system to generate debug reports and set debug keys, the browser will include these debug keys in all attribution reports and debug reports.

For more concepts and key terms used throughout our documentation, refer to the Privacy Sandbox glossary.

• コードが機能検出の背後でゲートされていることを確認してください。
• （テスト段階では必要ありません: Permissions-Policyを設定したことを確認してください）

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

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

レポート作成元に次の Cookie を設定します。

Set-Cookie: ar_debug=1; SameSite=None; Secure; Path=/; HttpOnly

ブラウザは、ソースとトリガーの両方の登録でこの Cookie の有無を確認します。両方の時点で Cookie が存在する場合にのみ、成功のデバッグレポートが生成されます。

デモ コード: デバッグ Cookie

各デバッグ キーは、基数 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"
}

デモ コード: ソースデバッグキー****デモ コード: トリガーデバッグキー

デバッグレポートを収集するエンドポイントをセットアップします。このエンドポイントは、パスに 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);
  }
);

デモ コード: イベントレベルデバッグレポートのエンドポイント

デモ コード: 集約可能なデバッグレポートのエンドポイント

• ブラウザで chrome://attribution-internals を開きます。
• Event-Level Reports タブと Aggregatable Reports タブの両方で、Show Debug Reports チェックボックスがオンになっていることを確認します。
• アトリビューション レポートを実装したサイトを開きます。アトリビューション レポートの生成に使用する手順を完了します。これらの同じ手順により、成功デバッグレポートが生成されます。
• chrome://attribution-internals で以下を確認します。
  • アトリビューション レポートが正しく生成されていることを確認します。
  • Event-Level Reports タブと Aggregatable Reports タブで、成功デバッグレポートも生成されていることを確認します。リスト内の青い debug パスでそれらを認識できます。

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

成功デバッグレポートはアトリビューション レポートと同じで、ソース側とトリガー側の両方のデバッグキーが含まれています。

{
  "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"
}

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
}

デモ コード: ソースヘッダー

デモ コード: トリガーヘッダー

デバッグレポートを収集するエンドポイントをセットアップします。このエンドポイントは、パスに 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 つしかありません。イベントレベルおよび集計レポートに関連する詳細レポートは、すべて同じエンドポイントに送信されます。

デモ コード: 詳細デバッグレポートのエンドポイント

詳細デバッグレポートにはさまざまなタイプがありますが、1 タイプの詳細デバッグレポートだけで詳細なデバッグのセットアップを確認すれば十分です。すべての詳細デバッグレポートが同じ構成を使用し、同じエンドポイントに送信されるため、この 1 タイプの詳細デバッグレポートが正しく生成され、受信されれば、すべてのタイプの詳細デバッグレポートも正しく生成され、受信されることになります。

1. ブラウザで chrome://attribution-internals を開きます。
2. アトリビューション レポートでセットアップされたサイトでアトリビューション（コンバージョン）をトリガーします。このコンバージョンの前に広告エンゲージメント（インプレッションまたはクリック）がなかったことを考えると、trigger-no-matching-source タイプの詳細デバッグレポートが生成されることが予想されます。
3. chrome://attribution-internals で、Verbose debug reports タブを開き、trigger-no-matching-source タイプの詳細デバッグレポートが生成されていることを確認します。
4. サーバーで、エンドポイントがこの詳細デバッグレポートをすぐに受信したことを確認します。

トリガー時に生成される詳細デバッグレポートには、ソース側とトリガー側の両方のデバッグキーが含まれます（トリガーに一致するソースがある場合）。ソース時に生成される詳細デバッグレポートには、ソース側のデバッグキーが含まれます。

ブラウザから送信される、詳細デバッグレポートを含むリクエストの例:

[
  {
    "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）