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

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

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 の問題が発生した場合は、ヘッダー検証ツールにヘッダーをコピーします。これにより、問題の原因となっているフィールドを特定して修正できます。

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

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

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

ブラウザは、ソース登録とトリガー登録の両方でこの Cookie の有無をチェックします。成功デバッグレポートは、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 パスでリスト内で識別します。

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

ステップ 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 で [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）。

次の動画

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

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

用語集

実装に関する質問

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

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

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

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