Bagian 2 dari 3 tentang proses debug Attribution Reporting. Menyiapkan laporan debug.
Glosarium
- Asal pelaporan adalah origin
yang [menetapkan header sumber dan pemicu Attribution Reporting.
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 gabungan) yang berisi data pengukuran yang Anda minta.
- Laporan debug berisi data tambahan tentang laporan atribusi, atau tentang sumber atau peristiwa pemicu. Menerima laporan debug bukan berarti ada 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. Model atribusi 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 penyebab
tidak adanya laporan tersebut. Kejadian ini menunjukkan kasus saat browser tidak mencatat peristiwa sumber
atau pemicu (yang berarti browser tidak akan menghasilkan 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 sudah menyiapkan sistem untuk menghasilkan laporan debug dan menetapkan kunci debug, browser akan menyertakan kunci debug ini di semua laporan atribusi dan laporan debug.
Untuk mengetahui konsep dan istilah utama lainnya yang digunakan di seluruh dokumentasi kami, lihat glosarium Privacy Sandbox.
Ada pertanyaan tentang penerapan?
Jika Anda mengalami masalah saat menyiapkan laporan debug, laporkan masalah di repositori dukungan developer dan kami akan membantu Anda memecahkan masalah tersebut.
Bersiap untuk menyiapkan laporan debug
Sebelum menyiapkan laporan debug, ikuti langkah-langkah berikut:
Memastikan bahwa Anda telah menerapkan praktik terbaik untuk integrasi API
Pastikan kode Anda dilindungi dengan deteksi fitur. Untuk memastikan API tidak diblokir oleh Kebijakan Izin, jalankan kode berikut:
if (document.featurePolicy.allowsFeature('attribution-reporting')) { // the Attribution Reporting API is enabled }
Jika pemeriksaan deteksi fitur ini menampilkan nilai benar, API akan diizinkan dalam konteks (halaman) tempat pemeriksaan dijalankan.
(Tidak diperlukan selama fase pengujian: Pastikan Anda telah menetapkan Kebijakan Izin)
Memperbaiki masalah integrasi dasar
Meskipun laporan debug berguna untuk membantu Anda mendeteksi dan menganalisis kerugian dalam skala besar, beberapa masalah integrasi dapat dideteksi secara lokal. Masalah kesalahan konfigurasi header sumber dan pemicu, masalah penguraian JSON, konteks yang tidak aman (non-HTTPS), dan masalah lain yang mencegah API berfungsi akan muncul di tab Masalah DevTools.
Masalah DevTools bisa memiliki jenis yang berbeda. Jika Anda mengalami masalah invalid header
, salin header ke alat validator
header. Tindakan ini
akan membantu Anda mengidentifikasi dan memperbaiki kolom yang menyebabkan masalah.
Menyiapkan laporan debug: langkah-langkah umum untuk membuat laporan keberhasilan dan laporan panjang
Tetapkan cookie berikut di asal 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.
Perhatikan bahwa laporan debug dapat diaktifkan untuk browser di Mode B, dengan penonaktifan cookie pihak ketiga guna memfasilitasi pengujian dan persiapan untuk penghentian penggunaan cookie pihak ketiga. Untuk browser di Mode B, Anda tidak perlu menetapkan cookie debug untuk mengaktifkan laporan debug. Lanjutkan ke langkah 2 untuk menyiapkan kunci debug untuk laporan debug yang berhasil.
Langkah 2: Menetapkan kunci debug
Setiap kunci debug harus berupa bilangan bulat tanpa tanda tangan 64-bit yang diformat sebagai string base-10. Jadikan setiap kunci debug sebagai ID unik. Laporan debug keberhasilan hanya akan dibuat jika kunci debug telah 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 di-debug.
Misalnya, Anda dapat menetapkan kunci debug berikut:
- ID Cookie + Stempel waktu sumber sebagai kunci debug sumber (dan ambil stempel waktu yang sama tersebut dalam sistem berbasis cookie)
- ID Cookie + Stempel waktu pemicu sebagai kunci debug pemicu (dan catat stempel waktu yang sama tersebut dalam sistem berbasis cookie)
Dengan ini, 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 dengan 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 debug pemicu
Menyiapkan laporan debug keberhasilan
Kode contoh di bagian ini menghasilkan laporan debug keberhasilan untuk laporan tingkat peristiwa dan laporan agregat. Laporan tingkat peristiwa dan laporan agregat menggunakan kunci debug yang sama.
Langkah 3: Menyiapkan endpoint untuk mengumpulkan laporan debug yang berhasil
Menyiapkan 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 agregat:
https://adtech.example/.well-known/attribution-reporting/debug/report-aggregate-attribution
- Endpoint untuk laporan debug keberhasilan agregat:
Saat atribusi dipicu, browser akan segera mengirimkan laporan
debug melalui permintaan POST
ke endpoint ini. Kode server Anda untuk menangani
laporan debug keberhasilan yang masuk mungkin terlihat sebagai berikut (di sini di 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 agregat
Langkah 4: Pastikan penyiapan Anda akan membuat laporan debug keberhasilan
- Buka
chrome://attribution-internals
di browser Anda. - Pastikan kotak centang Tampilkan Laporan Debug dicentang, di tab Laporan Tingkat Peristiwa dan Laporan Gabungan.
- Buka situs tempat Anda menerapkan Attribution Reporting. Selesaikan langkah-langkah yang Anda gunakan untuk membuat laporan atribusi; langkah yang sama ini akan membuat laporan debug keberhasilan.
- Di
chrome://attribution-internals
:- Periksa apakah laporan atribusi dibuat dengan benar.
- Di tab Laporan Tingkat Peristiwa dan tab Laporan Gabungan,
pastikan laporan debug keberhasilan juga dibuat. Kenali mereka
dalam daftar dengan jalur
debug
berwarna biru.
- Di server, pastikan endpoint Anda segera menerima laporan debug keberhasilan ini. Pastikan Anda memeriksa laporan debug keberhasilan tingkat peristiwa dan agregat.
Langkah 5: Amati laporan debug keberhasilan
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: Gunakan proses debug panjang 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
}
Langkah 4: Menyiapkan endpoint untuk mengumpulkan laporan debug panjang
Menyiapkan 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 panjang dibuat, yaitu saat sumber atau pemicu tidak
terdaftar, browser akan segera mengirimkan laporan debug panjang melalui
permintaan POST
ke endpoint ini. Kode server Anda untuk menangani laporan debug panjang
yang masuk mungkin terlihat sebagai berikut (di sini, di 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 yang berhasil, laporan panjang hanya memiliki satu endpoint. Laporan panjang yang terkait dengan laporan gabungan dan tingkat peristiwa akan dikirim ke endpoint yang sama.
Kode demo: endpoint laporan debug panjang
Langkah 5: Pastikan penyiapan Anda akan menghasilkan laporan debug panjang
Meskipun ada banyak jenis laporan debug panjang, Anda cukup memeriksa penyiapan proses debug panjang dengan hanya satu jenis laporan debug panjang. Jika satu jenis laporan debug panjang ini dibuat dan diterima dengan benar, ini berarti semua jenis laporan debug panjang juga akan dibuat dan diterima dengan benar, karena semua laporan debug panjang menggunakan konfigurasi yang sama dan dikirim ke endpoint yang sama.
- Buka
chrome://attribution-internals
di browser Anda. - Picu atribusi (konversi) di situs Anda yang disiapkan dengan Pelaporan
Atribusi. Karena tidak ada interaksi iklan (tayangan atau klik)
sebelum konversi ini, Anda akan membuat laporan debug panjang dari jenis
trigger-no-matching-source
. - Di
chrome://attribution-internals
, buka tab Laporan debug panjang dan pastikan laporan debug panjang dari jenistrigger-no-matching-source
telah dibuat. - Di server, pastikan endpoint Anda telah segera menerima laporan debug panjang ini.
Langkah 6: Amati laporan debug panjang
Laporan debug panjang yang dibuat pada waktu pemicu akan menyertakan kunci debug sisi sumber dan sisi pemicu (jika ada sumber yang cocok untuk pemicu tersebut). Laporan debug panjang yang dibuat pada waktu sumber menyertakan kunci debug sisi sumber.
Contoh permintaan yang berisi laporan 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 panjang dan tindakan yang harus diambil bergantung pada setiap jenis, tinjau referensi laporan panjang di Bagian 3: Proses debug cookbook.
Body
- Isi laporan. Hal itu akan bergantung pada jenisnya. Tinjau referensi laporan panjang di Bagian 3: Proses debug cookbook.
Isi permintaan akan berisi minimal satu laporan panjang, dan maksimal dua laporan panjang:
- Satu laporan panjang jika kegagalan hanya memengaruhi laporan tingkat peristiwa (atau jika hanya memengaruhi laporan agregat). Kegagalan pendaftaran sumber atau pemicu hanya memiliki satu alasan. Oleh karena itu, satu laporan panjang dapat dibuat per kegagalan dan per jenis laporan (tingkat peristiwa atau gabungan).
- Dua laporan panjang jika kegagalan memengaruhi laporan tingkat peristiwa dan
gabungan—dengan pengecualian: jika alasan kegagalan sama untuk laporan tingkat
peristiwa dan laporan agregat, hanya satu laporan panjang yang akan dibuat (contoh:
trigger-no-matching-source
)