Menyiapkan laporan debug untuk Attribution Reporting

Bagian 2 dari 3 tentang proses debug Attribution Reporting. Siapkan laporan debug Anda.

Glosarium

  • Asal pelaporan adalah asal yang menetapkan header sumber dan pemicu Pelaporan Atribusi. Semua laporan yang dibuat oleh browser dikirim ke asal ini. Dalam panduan ini, kami menggunakan https://adtech.example sebagai contoh asal pelaporan.
  • Laporan atribusi (singkatnya laporan) adalah laporan akhir (tingkat peristiwa atau agregat) yang berisi data pengukuran yang Anda minta.
  • Laporan debug berisi data tambahan tentang laporan atribusi, atau tentang peristiwa sumber atau pemicu. Menerima laporan debug tidak selalu berarti ada sesuatu yang berfungsi dengan tidak benar. Ada dua jenis laporan debug
  • Laporan debug transisi adalah laporan debug yang mengharuskan cookie ditetapkan agar dapat dibuat dan dikirim. Laporan debug transisi tidak akan tersedia jika cookie tidak ditetapkan dan setelah cookie pihak ketiga tidak digunakan lagi. Semua laporan debug yang dijelaskan dalam panduan ini adalah laporan debug transisi.
  • Laporan debug keberhasilan melacak pembuatan laporan atribusi yang berhasil. Keduanya berkaitan langsung dengan laporan atribusi. Laporan debug sukses telah tersedia sejak Chrome 101 (April 2022).
  • Laporan debug panjang dapat melacak laporan yang tidak ada dan membantu Anda menentukan alasan laporan tidak ada. Eksperimen menunjukkan kasus saat browser tidak mencatat peristiwa sumber atau pemicu, (yang berarti browser tidak akan membuat laporan atribusi), dan kasus saat laporan atribusi tidak dapat dibuat atau dikirim karena alasan tertentu. Laporan debug panjang menyertakan kolom type yang menjelaskan alasan peristiwa sumber, peristiwa pemicu, atau laporan atribusi tidak dibuat. Laporan debug panjang tersedia mulai Chrome 109 (Stabil pada Januari 2023).
  • Kunci debug adalah ID unik yang dapat Anda tetapkan di sisi sumber dan sisi pemicu. Kunci debug memungkinkan Anda memetakan konversi berbasis cookie dan konversi berbasis atribusi. Jika Anda telah menyiapkan sistem untuk menghasilkan laporan debug dan menetapkan kunci debug, browser akan menyertakan kunci debug ini dalam semua laporan atribusi dan laporan debug.

Untuk konsep lainnya dan istilah utama yang digunakan di seluruh dokumentasi kami, lihat glosarium Privacy Sandbox.

Ada pertanyaan tentang penerapan?

Jika Anda mengalami masalah saat menyiapkan laporan debug, buat masalah di repositori dukungan developer kami dan kami akan membantu Anda memecahkan masalah tersebut.

Bersiap untuk menyiapkan laporan debug

Sebelum menyiapkan laporan debug, ikuti langkah-langkah berikut:

Pastikan Anda telah menerapkan praktik terbaik untuk integrasi API

  • Pastikan kode Anda dibatasi di balik deteksi fitur. Untuk memastikan API tidak diblokir oleh Permissions-Policy, jalankan kode berikut:

    if (document.featurePolicy.allowsFeature('attribution-reporting')) {
// the Attribution Reporting API is enabled
}

    Jika pemeriksaan deteksi fitur ini menampilkan nilai benar, API diizinkan dalam konteks (halaman) tempat pemeriksaan dijalankan.

  • (Tidak diperlukan selama fase pengujian: Periksa apakah Anda telah menetapkan Permissions-Policy)

Memperbaiki masalah integrasi mendasar

Meskipun laporan debug berguna untuk membantu Anda mendeteksi dan menganalisis kehilangan dalam skala besar, beberapa masalah integrasi dapat dideteksi secara lokal. Masalah konfigurasi header sumber dan pemicu yang salah, masalah penguraian JSON, konteks yang tidak aman (non-HTTPS), dan masalah lain yang mencegah API berfungsi akan ditampilkan di tab Masalah DevTools.

Masalah DevTools dapat berupa berbagai jenis. Jika Anda mengalami masalah invalid header, salin header ke alat validasi header. Hal ini akan membantu Anda mengidentifikasi dan memperbaiki kolom yang menyebabkan masalah.

Memvalidasi Header Pelaporan Atribusi

Anda dapat menggunakan validator header untuk memvalidasi header yang terkait dengan Attribution Reporting API. Anda dapat memantau error validasi yang berasal dari browser untuk mempermudah proses debug API.

Untuk memilih menerima laporan proses debug, balas dengan report-header-errors sebagai bagian dari header respons Attribution-Reporting-Info.

Attribution-Reporting-Info: report-header-errors

Perhatikan bahwa Attribution-Reporting-Info adalah header berstruktur kamusAttribution-Reporting-Info, sehingga memberikan kunci boolean report-header-errors menyiratkan nilai benar (true).

Laporan debug segera dikirim ke endpoint pelaporan:

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

Data laporan disertakan dalam isi permintaan sebagai daftar objek JSON yang memiliki bentuk ini:

[{
  "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
  }
}]
Alat validasi header
Alat validasi header

Menyiapkan laporan debug: langkah-langkah umum untuk laporan keberhasilan dan laporan panjang

Tetapkan cookie berikut di origin pelaporan:

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

Browser akan memeriksa keberadaan cookie ini pada pendaftaran sumber dan pemicu. Laporan debug keberhasilan hanya akan dibuat jika cookie ada pada kedua waktu tersebut.

Kode demo: debug cookie

Perhatikan bahwa laporan debug dapat diaktifkan untuk browser dalam Mode B, dengan cookie pihak ketiga dinonaktifkan untuk memfasilitasi pengujian dan persiapan penghentian penggunaan cookie pihak ketiga. Untuk browser dalam Mode B, Anda tidak perlu menyetel cookie debug untuk mengaktifkan laporan debug. Lanjutkan ke langkah 2 untuk menyiapkan kunci debug untuk laporan debug keberhasilan.

Langkah 2: Setel kunci debug

Setiap kunci debug harus berupa bilangan bulat tanpa tanda tangan 64-bit yang diformat sebagai string base-10. Buat setiap kunci debug menjadi ID unik. Laporan debug keberhasilan hanya akan dibuat jika kunci debug ditetapkan.

  • Petakan kunci debug sisi sumber ke informasi waktu sumber tambahan yang menurut Anda relevan untuk di-debug.
  • Petakan kunci debug sisi pemicu ke informasi waktu pemicu tambahan yang menurut Anda relevan untuk proses debug.

Misalnya, Anda dapat menetapkan kunci debug berikut:

  • ID Cookie + Stempel waktu sumber sebagai kunci debug sumber (dan ambil stempel waktu yang sama di sistem berbasis cookie Anda)
  • ID Cookie + Stempel waktu pemicu sebagai kunci debug pemicu (dan ambil stempel waktu yang sama di sistem berbasis cookie Anda)

Dengan demikian, Anda dapat menggunakan informasi konversi berbasis cookie untuk mencari laporan debug atau laporan atribusi yang sesuai. Pelajari lebih lanjut di Bagian 3: Cookbook.

Buat kunci debug sisi sumber berbeda dari source_event_id, sehingga Anda dapat membedakan setiap laporan yang memiliki ID peristiwa sumber yang sama.

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

Kode demo: kunci debug sumber Kode demo: kunci pemicu debug

Menyiapkan laporan debug keberhasilan

Contoh kode di bagian ini menghasilkan laporan debug keberhasilan untuk laporan tingkat peristiwa dan laporan gabungan. Laporan tingkat peristiwa dan yang dapat digabungkan menggunakan kunci debug yang sama.

Langkah 3: Siapkan endpoint untuk mengumpulkan laporan debug keberhasilan

Siapkan endpoint untuk mengumpulkan laporan debug. Endpoint ini harus mirip dengan endpoint atribusi utama, dengan string debug tambahan di jalur:

  • Endpoint untuk laporan debug keberhasilan tingkat peristiwa: https://adtech.example/.well-known/attribution-reporting/debug/report-event-attribution
    • Endpoint untuk laporan debug keberhasilan gabungan: https://adtech.example/.well-known/attribution-reporting/debug/report-aggregate-attribution

Saat atribusi dipicu, browser akan segera mengirimkan laporan debug menggunakan permintaan POST ke endpoint ini. Kode server Anda untuk menangani laporan debug keberhasilan yang masuk mungkin terlihat seperti berikut (di sini pada endpoint node):

// 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);
  }
);

Kode demo: endpoint laporan debug tingkat peristiwa

Kode demo: endpoint laporan debug yang dapat diagregasi

Langkah 4: Konfirmasi bahwa penyiapan Anda akan menghasilkan laporan debug keberhasilan

  • Buka chrome://attribution-internals di browser Anda.
  • Pastikan kotak centang Tampilkan Laporan Debug dicentang, baik di tab Laporan Tingkat Peristiwa maupun Laporan Gabungan.
  • Buka situs tempat Anda menerapkan Pelaporan Atribusi. Selesaikan langkah-langkah yang Anda gunakan untuk membuat laporan atribusi; langkah-langkah yang sama ini akan membuat laporan debug keberhasilan.
  • Dalam chrome://attribution-internals:
    • Pastikan laporan atribusi dibuat dengan benar.
    • Di tab Laporan Tingkat Peristiwa dan tab Laporan yang Dapat Digabungkan, periksa apakah laporan debug yang berhasil juga dibuat. Mengenali mereka dalam daftar dengan jalur debug biru mereka.
Internal atribusi
Internal atribusi
  • Di server Anda, verifikasi bahwa endpoint Anda segera menerima laporan debug keberhasilan ini. Pastikan untuk memeriksa laporan debug keberhasilan tingkat peristiwa dan gabungan.
Melaporkan log server asal
Melaporkan log server asal

Langkah 5: Amati laporan debug kesuksesan

Laporan debug keberhasilan identik dengan laporan atribusi, dan berisi kunci debug sisi sumber dan sisi pemicu.

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

Menyiapkan laporan debug panjang

Langkah 3: Aktifkan proses debug verbose di header sumber dan pemicu

Tetapkan debug_reporting ke true di Attribution-Reporting-Register-Source dan Attribution-Reporting-Register-Trigger.

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
}

Kode demo: source header

Kode demo: pemicu header

Langkah 4: Siapkan endpoint untuk mengumpulkan laporan debug verbose

Siapkan endpoint untuk mengumpulkan laporan debug. Endpoint ini harus mirip dengan endpoint atribusi utama, dengan string debug/verbose tambahan di jalur:

https://adtech.example/.well-known/attribution-reporting/debug/verbose

Saat laporan debug verbose dibuat, yaitu saat sumber atau pemicu tidak terdaftar, browser akan segera mengirim laporan debug verbose menggunakan permintaan POST ke endpoint ini. Kode server Anda untuk menangani laporan debug verbose masuk mungkin terlihat seperti berikut (di sini pada endpoint node):

// 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);
  }
);

Tidak seperti laporan debug keberhasilan, hanya ada satu endpoint untuk laporan panjang. Laporan verbose yang terkait dengan laporan tingkat peristiwa dan laporan gabungan akan dikirim ke endpoint yang sama.

Kode demo: laporan debug panjang endpoint

Langkah 5: Konfirmasi bahwa penyiapan Anda akan menghasilkan laporan debug verbose

Meskipun ada banyak jenis laporan proses debug panjang, cukup untuk memeriksa penyiapan proses debug panjang Anda hanya dengan satu jenis laporan proses debug panjang. Jika satu jenis laporan debug verbose ini dibuat dan diterima dengan benar, berarti semua jenis laporan debug verbose juga akan dibuat dan diterima dengan benar, karena semua laporan debug verbose menggunakan konfigurasi yang sama dan dikirim ke endpoint yang sama.

  1. Buka chrome://attribution-internals di browser Anda.
  2. Memicu atribusi (konversi) di situs Anda yang disiapkan dengan Attribution Reporting. Mengingat tidak ada engagement iklan (tayangan atau klik) sebelum konversi ini, Anda dapat mengharapkan laporan debug verbose jenis trigger-no-matching-source akan dibuat.
  3. Di chrome://attribution-internals, buka tab Laporan proses debug panjang dan periksa apakah laporan proses debug panjang jenis trigger-no-matching-source telah dibuat.
  4. Di server Anda, verifikasi bahwa endpoint Anda telah segera menerima laporan debug verbose ini.

Langkah 6: Amati laporan debug panjang

Laporan debug panjang yang dibuat pada waktu pemicu mencakup kunci debug sisi sumber dan sisi pemicu (jika ada sumber yang cocok untuk pemicu). Laporan debug panjang yang dibuat pada waktu sumber mencakup kunci debug sisi sumber.

Contoh permintaan yang berisi laporan proses debug panjang, yang dikirim oleh browser:

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

Setiap laporan panjang berisi kolom-kolom berikut:

Type
Penyebab laporan dibuat. Untuk mempelajari semua jenis laporan verbose dan tindakan yang harus dilakukan bergantung pada setiap jenis, tinjau referensi laporan verbose di Bagian 3: Cookbook debugging.
Body
Isi laporan. Hal ini akan bergantung pada jenisnya. Tinjau referensi laporan verbose di Bagian 3: Buku panduan debugging.

Isi permintaan akan berisi minimal satu, dan maksimal dua laporan verbose:

  • Satu laporan verbose jika kegagalan hanya memengaruhi laporan tingkat peristiwa (atau jika hanya memengaruhi laporan gabungan). Kegagalan pendaftaran sumber atau pemicu hanya memiliki satu alasan; oleh karena itu, satu laporan verbose dapat dibuat per kegagalan dan per jenis laporan (tingkat peristiwa atau gabungan).
  • Dua laporan verbose jika kegagalan memengaruhi laporan tingkat peristiwa dan laporan gabungan—dengan pengecualian: jika alasan kegagalan sama untuk laporan tingkat peristiwa dan laporan gabungan, hanya satu laporan verbose yang dibuat (contoh: trigger-no-matching-source)

Berikutnya

Bagian 3: Cookbook proses debug