Buku resep proses debug Pelaporan Atribusi

Bagian 3 dari 3 tentang proses debug Pelaporan Atribusi. Temukan petunjuk tentang cara menggunakan laporan debug.

Catatan: Artikel ini adalah bagian dari rangkaian tentang proses debug Attribution Reporting API. Rangkaian ini mencakup proses debug sisi klien untuk laporan tingkat peristiwa dan laporan gabungan. Panduan proses debug sisi server untuk laporan ringkasan tersedia di GitHub.

Dalam cookbook ini, Anda akan menemukan petunjuk cara menggunakan laporan debug untuk berbagai kasus penggunaan yang diuraikan dalam Bagian 1: Pengantar laporan debug.

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.

Cara: Memeriksa integrasi Anda secara real time

1. Siapkan sistem Anda untuk membuat laporan debug sukses. Lihat caranya di Bagian 2: Menyiapkan laporan Debug.
2. Setiap kali Anda men-deploy kode Pelaporan Atribusi, periksa secara real time apakah Anda menerima beberapa laporan debug sukses di endpoint. Jika demikian, penyiapan Pelaporan Atribusi Anda berfungsi.
3. Laporan debug sukses hanya dikirim saat konversi terjadi. Sebagai gantinya, sebaiknya periksa apakah integrasi Anda disiapkan dengan benar, terlepas dari konversi—yaitu, Anda ingin memeriksa apakah sumber berhasil didaftarkan. Untuk mencapai hal ini, Anda dapat mengandalkan laporan debug panjang keberhasilan pendaftaran sumber. Lihat cara menyiapkannya di Bagian 2: Menyiapkan laporan Debug.

Perhatian: Ini hanya pemeriksaan dasar. Penerapan Anda mungkin masih berisi bug, dan faktor lain akan menyebabkan hilangnya data pengukuran. Untuk pemeriksaan lanjutan lainnya, tinjau kasus penggunaan lainnya.

Cara: Menganalisis kerugian dan memecahkan masalah integrasi

Untuk membandingkan hasil pengukuran konversi berbasis cookie dengan laporan Pelaporan Atribusi, gunakan kunci debug dan petakan konversi cookie dengan laporan debug. Ingat bahwa laporan debug langsung dikirim ke endpoint Anda.

Ringkasan

Gunakan kunci debug (pasangan <source_debug_key, trigger_debug_key>) untuk memetakan konversi cookie ke laporan debug keberhasilan. Untuk setiap konversi cookie, pada waktu konversi, apakah Anda menerima laporan debug keberhasilan yang sesuai?

Jika ya: untuk semua laporan debug sukses ini, Anda akan menerima laporan atribusi nanti—dengan beberapa pengecualian. Tinjau Skenario laporan debug sukses untuk mengetahui detailnya.

Jika tidak: artinya konversi tidak terdaftar di Pelaporan Atribusi. Gunakan pasangan <source_debug_key, trigger_debug_key> (atau kunci debug sumber jika kunci debug pemicu tidak ada) untuk memetakan konversi cookie ke laporan debug panjang. Untuk setiap konversi ini, apakah Anda pernah menerima laporan debug panjang yang sesuai pada suatu waktu (waktu sumber atau pemicu)?

• Jika Anda tidak menerima laporan debug panjang: hal ini mungkin disebabkan oleh perilaku pengguna atau masalah integrasi. Tinjau skenario tanpa laporan debug untuk mengetahui detailnya.

• Jika Anda menerima laporan debug panjang, lihat kolom type-nya.

  • Jika type-nya adalah source-success: ini berarti sumber berhasil didaftarkan, tetapi pemicunya tidak. Untuk mempersempit alasan laporan debug sukses tidak ada, cari laporan debug panjang yang sesuai dari jenis lainnya⏤laporan tersebut akan menunjukkan masalah di sisi pemicu.

  • Jika type-nya adalah yang lain: sumber atau pemicu belum terdaftar. type memberi tahu Anda alasannya. Laporan atribusi yang sesuai (dan laporan debug sukses) tidak akan ada. Bergantung pada type laporan debug panjang, Anda dapat menggunakan informasi ini sebagai titik data analisis kerugian (dengan kata lain, tidak ada tindakan yang perlu Anda lakukan), atau Anda dapat melaporkan bug atau memecahkan masalah implementasi. Tinjau skenario laporan debug panjang untuk mengetahui detailnya.

Poin penting: Laporan debug sukses dikirim saat browser berhasil membuat laporan tingkat peristiwa atau laporan gabungan. Di sisi lain, sebagian besar laporan debug panjang dikirim saat sumber atau pemicu tidak berhasil didaftarkan—kecuali untuk laporan debug panjang keberhasilan pendaftaran sumber.

Catatan: Dalam ringkasan ini, kami menjelaskan cara menjalankan analisis komprehensif, termasuk memecahkan masalah implementasi yang mungkin terjadi. Namun, Anda mungkin berada dalam fase pengujian saat hanya ingin berfokus pada penghapusan masalah penerapan, tanpa harus menjalankan analisis kerugian yang komprehensif dan menunggu kumpulan konversi tertentu. Dalam hal ini, Anda dapat langsung melihat jenis laporan panjang tertentu yang mungkin menunjukkan masalah penerapan saat menerimanya.

Kemungkinan skenario

Laporan debug sukses

Jika untuk konversi cookie tertentu, Anda menerima laporan debug berhasil, artinya konversi ini berhasil didaftarkan dengan Pelaporan Atribusi.

Anda akan menerima laporan atribusi untuk konversi ini nanti⏤dengan beberapa pengecualian:

• Perilaku pengguna: menghapus data setelah konversi dan sebelum laporan atribusi dikirim, menutup browser, dll. Jika pengguna menutup browser setelah melakukan konversi dan tidak membuka browser selama seminggu, laporan tidak akan dikirim selama seminggu atau lebih. Anda mungkin menganggap keterlambatan ini sebagai kerugian.
• Hanya berlaku untuk Tingkat Peristiwa: Laporan tingkat peristiwa diganti dengan laporan lain yang memiliki prioritas lebih tinggi.
• Kemungkinan masalah jaringan.

Catatan: Jika browser mencoba mengirim laporan, tetapi gagal karena masalah jaringan, browser akan mencoba lagi dua kali sebelum akhirnya menyerah.

Laporan debug panjang dari jenis source-success

Jika untuk sumber konversi cookie tertentu, Anda menerima laporan debug panjang jenis source-success, artinya pendaftaran sumber berhasil. Bergantung pada apakah pendaftaran pemicu juga berhasil nanti, Anda mungkin akan menerima atau tidak menerima laporan untuk konversi tersebut.

Ada satu peringatan untuk hal ini:

Poin penting: Laporan debug panjang keberhasilan pendaftaran sumber dikirim meskipun batas origin pelaporan yang tidak diatribusikan tercapai. Pesan ini dikirim karena alasan keamanan, meskipun pendaftaran sumber sebenarnya tidak berhasil dalam kasus tersebut.

Laporan debug panjang dari jenis lainnya

Jika untuk konversi cookie tertentu, Anda menerima laporan debug panjang dari jenis lain, Anda tidak akan menerima laporan debug sukses, sehingga tidak ada laporan atribusi di lain waktu⏤karena laporan panjang berarti terjadi kegagalan yang dapat dilaporkan. Ada sesuatu yang mencegah pendaftaran sumber, pendaftaran pemicu, pembuatan laporan, atau pengiriman laporan. Kemungkinan penyebab:

• Batasan privasi
• Batas penyimpanan
• Aturan khusus
• Masalah penerapan dalam kode Anda
• Bug browser

Beberapa di antaranya sudah diperkirakan. Tindakan yang akan diambil bergantung pada type setiap laporan panjang. Tinjau referensi laporan panjang.

Tidak ada laporan debug

Jika untuk konversi cookie tertentu, Anda hanya menerima laporan atribusi (tidak ada laporan debug sukses atau laporan debug panjang), artinya ada sesuatu yang mencegah laporan debug dibuat. Kemungkinan penyebab:

• Preferensi pengguna (pengguna telah menonaktifkan cookie pihak ketiga)
• Cookie tidak ada, atau kunci debug tidak ada (kunci debug dihapus karena cookie tidak ada). Di chrome://attribution-internals, buka tab Logs dan periksa apakah ada masalah yang muncul di sana.
• Masalah jaringan yang terjadi pada waktu sumber atau pemicu, tetapi tidak saat laporan atribusi dikirim.

Apakah Anda menerima laporan atribusi?

Ini adalah subkasus dari tidak menerima laporan debug: jika untuk konversi cookie tertentu, Anda tidak menerima laporan apa pun (tidak ada laporan debug apa pun, tidak ada laporan atribusi), ini berarti terjadi kegagalan yang tidak dapat dilaporkan. Kemungkinan penyebab:

• Masalah integrasi mendasar. Tinjau cara memecahkan masalah ini di Memperbaiki masalah integrasi mendasar.
• Kemungkinan masalah jaringan.
• Preferensi pengguna di setelan browser seperti Privacy Sandbox dinonaktifkan.

Referensi laporan debug panjang

Setiap laporan debug panjang memiliki kolom type yang mencatat alasan laporan atribusi yang sesuai dihapus. Gunakan referensi untuk mengetahui tindakan yang harus diambil untuk setiap type laporan panjang.

Catatan: Jika type laporan panjang dimulai dengan trigger-event, laporan tersebut hanya dapat dibuat untuk peristiwa sumber atau pemicu yang terkait dengan laporan tingkat peristiwa. Jika type laporan panjang dimulai dengan trigger-aggregate, laporan tersebut hanya dapat dibuat untuk peristiwa sumber atau pemicu yang dikaitkan dengan laporan gabungan. Dalam kasus lain, laporan ini ditujukan untuk laporan tingkat peristiwa atau laporan gabungan.

Pendaftaran sumber berhasil

Sumber berhasil didaftarkan.

source-success

Detail dan isi laporan

Poin penting: Laporan debug panjang keberhasilan pendaftaran sumber dikirim meskipun batas asal pelaporan yang tidak diatribusikan tercapai. Pesan ini dikirim karena alasan keamanan, meskipun pendaftaran sumber sebenarnya tidak berhasil dalam kasus tersebut.

Laporan batasan privasi

Laporan ini sudah diperkirakan. Batasan ini menunjukkan batasan privasi untuk mengurangi kebocoran identitas pengguna lintas situs.

source-destination-limit

Detail dan isi laporan

source-noised

Detail dan isi laporan

trigger-attributions-per-source-destination-limit

Detail dan isi laporan

trigger-reporting-origin-limit

Detail dan isi laporan

trigger-event-noise

Detail dan isi laporan

trigger-event-excessive-reports

Nilai ini dihasilkan jika jumlah laporan melebihi batas; Anda dapat mendaftarkan maksimal satu konversi untuk penayangan, dan tiga untuk klik. Perhatikan bahwa Anda dapat mengonfigurasi laporan yang akan diterima dengan menetapkan prioritas. Detail dan isi laporan

Laporan batasan penyimpanan

Laporan ini sudah diperkirakan. Batasan ini menunjukkan batasan penyimpanan untuk mencegah penggunaan resource yang berlebihan.

source-storage-limit

Detail dan isi laporan

trigger-event-storage-limit

Detail dan isi laporan

trigger-aggregate-storage-limit

Detail dan isi laporan

Laporan aturan kustom

Laporan ini akan muncul jika Anda menggunakan pemfilteran, penghapusan duplikat, prioritas, atau pemfilteran berbasis periode. Untuk berjaga-jaga, periksa kembali aturan kustom yang sesuai untuk mengonfirmasi bahwa laporan yang sesuai dengan laporan panjang tersebut memang laporan yang ingin Anda hapus. Jika ini benar, Anda tidak perlu melakukan tindakan apa pun.

trigger-no-matching-filter-data

Detail dan isi laporan

trigger-event-no-matching-configuration

Detail dan isi laporan

trigger-event-deduplicated

Detail dan isi laporan

trigger-aggregate-deduplicated

Detail dan isi laporan

trigger-event-low-priority

Detail dan isi laporan

trigger-event-report-window-passed

Detail dan isi laporan

trigger-aggregate-report-window-passed

Detail dan isi laporan

Laporan panjang lainnya

Laporan ini dapat menunjukkan potensi masalah penerapan dalam kode Anda.

trigger-no-matching-source

Ini mungkin merupakan masalah implementasi. Pastikan tidak ada kesalahan konfigurasi dalam penyiapan <reporting origin, destination> Anda. Perilaku ini mungkin juga merupakan perilaku API yang diharapkan. Misalnya, pengguna telah menghapus data pada suatu waktu setelah berinteraksi dengan iklan dan sebelum melakukan konversi, atau pengguna melakukan konversi tanpa pernah melihat iklan terkait. Detail dan isi laporan

trigger-aggregate-no-contributions

Ini mungkin bukan perilaku yang Anda inginkan untuk kode Anda. Pecahkan masalah kode pendaftaran pemicu; pastikan konfigurasi kontribusi Anda sudah benar. Detail dan isi laporan

trigger-aggregate-insufficient-budget

Ini mungkin bukan perilaku yang Anda inginkan untuk kode Anda. Periksa kembali kode pendaftaran pemicu untuk memastikan bahwa jumlah semua kontribusi tidak melebihi anggaran kontribusi. Detail dan isi laporan

Error tidak terduga (potensi bug browser)

Laporan ini tidak terduga. Hal ini mungkin disebabkan oleh bug browser. Laporkan bug dan tentukan langkah-langkah untuk mereproduksinya dalam deskripsi Anda.

source-unknown-error

Detail dan isi laporan

trigger-unknown-error

Detail dan isi laporan

Contoh analisis kerugian

Langkah 1: Penyiapan dan pemetaan dengan cookie

Ikuti petunjuk di Bagian 2: Menyiapkan laporan debug untuk menyiapkan sistem Anda guna membuat laporan debug sukses dan laporan debug panjang.

Dengan demikian, Anda dapat menggunakan informasi konversi berbasis cookie untuk mencari laporan debug atau laporan atribusi yang sesuai.

Langkah 2: Identifikasi pendaftaran yang berhasil dan laporan yang tidak ada

Dalam contoh ini, asumsikan Anda telah melacak 100 konversi dengan sistem berbasis cookie.

Setiap kali Anda mencatat konversi berbasis cookie, cari laporan debug sukses (langsung dikirim) yang memiliki pasangan <source_debug_key, trigger_debug_key> yang sama dengan konversi berbasis cookie ini.

Misalkan Anda telah menerima laporan debug sukses untuk 70 konversi cookie ini.

• Laporan keberhasilan berarti atribusi telah berhasil dicatat, sehingga Anda dapat mengasumsikan bahwa Anda akan mendapatkan laporan atribusi yang sesuai dengan setiap laporan keberhasilan—dengan beberapa pengecualian.
• Anda dapat memutuskan untuk memantau pengecualian ini. Untuk melakukannya, saat laporan atribusi dikirim ke endpoint Anda selama beberapa hari/minggu ke depan (bergantung pada masa berlakunya), cari laporan atribusi yang memiliki pasangan kunci debug yang sama dengan setiap laporan debug yang berhasil. Pastikan untuk menunggu sebentar: laporan mungkin tidak langsung dikirim pada akhir setiap periode. Anggaplah Anda hanya menemukan 60 laporan atribusi. 10 laporan atribusi yang hilang mungkin disebabkan oleh perilaku pengguna.

Catatan: Anda mungkin memiliki laporan atribusi tingkat peristiwa yang tidak dipetakan ke konversi berbasis cookie. Laporan ini kemungkinan besar berisi laporan berisi derau yang dibuat secara acak oleh API. Anda dapat mengonfirmasinya dengan mencari laporan panjang debug jenis source-noised yang memiliki kunci debug sumber yang sama dengan laporan tingkat peristiwa Anda.

Langkah 3: Penilaian kerugian singkat

100-70 = 30 laporan debug sukses tidak ada. Artinya, 30 konversi ini (yang dilacak dalam penerapan berbasis cookie Anda) tidak dicatat dengan Pelaporan Atribusi. Anda tidak akan menerima laporan atribusi untuk hal ini.

Karena Anda memiliki 100 konversi berbasis cookie dan hanya 70 konversi berbasis atribusi, kerugian Anda adalah 30%. Sekarang Anda memiliki penilaian kerugian singkat.

Langkah 4: Menganalisis penyebab

Untuk menyelidiki penyebab laporan ini tidak ada, cari laporan proses debug panjang yang sesuai yang Anda terima pada waktu konversi (pendaftaran pemicu) atau sebelumnya pada waktu pendaftaran sumber. Gunakan kunci konversi berbasis cookie untuk memetakan konversi tersebut ke laporan debug panjang.

• Misalkan ada 10 kunci yang tidak memiliki laporan debug panjang. Periksa apakah ada masalah integrasi. Jika tidak, hal ini mungkin disebabkan oleh perilaku pengguna.
• Anda memiliki 20 laporan debug panjang. Sekarang Anda dapat menyaring analisis kerugian. Analisis kolom type dari setiap laporan panjang. Misalnya, Anda mungkin menemukan bahwa:
  • 10 (= 10% dalam contoh kami) laporan tidak ada karena pending destination limit
  • 5 (= 5%) laporan tidak ada karena trigger-aggregate-no-contributions.
  • 5 (= 5%) laporan tidak ada karena unknown-error.

Langkah 5: Ambil tindakan dan pecahkan masalah

Setelah mengetahui alasan laporan tidak ada, Anda dapat menindaklanjuti insight ini.

Tindakan yang akan diambil bergantung pada type setiap laporan panjang. Tinjau referensi laporan panjang untuk mengetahui detailnya. Contoh:

• pending-destination-limit adalah perlindungan privasi. Tidak ada tindakan yang perlu dilakukan. Gunakan angka ini sebagai titik data, untuk visibilitas dan pemantauan Anda sendiri.
• trigger-aggregate-no-contributions mungkin merupakan tanda masalah penerapan di pihak Anda. Analisis lebih lanjut. Gunakan detail dalam isi laporan panjang untuk memecahkan masalah dan memperbaikinya jika diperlukan.
• unknown-error mungkin merupakan tanda bug browser atau error jaringan. Jika Anda mengalaminya berulang kali, laporkan bug kepada developer browser.