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

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

ドキュメント全体で使用されるその他の概念と重要な用語については、「プライバシーサンドボックス用語集」をご覧ください。

• コードが機能検出の背後でゲートされていることを確認してください。
• （テスト段階では必要ありません: 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）