Ringkasan Attribution Reporting untuk Seluler

Berikan masukan

Update terbaru

  • Memperbarui daftar perubahan yang akan datang dan masalah umum
  • Memperkenalkan konfigurasi tingkat peristiwa fleksibel lite, sebagai jembatan untuk konfigurasi tingkat peristiwa fleksibel penuh
  • Mulai September 2023, registerWebSource, registerWebTrigger, registerAppSource, dan registerAppTrigger harus menggunakan string untuk kolom yang mengharapkan nilai numerik (seperti priority, source_event_id, debug_key, trigger_data, deduplication_key, dll.)
  • Pada K4 2023, dukungan Google Cloud di Attribution Reporting API Android akan ditambahkan untuk membuat laporan ringkasan menggunakan Layanan Agregasi di Google Cloud, pengaturan waktu yang lebih spesifik dibahas di sini. Lihat panduan deployment untuk mengetahui informasi selengkapnya tentang cara menyiapkan Layanan Agregasi dengan Google Cloud.
  • Batas kapasitas perlindungan privasi yang baru untuk jumlah tujuan unik.
  • Fungsi yang diperbarui untuk filter pemicu periode lihat balik akan hadir pada Kuartal 1 2024. Lihat catatan untuk mengetahui informasi selengkapnya.

Ringkasan

Saat ini, sudah menjadi hal yang umum bagi solusi pengukuran dan atribusi seluler untuk menggunakan ID lintas pihak, seperti ID Iklan. Attribution Reporting API dirancang untuk memberikan privasi pengguna yang lebih baik dengan menghapus ketergantungan pada ID pengguna lintas pihak, dan untuk mendukung kasus penggunaan utama untuk atribusi dan pengukuran konversi di berbagai aplikasi dan di seluruh web.

API ini memiliki mekanisme struktural berikut yang menawarkan framework untuk meningkatkan privasi, yang akan dijelaskan lebih mendalam di bagian selanjutnya dalam dokumen ini:

Mekanisme sebelumnya membatasi kemampuan untuk menautkan identitas pengguna di dua aplikasi atau domain yang berbeda.

Attribution Reporting API mendukung kasus penggunaan berikut:

  • Pelaporan konversi: Membantu pengiklan mengukur performa kampanye mereka dengan menampilkan jumlah konversi (pemicu) dan nilai konversi (pemicu) di berbagai dimensi, misalnya berdasarkan kampanye, grup iklan, dan materi iklan.
  • Pengoptimalan: Memberikan laporan tingkat peristiwa yang mendukung pengoptimalan pembelanjaan iklan, dengan menyediakan data atribusi per tayangan yang dapat digunakan untuk melatih model ML.
  • Deteksi aktivitas tidak valid: Memberikan laporan yang dapat digunakan dalam deteksi dan analisis traffic tidak valid serta penipuan iklan.

Pada tingkat tinggi, Attribution Reporting API berfungsi sebagai berikut, yang akan dibahas lebih mendalam di bagian selanjutnya dalam dokumen ini:

  1. Teknologi iklan menyelesaikan proses pendaftaran untuk menggunakan Attribution Reporting API.
  2. Teknologi iklan mendaftarkan sumber atribusi—penayangan atau klik iklan—dengan Attribution Reporting API.
  3. Teknologi iklan mendaftarkan pemicu—konversi pengguna di aplikasi atau situs pengiklan—dengan Attribution Reporting API.
  4. Attribution Reporting API mencocokkan pemicu dengan sumber atribusi— atribusi konversi—dan satu atau beberapa pemicu dikirim ke luar perangkat melalui laporan tingkat peristiwa dan agregat ke teknologi iklan.

Mendapatkan akses ke Attribution Reporting API

Platform teknologi iklan perlu mendaftar untuk mengakses Attribution Reporting API, lihat Mendaftar ke akun Privacy Sandbox untuk mengetahui informasi selengkapnya.

Mendaftarkan sumber atribusi (klik atau lihat)

Attribution Reporting API menyebut tampilan dan klik iklan sebagai sumber atribusi. Untuk mendaftarkan klik iklan atau tampilan iklan, panggil registerSource(). API ini mengharapkan parameter berikut:

  • URI sumber atribusi: Platform mengirimkan permintaan ke URI ini agar dapat mengambil metadata yang terkait dengan sumber atribusi.
  • Peristiwa input: Objek InputEvent (untuk peristiwa klik) atau null (untuk peristiwa penayangan).

Saat API membuat permintaan ke URI Sumber Atribusi, teknologi iklan harus merespons dengan metadata sumber atribusi dalam header HTTP yang baru Attribution-Reporting-Register-Source, dengan kolom berikut:

  • ID peristiwa sumber: Nilai ini menunjukkan data tingkat peristiwa yang terkait dengan sumber atribusi ini (tampilan atau klik iklan). Harus berupa bilangan bulat tanpa tanda tangan 64-bit yang diformat sebagai string.
  • Tujuan: Origin dengan eTLD+1 atau nama paket aplikasi tempat terjadinya peristiwa pemicu.
  • Masa berakhir (opsional): Masa berakhir, dalam detik, adalah saat sumber harus dihapus dari perangkat. Defaultnya adalah 30 hari, dengan nilai minimum 1 hari dan nilai maksimum 30 hari. Nilai ini dibulatkan ke hari terdekat. Dapat diformat sebagai string atau bilangan bulat tanpa tanda tangan 64-bit.
  • Periode laporan peristiwa (opsional): Durasi dalam hitungan detik setelah pendaftaran sumber, ketika laporan peristiwa dapat dibuat untuk sumber ini. Jika periode laporan peristiwa telah berlalu, tetapi masa berlakunya belum berlalu, pemicu masih dapat dicocokkan dengan sumber, tetapi laporan peristiwa tidak dikirim untuk pemicu tersebut. Tidak boleh lebih besar dari Masa Berlaku. Dapat diformat sebagai string atau bilangan bulat tanpa tanda tangan 64-bit.
  • Periode laporan gabungan (opsional): Durasi dalam hitungan detik setelah pendaftaran sumber, ketika laporan gabungan dapat dibuat untuk sumber ini. Tidak boleh lebih besar dari Masa Berlaku. Dapat diformat sebagai string atau bilangan bulat tanpa tanda tangan 64-bit.
  • Prioritas sumber (opsional): Digunakan untuk memilih sumber atribusi mana yang harus dikaitkan dengan pemicu tertentu, jika beberapa sumber atribusi dapat dikaitkan dengan pemicu tersebut. Harus berupa bilangan bulat dengan tanda tangan 64-bit yang diformat sebagai string.

    Saat pemicu diterima, API akan menemukan sumber atribusi yang cocok dengan nilai prioritas sumber tertinggi dan membuat laporan. Setiap platform teknologi iklan dapat menentukan strategi prioritasnya sendiri. Untuk mengetahui detail selengkapnya tentang pengaruh prioritas terhadap pelaporan, lihat bagian contoh membuat prioritas.

    Nilai yang lebih tinggi menunjukkan prioritas yang lebih tinggi.
  • Periode atribusi penginstalan dan pascapenginstalan (opsional): Digunakan untuk menentukan atribusi peristiwa pascapenginstalan, yang akan dijelaskan kemudian dalam dokumen ini.
  • Filter data (opsional): Digunakan untuk memfilter beberapa pemicu secara selektif, sehingga akan mengabaikannya. Untuk detail lebih lanjut, lihat bagian filter pemicu di halaman ini.
  • Kunci agregasi (opsional): Menentukan segmentasi yang akan digunakan untuk laporan agregat.

Secara opsional, respons metadata sumber atribusi dapat menyertakan data tambahan di header Pengalihan pelaporan atribusi. Data ini berisi URL alihan, yang memungkinkan beberapa teknologi iklan mendaftarkan permintaan.

Panduan developer menyertakan contoh yang menunjukkan cara menerima pendaftaran sumber.

Langkah-langkah berikut menunjukkan contoh alur kerja:

  1. SDK teknologi iklan memanggil API untuk memulai pendaftaran sumber atribusi, dengan menentukan URI yang akan dipanggil oleh API:

    registerSource(
    Uri.parse("https://adtech.example/attribution_source?AD_TECH_PROVIDED_METADATA"),
    myClickEvent);

  2. API membuat permintaan ke https://adtech.example/attribution_source?AD_TECH_PROVIDED_METADATA, menggunakan salah satu header berikut:

    <!-- For click events -->
Attribution-Reporting-Source-Info: navigation

<!-- For view events -->
Attribution-Reporting-Source-Info: event

  3. Server HTTPS teknologi iklan ini membalas dengan header yang berisi hal-hal berikut:

    Attribution-Reporting-Register-Source: {
    "destination": "android-app://com.advertiser.example",
    "source_event_id": "234",
    "expiry": "60000",
    "priority": "5"
}
Attribution-Reporting-Redirect:
https://adtechpartner1.example?their_ad_click_id=567
Attribution-Reporting-Redirect:
https://adtechpartner2.example?their_ad_click_id=890

  4. API membuat permintaan ke setiap URL yang ditentukan dalam Attribution-Reporting-Redirect. Dalam contoh ini, dua URL partner teknologi iklan ditentukan, sehingga API membuat satu permintaan ke https://adtechpartner1.example?their_ad_click_id=567 dan permintaan lainnya ke https://adtechpartner2.example?their_ad_click_id=890.

  5. Server HTTPS teknologi iklan ini membalas dengan header yang berisi hal-hal berikut:

    Attribution-Reporting-Register-Source: {
    "destination": "android-app://com.advertiser.example",
    "source_event_id": "789",
    "expiry": "120000",
    "priority": "2"
}

Tiga sumber atribusi navigasi (klik) didaftarkan berdasarkan permintaan yang ditunjukkan pada langkah sebelumnya.

Mendaftarkan sumber atribusi dari WebView

WebView mendukung kasus penggunaan saat aplikasi merender iklan dalam WebView. Hal ini ditangani oleh WebView yang langsung memanggil registerSource() sebagai permintaan latar belakang. Panggilan ini mengaitkan sumber atribusi dengan aplikasi, bukan origin tingkat atas. Mendaftarkan sumber dari konten web yang disematkan dalam konteks browser juga didukung; baik pemanggil API maupun aplikasi harus menyesuaikan setelan untuk melakukannya. Lihat Mendaftarkan sumber atribusi dan pemicu dari WebView untuk mengetahui petunjuk tentang pemanggil API serta Pendaftaran pemicu dan sumber atribusi dari WebView untuk mengetahui petunjuk untuk aplikasi.

Karena teknologi iklan menggunakan kode umum di Web dan WebView, WebView mengikuti pengalihan HTTP 302 dan meneruskan pendaftaran yang valid ke platform. Kami tidak berencana mendukung header Attribution-Reporting-Redirect untuk skenario ini, tetapi hubungi kami jika Anda memiliki kasus penggunaan yang terpengaruh.

Mendaftarkan pemicu (konversi)

Platform teknologi iklan dapat mendaftarkan pemicu—konversi seperti penginstalan atau peristiwa pascapenginstalan—menggunakan metode registerTrigger().

Metode registerTrigger() mengharapkan parameter URI Pemicu. API mengirimkan permintaan ke URI ini untuk mengambil metadata yang terkait dengan pemicu.

API mengikuti pengalihan. Respons server teknologi iklan harus menyertakan header HTTP yang disebut Attribution-Reporting-Register-Trigger, yang mewakili informasi pada satu atau beberapa pemicu terdaftar. Konten {i>header<i} harus Dienkode JSON dan menyertakan kolom berikut:

  • Data pemicu: Data untuk mengidentifikasi peristiwa pemicu (3 bit untuk klik, 1 bit untuk tampilan) Harus berupa bilangan bulat dengan tanda tangan 64-bit yang diformat sebagai string.
  • Prioritas pemicu (opsional): Mewakili prioritas pemicu ini dibandingkan dengan pemicu lain untuk sumber atribusi yang sama. Harus berupa bilangan bulat 64-bit dengan tanda tangan yang diformat sebagai string. Untuk mengetahui detail selengkapnya tentang pengaruh prioritas terhadap pelaporan, lihat bagian membuat prioritas.
  • Kunci penghapusan duplikat (opsional): Digunakan untuk mengidentifikasi kasus ketika pemicu yang sama didaftarkan beberapa kali oleh platform teknologi iklan yang sama, untuk sumber atribusi yang sama. Harus berupa bilangan bulat dengan tanda tangan 64-bit yang diformat sebagai string.
  • Kunci agregasi (opsional): Daftar kamus yang menentukan kunci agregasi dan laporan agregat yang harus digabungkan nilainya.
  • Nilai agregasi (opsional): Daftar jumlah nilai yang berkontribusi ke setiap kunci.
  • Filter (opsional): Digunakan untuk memfilter pemicu atau memicu data secara selektif. Untuk detail lebih lanjut, lihat bagian filter pemicu di halaman ini.

Secara opsional, respons server teknologi iklan dapat mencakup data tambahan di header Pengalihan Pelaporan Atribusi. Data ini berisi URL alihan, yang memungkinkan beberapa teknologi iklan mendaftarkan permintaan.

Beberapa teknologi iklan dapat mendaftarkan peristiwa pemicu yang sama menggunakan pengalihan di kolom Attribution-Reporting-Redirect atau beberapa panggilan ke metode registerTrigger(). Sebaiknya gunakan kolom kunci penghapusan duplikat untuk menghindari penyertaan pemicu duplikat dalam laporan jika teknologi iklan yang sama menyediakan beberapa respons untuk peristiwa pemicu yang sama. Pelajari lebih lanjut cara dan waktu untuk menggunakan kunci penghapusan duplikat.

Panduan developer menyertakan contoh yang menunjukkan cara menerima pendaftaran pemicu.

Langkah-langkah berikut menunjukkan contoh alur kerja:

  1. SDK teknologi iklan memanggil API untuk memulai pendaftaran pemicu menggunakan URI yang telah didaftarkan sebelumnya. Lihat Mendaftar ke akun Privacy Sandbox untuk mengetahui informasi selengkapnya.

    registerTrigger(
    Uri.parse("https://adtech.example/attribution_trigger?AD_TECH_PROVIDED_METADATA"));

  2. API membuat permintaan ke https://adtech.example/attribution_trigger?AD_TECH_PROVIDED_METADATA.

  3. Server HTTPS teknologi iklan ini membalas dengan header yang berisi hal-hal berikut:

    Attribution-Reporting-Register-Trigger: {
    "event_trigger_data": [{
    "trigger_data": "1122",
    // This returns 010 for click-through conversions (CTCs) and 0 for
    // view-through conversions (VTCs) in reports
    "priority": "3",
    "deduplication_key": "3344"
    }],
}
Attribution-Reporting-Redirect: https://adtechpartner.example?app_install=567

  4. API membuat permintaan ke setiap URL yang ditentukan dalam Attribution-Reporting-Redirect. Dalam contoh ini, hanya satu URL yang ditentukan, sehingga API membuat permintaan ke https://adtechpartner.example?app_install=567.

  5. Server HTTPS teknologi iklan ini membalas dengan header yang berisi hal-hal berikut:

    Attribution-Reporting-Register-Trigger: {
"event_trigger_data":[{
  "trigger_data": "5566",
  "priority": "3",
  "deduplication_key": "3344"
}]
}

    Dua pemicu didaftarkan berdasarkan permintaan pada langkah sebelumnya.

Kemampuan atribusi

Bagian berikut menjelaskan cara Attribution Reporting API mencocokkan pemicu konversi dengan sumber atribusi.

Algoritma atribusi prioritas sumber diterapkan

Attribution Reporting API menggunakan algoritma atribusi prioritas sumber untuk mencocokkan pemicu (konversi) dengan sumber atribusi.

Parameter prioritas memberikan cara untuk menyesuaikan atribusi pemicu ke sumber:

  • Anda dapat mengatribusikan pemicu ke peristiwa iklan tertentu dibandingkan dengan pemicu lainnya. Misalnya, Anda dapat memilih untuk lebih menekankan pada klik daripada penayangan, atau berfokus pada peristiwa dari kampanye tertentu.
  • Anda dapat mengonfigurasi sumber dan pemicu atribusi sehingga jika mencapai batas kapasitas, Anda akan lebih berpeluang untuk menerima laporan yang lebih penting bagi Anda. Misalnya, Anda mungkin ingin memastikan konversi yang dapat di-bid atau konversi bernilai tinggi lebih mungkin muncul dalam laporan ini.

Dalam kasus ketika beberapa teknologi iklan mendaftarkan sumber atribusi, seperti yang dijelaskan nanti di halaman ini, atribusi ini terjadi secara independen untuk setiap teknologi iklan. Untuk setiap teknologi iklan, sumber atribusi dengan prioritas tertinggi akan diatribusikan dengan peristiwa pemicu. Jika ada beberapa sumber atribusi dengan prioritas yang sama, API akan memilih sumber atribusi yang terakhir didaftarkan. Sumber atribusi lainnya, yang tidak dipilih akan dihapus dan tidak lagi memenuhi syarat untuk atribusi pemicu di masa mendatang.

Filter pemicu

Pendaftaran sumber dan pemicu mencakup fungsi opsional tambahan untuk melakukan hal berikut:

  • Secara selektif memfilter beberapa pemicu, dan mengabaikannya secara efektif.
  • Pilih data pemicu untuk laporan tingkat peristiwa berdasarkan data sumber.
  • Memilih untuk mengecualikan pemicu dari laporan tingkat peristiwa.

Untuk memfilter pemicu secara selektif, teknologi iklan dapat menentukan data filter, yang terdiri dari kunci dan nilai, selama pendaftaran sumber dan pemicu. Jika kunci yang sama ditetapkan untuk sumber dan pemicu, pemicu akan diabaikan jika persimpangan kosong. Misalnya, sumber dapat menentukan "product": ["1234"], dengan product sebagai kunci filter dan 1234 sebagai nilainya. Jika filter pemicu ditetapkan ke "product": ["1111"], pemicu akan diabaikan. Jika tidak ada kunci filter pemicu yang cocok dengan product, filter akan diabaikan.

Skenario lain di mana platform teknologi iklan mungkin memfilter pemicu secara selektif adalah saat memaksa periode masa berlaku yang lebih singkat. Saat pendaftaran pemicu, teknologi iklan dapat menentukan (dalam hitungan detik) periode lihat balik dari saat konversi terjadi; misalnya, periode lihat balik 7 hari akan ditentukan sebagai: "_lookback_window": 604800 // 7d

Untuk menentukan apakah filter cocok, API akan memeriksa periode lihat balik terlebih dahulu. Jika tersedia, durasi waktu sejak sumber didaftarkan harus lebih kecil atau sama dengan durasi periode lihat balik.

Platform teknologi iklan juga dapat memilih data pemicu berdasarkan data peristiwa sumber. Misalnya, source_type otomatis dibuat oleh API sebagai navigation atau event. Selama pendaftaran pemicu, trigger_data dapat ditetapkan sebagai satu nilai untuk "source_type": ["navigation"] dan sebagai nilai yang berbeda untuk "source_type": ["event"].

Pemicu dikecualikan dari laporan tingkat peristiwa jika salah satu kondisi berikut berlaku:

  • Tidak ada trigger_data yang ditentukan.
  • Sumber dan pemicu menentukan kunci filter yang sama, tetapi nilainya tidak cocok. Perhatikan bahwa dalam hal ini, pemicu akan diabaikan untuk laporan tingkat peristiwa dan gabungan.

Atribusi pascapenginstalan

Dalam beberapa kasus, pemicu pascapenginstalan perlu dikaitkan ke sumber atribusi yang sama yang mendorong penginstalan, meskipun ada sumber atribusi lain yang memenuhi syarat dan muncul baru-baru ini.

API dapat mendukung kasus penggunaan ini dengan mengizinkan teknologi iklan menetapkan periode atribusi pascapenginstalan:

  • Saat mendaftarkan sumber atribusi, tentukan periode atribusi penginstalan ketika penginstalan diharapkan terjadi (umumnya 2-7 hari, rentang yang diterima 1 hingga 30 hari). Tentukan interval waktu ini dalam detik.
  • Saat mendaftarkan sumber atribusi, tentukan periode eksklusivitas atribusi pasca-penginstalan ketika setiap peristiwa pemicu pasca-penginstalan harus dikaitkan dengan sumber atribusi yang mendorong penginstalan (umumnya 7-30 hari, rentang yang diterima 0 hingga 30 hari). Tentukan interval waktu ini dalam detik.
  • Attribution Reporting API memvalidasi saat penginstalan aplikasi terjadi dan secara internal mengatribusikan penginstalan ke sumber atribusi prioritas sumber. Namun, penginstalan tidak dikirim ke teknologi iklan dan tidak dihitung terhadap batas kapasitas masing-masing platform.
  • Validasi penginstalan aplikasi tersedia untuk aplikasi apa pun yang didownload.
  • Setiap pemicu mendatang yang terjadi dalam periode atribusi pascapenginstalan akan diatribusikan ke sumber atribusi yang sama seperti penginstalan yang divalidasi, asalkan sumber atribusi tersebut memenuhi syarat.

Di masa mendatang, kami mungkin akan memperluas desain untuk mendukung model atribusi yang lebih canggih.

Tabel berikut menunjukkan contoh cara teknologi iklan dapat menggunakan atribusi pascapenginstalan. Asumsikan semua sumber dan pemicu atribusi didaftarkan oleh jaringan teknologi iklan yang sama, dan semua prioritasnya sama.

Peristiwa Hari saat peristiwa terjadi Catatan
Klik 1 1 install_attribution_window disetel ke 172800 (2 hari), dan post_install_exclusivity_window disetel ke 864000 (10 hari)
Penginstalan terverifikasi 2 API secara internal mengatribusikan penginstalan terverifikasi, tetapi penginstalan tersebut tidak dianggap sebagai pemicu. Oleh karena itu, tidak ada laporan yang dikirim pada tahap ini.
Pemicu 1 (Pertama Dibuka) 2 Pemicu pertama yang didaftarkan oleh teknologi iklan. Dalam contoh ini, pemicu mewakili first open (dibuka pertama), tetapi dapat berupa jenis pemicu apa pun.
Diatribusikan untuk mengklik 1 (cocok dengan atribusi penginstalan terverifikasi).
Klik 2 4 Menggunakan nilai yang sama untuk install_attribution_window dan post_install_exclusivity_window seperti Klik 1
Pemicu 2 (Setelah Penginstalan) 5 Pemicu kedua yang didaftarkan oleh teknologi iklan. Dalam contoh ini, ini mewakili konversi pasca-penginstalan seperti pembelian.
Diatribusikan untuk mengklik 1 (cocok dengan atribusi penginstalan terverifikasi).
Klik 2 dihapus dan tidak memenuhi syarat untuk atribusi di masa mendatang.

Daftar berikut memberikan beberapa catatan tambahan terkait atribusi pasca-penginstalan:

  • Jika penginstalan terverifikasi tidak terjadi dalam jumlah hari yang ditentukan oleh install_attribution_window, atribusi pascapenginstalan tidak akan diterapkan.
  • Penginstalan terverifikasi tidak didaftarkan oleh teknologi iklan dan tidak dikirim dalam laporan. Penginstalan tersebut tidak diperhitungkan terhadap batas kapasitas teknologi iklan. Penginstalan terverifikasi hanya digunakan untuk mengidentifikasi sumber atribusi yang dikreditkan dengan penginstalan.
  • Pada contoh dari tabel sebelumnya, pemicu 1 dan pemicu 2 berturut-turut mewakili first open (dibuka pertama) dan konversi pascapenginstalan. Namun, platform teknologi iklan dapat mendaftarkan jenis pemicu apa pun. Dengan kata lain, pemicu pertama tidak harus menjadi pemicu terbuka pertama.
  • Jika lebih banyak pemicu yang didaftarkan setelah masa berlaku post_install_exclusivity_window berakhir, klik 1 masih memenuhi syarat untuk atribusi, dengan asumsi bahwa masa berlaku pemicu belum berakhir dan belum mencapai batas kapasitas.
    • Klik 1 mungkin masih hilang, atau dibuang, jika sumber atribusi dengan prioritas lebih tinggi didaftarkan.
  • Jika aplikasi pengiklan di-uninstal dan diinstal ulang, instal ulang akan dihitung sebagai penginstalan terverifikasi baru.
  • Jika klik 1 adalah peristiwa tampilan, pemicu "pertama dibuka" dan pasca-penginstalan masih diatribusikan ke peristiwa tersebut. API membatasi atribusi untuk satu pemicu per penayangan, kecuali pada kasus atribusi pascapenginstalan yang mengizinkan hingga dua pemicu per penayangan. Dalam kasus atribusi pascapenginstalan, teknologi iklan dapat menerima 2 periode pelaporan yang berbeda (pada 2 hari atau masa berlaku sumber).

Semua kombinasi jalur pemicu berbasis aplikasi dan web didukung

Attribution Reporting API memungkinkan atribusi jalur pemicu berikut di satu perangkat Android:

  • Aplikasi ke aplikasi: Pengguna melihat iklan di aplikasi, lalu melakukan konversi dalam aplikasi tersebut atau aplikasi lain yang diinstal.
  • Aplikasi ke web: Pengguna melihat iklan di aplikasi, lalu melakukan konversi di browser seluler atau aplikasi.
  • Web ke aplikasi: Pengguna melihat iklan di browser aplikasi atau seluler, lalu melakukan konversi dalam aplikasi.
  • Web ke web: Pengguna melihat iklan di browser seluler atau aplikasi, lalu melakukan konversi di browser yang sama atau browser lain di perangkat yang sama.

Kami mengizinkan browser web mendukung fungsi baru yang terekspos web, seperti fungsi yang mirip dengan Privacy Sandbox untuk Attribution Reporting API Web, yang dapat memanggil API Android untuk mengaktifkan atribusi di seluruh aplikasi dan web.

Pelajari perubahan yang perlu dilakukan teknologi iklan dan aplikasi untuk mendukung jalur pemicu pengukuran lintas aplikasi dan web.

Memprioritaskan beberapa pemicu untuk satu sumber atribusi

Sumber atribusi tunggal dapat menyebabkan beberapa pemicu. Misalnya, alur pembelian dapat melibatkan pemicu "penginstalan aplikasi", satu atau beberapa pemicu "tambahkan ke keranjang", dan pemicu "pembelian". Setiap pemicu diatribusikan ke satu atau beberapa sumber atribusi sesuai dengan algoritme atribusi prioritas sumber, yang akan dijelaskan kemudian dalam halaman ini.

Ada batasan jumlah pemicu yang dapat diatribusikan ke satu sumber atribusi; untuk mengetahui detail selengkapnya, baca bagian melihat data pengukuran dalam laporan atribusi di halaman ini nanti. Jika ada beberapa pemicu di luar batasan ini, sebaiknya Anda memperkenalkan logika prioritas untuk mendapatkan kembali pemicu yang paling berharga. Misalnya, developer teknologi iklan mungkin ingin memprioritaskan untuk mendapatkan pemicu "pembelian" daripada pemicu "tambahkan ke keranjang".

Untuk mendukung logika ini, kolom prioritas terpisah dapat ditetapkan pada pemicu, dan pemicu prioritas tertinggi diambil sebelum batasan diterapkan, dalam periode pelaporan tertentu.

Mengizinkan beberapa teknologi iklan mendaftarkan sumber atribusi atau pemicu

Biasanya lebih dari satu teknologi iklan menerima laporan atribusi, umumnya untuk melakukan penghapusan duplikat lintas jaringan. Oleh karena itu, API memungkinkan beberapa teknologi iklan untuk mendaftarkan sumber atribusi atau pemicu yang sama. Teknologi iklan harus mendaftarkan sumber atribusi dan pemicu untuk menerima postback dari API, dan atribusi dilakukan di antara sumber atribusi dan pemicu yang telah didaftarkan dengan API ini oleh teknologi iklan.

Pengiklan yang ingin menggunakan pihak ketiga untuk melakukan penghapusan duplikat lintas-jaringan dapat terus melakukannya, menggunakan teknik yang mirip dengan berikut ini:

  • Menyiapkan server internal untuk mendaftarkan dan menerima laporan dari API.
  • Terus menggunakan partner pengukuran seluler yang ada.

Sumber atribusi

Pengalihan sumber atribusi didukung dalam metode registerSource():

  1. Teknologi iklan yang memanggil metode registerSource() dapat memberikan kolom Attribution-Reporting-Redirect tambahan dalam responsnya, yang mewakili kumpulan URL alihan teknologi iklan partner.
  2. API kemudian memanggil URL alihan sehingga sumber atribusi dapat didaftarkan oleh teknologi iklan partner.

Beberapa URL teknologi iklan partner dapat dicantumkan di kolom Attribution-Reporting-Redirect, dan teknologi iklan partner tidak dapat menentukan kolom Attribution-Reporting-Redirect-nya sendiri.

API juga memungkinkan teknologi iklan yang berbeda untuk setiap panggilan registerSource().

Pemicu

Untuk pendaftaran pemicu, pihak ketiga didukung dengan cara yang sama: teknologi iklan dapat menggunakan kolom Attribution-Reporting-Redirect tambahan, atau masing-masing dapat memanggil metode registerTrigger().

Jika pengiklan menggunakan beberapa teknologi iklan untuk mendaftarkan peristiwa pemicu yang sama, kunci penghapusan duplikat harus digunakan. Kunci penghapusan duplikat berfungsi untuk membedakan laporan berulang dari peristiwa yang sama yang didaftarkan oleh platform teknologi iklan yang sama. Misalnya, teknologi iklan dapat meminta SDK mereka memanggil API secara langsung untuk mendaftarkan pemicu dan menempatkan URL-nya di kolom pengalihan dari panggilan teknologi iklan lain. Jika kunci penghapusan duplikat tidak diberikan, pemicu duplikat dapat dilaporkan kembali ke setiap teknologi iklan sebagai satu-satunya.

Menangani pemicu duplikat

Teknologi iklan dapat mendaftarkan pemicu yang sama beberapa kali dengan API. Skenario mencakup hal berikut:

  • Pengguna melakukan tindakan yang sama (pemicu) beberapa kali. Misalnya, pengguna menjelajahi produk yang sama beberapa kali dalam periode pelaporan yang sama.
  • Aplikasi pengiklan menggunakan beberapa SDK untuk pengukuran konversi, dan semuanya dialihkan ke teknologi iklan yang sama. Misalnya, aplikasi pengiklan menggunakan dua partner pengukuran, MMP #1 dan MMP #2. Kedua MMP dialihkan ke teknologi iklan #3. Saat pemicu terjadi, kedua MMP mendaftarkan pemicu tersebut dengan Attribution Reporting API. Teknologi iklan #3 kemudian menerima dua pengalihan terpisah—satu dari MMP #1 dan satu dari MMP #2—untuk pemicu yang sama.

Dalam kasus ini, ada beberapa cara untuk menyembunyikan laporan tingkat peristiwa pada pemicu duplikat, untuk mengurangi kemungkinan melebihi batas kapasitas yang diterapkan pada laporan tingkat peristiwa. Cara yang direkomendasikan adalah menggunakan kunci penghapusan duplikat.

Metode yang direkomendasikan: kunci penghapusan duplikat

Metode yang direkomendasikan adalah agar aplikasi pengiklan meneruskan kunci penghapusan duplikat yang unik ke teknologi iklan atau SDK apa pun yang digunakan untuk pengukuran konversi. Saat konversi terjadi, aplikasi akan meneruskan kunci penghapusan duplikat ke teknologi iklan atau SDK. Teknologi iklan atau SDK tersebut kemudian terus meneruskan kunci penghapusan duplikat untuk mengalihkan menggunakan parameter dalam URL yang ditentukan di Attribution-Reporting-Redirect.

Teknologi iklan dapat memilih untuk mendaftarkan pemicu pertama saja dengan kunci penghapusan duplikat tertentu, atau dapat memilih untuk mendaftarkan beberapa pemicu atau semua pemicu. Teknologi iklan dapat menentukan deduplication_key saat mendaftarkan pemicu duplikat.

Jika teknologi iklan mendaftarkan beberapa pemicu dengan kunci penghapusan duplikat dan sumber atribusi yang sama, hanya pemicu terdaftar pertama yang akan dikirim dalam laporan tingkat peristiwa. Pemicu duplikat tetap dikirim dalam laporan agregat yang dienkripsi.

Metode alternatif: teknologi iklan menyetujui jenis pemicu per pengiklan

Jika ada teknologi iklan yang tidak ingin menggunakan kunci penghapusan duplikat, atau jika aplikasi pengiklan tidak dapat meneruskan kunci penghapusan duplikat, ada opsi alternatif. Semua teknologi iklan yang mengukur konversi untuk pengiklan tertentu harus bekerja sama untuk menentukan jenis pemicu yang berbeda bagi setiap pengiklan.

Teknologi iklan yang memulai panggilan pendaftaran pemicu—misalnya, SDK—menyertakan parameter dalam URL yang ditentukan dalam Attribution-Reporting-Redirect, seperti duplicate_trigger_id. Parameter duplicate_trigger_id tersebut dapat mencakup informasi seperti nama SDK dan jenis pemicu untuk pengiklan tersebut. Kemudian, teknologi iklan dapat mengirimkan subkumpulan pemicu duplikat ini ke laporan tingkat peristiwa. Teknologi iklan juga dapat menyertakan duplicate_trigger_id ini dalam kunci agregasinya.

Contoh atribusi lintas-jaringan

Pada contoh yang dijelaskan di bagian ini, pengiklan menggunakan dua platform teknologi iklan penayangan (Teknologi iklan A dan Teknologi iklan B) dan satu partner pengukuran (MMP).

Untuk memulai, Teknologi iklan A, Teknologi iklan B, dan MMP harus menyelesaikan pendaftaran untuk menggunakan Attribution Reporting API. Lihat Mendaftar ke akun Privacy Sandbox untuk mengetahui informasi selengkapnya.

Daftar berikut memberikan beberapa hipotesis terkait tindakan pengguna yang terjadi setiap hari, dan cara Attribution Reporting API menangani tindakan tersebut sehubungan dengan Teknologi iklan A, Teknologi iklan B, dan MMP:

Hari ke-1: Pengguna mengklik iklan yang ditayangkan oleh Teknologi iklan A

Teknologi Iklan memanggil registerSource() dengan URI-nya. API membuat permintaan ke URI, dan klik didaftarkan dengan metadata dari respons server Teknologi iklan A.

Teknologi iklan A juga menyertakan URI MMP di header Attribution-Reporting-Redirect. API membuat permintaan ke URI MMP, dan klik didaftarkan dengan metadata dari respons server MMP.

Hari ke-2: Pengguna mengklik iklan yang ditayangkan oleh Teknologi iklan B

Teknologi iklan memanggil registerSource() dengan URI-nya. API membuat permintaan ke URI, dan klik didaftarkan dengan metadata dari respons server Teknologi iklan B.

Seperti halnya Teknologi iklan A, Teknologi iklan B juga telah menyertakan URI MMP di header Attribution-Reporting-Redirect. API membuat permintaan ke URI MMP, dan klik didaftarkan dengan metadata dari respons server MMP.

Hari ke-3: Pengguna melihat iklan yang ditayangkan oleh Teknologi iklan A

API merespons dengan cara yang sama seperti pada Hari ke-1, kecuali bahwa penayangan didaftarkan untuk Teknologi iklan A dan MMP.

Hari ke-4: Pengguna menginstal aplikasi, yang menggunakan MMP untuk pengukuran konversi

MMP memanggil registerTrigger() dengan URI-nya. API membuat permintaan ke URL, dan konversi didaftarkan dengan metadata dari respons server MMP.

MMP juga menyertakan URI untuk Teknologi iklan A dan Teknologi iklan B di header Attribution-Reporting-Redirect. API membuat permintaan ke server Teknologi iklan A dan Teknologi iklan B, dan konversi tersebut terdaftar sesuai dengan metadata dari respons server.

Diagram berikut menggambarkan proses yang dijelaskan dalam daftar sebelumnya:

Contoh cara Attribution Reporting API merespons serangkaian tindakan pengguna.

Cara kerja Atribusi adalah sebagai berikut:

  • Teknologi iklan A menetapkan prioritas klik yang lebih tinggi daripada penayangan sehingga penginstalan akan diatribusikan ke klik pada Hari ke-1.
  • Teknologi iklan B mendapatkan penginstalan yang diatribusikan pada Hari ke-2.
  • MMP menetapkan prioritas klik lebih tinggi daripada penayangan, dan membuat penginstalan diatribusikan ke klik pada Hari ke-2. Klik hari ke-2 adalah prioritas tertinggi, peristiwa iklan terbaru.

Atribusi lintas-jaringan tanpa pengalihan

Meskipun kami merekomendasikan penggunaan pengalihan untuk memungkinkan beberapa teknologi iklan mendaftarkan sumber dan pemicu atribusi, kami menyadari bahwa mungkin ada beberapa skenario ketika penggunaan pengalihan tidak memungkinkan. Bagian ini akan menjelaskan cara mendukung atribusi lintas jaringan tanpa pengalihan.

Alur tingkat tinggi

  1. Saat pendaftaran sumber, jaringan teknologi iklan penayangan membagikan kunci agregasi sumbernya.
  2. Saat pendaftaran pemicu, pengiklan atau partner pengukuran akan memilih bagian kunci sisi sumber yang akan digunakan, lalu menentukan konfigurasi atribusinya.
  3. Atribusi didasarkan pada konfigurasi atribusi, kunci bersama, dan sumber apa pun yang didaftarkan oleh pengiklan atau partner pengukuran tersebut (mis. dari jaringan teknologi iklan penayangan lain yang telah mengaktifkan pengalihan).
  4. Jika pemicu diatribusikan ke sumber yang berasal dari teknologi iklan penayangan yang tidak mengalihkan, pengiklan atau partner pengukuran dapat menerima laporan agregat yang menggabungkan bagian kunci sumber dan pemicu yang ditentukan pada langkah #2.

Pendaftaran sumber

Saat pendaftaran sumber, jaringan teknologi iklan penayangan dapat memilih antara membagikan kunci agregasi sumbernya atau subset kunci agregasi sumbernya, bukan pengalihannya. Teknologi iklan penayangan tidak diwajibkan untuk benar-benar menggunakan kunci sumber ini dalam laporan agregatnya sendiri dan dapat mendeklarasikannya hanya atas nama pengiklan atau partner pengukuran jika diperlukan.

Kunci agregasi bersama tersedia untuk semua teknologi iklan yang mendaftarkan pemicu untuk pengiklan yang sama. Namun, kolaborasi pada jenis kunci agregasi yang diperlukan, namanya, dan cara mendekode kunci ke dimensi yang dapat dibaca akan ditentukan oleh teknologi iklan penayangan dan teknologi iklan pengukuran pemicu.

Pendaftaran pemicu

Saat pendaftaran pemicu, teknologi iklan pengukuran akan memilih bagian kunci sisi sumber yang akan diterapkan ke setiap bagian kunci pemicu, termasuk bagian kunci yang dibagikan oleh teknologi iklan penayangan.

Selain itu, teknologi iklan pengukuran juga harus menentukan logika atribusi waterfall mereka menggunakan panggilan API konfigurasi atribusi yang baru. Dalam konfigurasi ini, teknologi iklan dapat menentukan prioritas sumber, masa habis berlaku, dan filter untuk sumber yang tidak memiliki visibilitas (misalnya, sumber yang tidak menggunakan pengalihan).

Atribusi

Attribution Reporting API melakukan atribusi sentuh terakhir yang diprioritaskan oleh sumber untuk teknologi iklan pengukuran berdasarkan konfigurasi atribusi, kunci bersama, dan sumber apa pun yang didaftarkan. Contoh:

  • Pengguna mengklik iklan yang ditayangkan oleh teknologi iklan A, B, C, dan D. Pengguna lalu menginstal aplikasi pengiklan yang menggunakan partner teknologi iklan pengukuran (MMP).
  • Teknologi iklan A mengalihkan sumbernya ke MMP.
  • Teknologi iklan B dan C tidak mengalihkan, tetapi membagikan kunci agregasinya.
  • Teknologi iklan D tidak mengalihkan atau membagikan kunci agregasi.

MMP mendaftarkan sumber dari Teknologi iklan A, dan menentukan konfigurasi atribusi yang menyertakan Teknologi iklan B dan Teknologi iklan D.

Atribusi untuk MMP kini mencakup:

  • Teknologi iklan A, karena MMP mendaftarkan sumber dari pengalihan teknologi iklan tersebut.
  • Teknologi iklan B, karena kunci bersama Teknologi iklan B dan MMP menyertakannya dalam konfigurasi atribusinya.

Atribusi untuk MMP tidak mencakup:

  • Teknologi iklan C, karena MMP tidak menyertakannya dalam konfigurasi atribusi.
  • Teknologi iklan D, karena MMP tidak mengalihkan atau berbagi kunci agregasi.

Proses Debug

Guna mendukung proses debug untuk atribusi lintas jaringan tanpa pengalihan, kolom tambahan shared_debug_key tersedia untuk teknologi iklan agar ditetapkan setelah pendaftaran sumber. Jika ditetapkan pada pendaftaran sumber asli, ID tersebut juga akan ditetapkan pada sumber turunan yang sesuai sebagai debug_key selama pendaftaran pemicu untuk atribusi lintas jaringan tanpa pengalihan. Kunci debug ini dilampirkan sebagai source_debug_key dalam laporan peristiwa dan agregasi.

Fitur debug ini hanya akan didukung untuk atribusi lintas jaringan tanpa pengalihan dalam skenario berikut:

  • Pengukuran aplikasi ke aplikasi yang mengizinkan ID iklan
  • Pengukuran aplikasi ke web yang mengizinkan ID iklan dan cocok di sumber aplikasi dan pemicu web
  • Pengukuran web ke web (di aplikasi browser yang sama) saat ar_debug` ada di sumber dan pemicu

Penemuan kunci untuk atribusi lintas jaringan tanpa pengalihan

Penemuan kunci dimaksudkan untuk menyederhanakan cara teknologi iklan (biasanya MMP) menerapkan konfigurasi atribusinya untuk tujuan atribusi lintas jaringan saat satu atau beberapa teknologi iklan penayangan menggunakan kunci agregasi bersama (seperti yang dijelaskan dalam Atribusi lintas jaringan tanpa pengalihan di atas).

Saat MMP mengkueri Layanan Agregasi untuk membuat laporan ringkasan untuk kampanye yang menyertakan sumber turunan, Layanan Agregasi mengharuskan MMP untuk menentukan daftar kemungkinan kunci sebagai input untuk tugas agregasi. Dalam beberapa kasus, daftar kunci agregasi sumber potensial mungkin sangat besar, atau tidak diketahui. Daftar kunci yang mungkin yang besar sulit untuk dilacak, dan kemungkinan juga cukup kompleks dan mahal untuk diproses. Perhatikan contoh berikut:

  • Daftar semua kunci yang mungkin berukuran besar:
    • Jaringan iklan yang melakukan penayangan menjalankan inisiatif akuisisi pengguna yang kompleks yang mencakup 20 kampanye, masing-masing dengan 10 grup iklan, dan setiap grup iklan dengan 5 materi iklan yang diperbarui setiap minggu berdasarkan performa.
  • Daftar semua kunci yang mungkin tidak diketahui:
    • Jaringan iklan yang melakukan penayangan menayangkan iklan di banyak aplikasi seluler tempat daftar lengkap ID aplikasi penayang tidak diketahui saat peluncuran kampanye.
    • Seorang pengiklan bekerja di beberapa jaringan iklan yang melakukan penayangan yang tidak mengalihkan ke MMP saat pendaftaran sumber; setiap jaringan iklan yang melakukan penayangan memiliki struktur dan nilai kunci yang berbeda, yang mungkin tidak dibagikan sebelumnya dengan MMP.

Dengan pengenalan penemuan kunci:

  • Layanan Agregasi tidak lagi memerlukan enumerasi penuh kunci agregasi yang mungkin.
  • Alih-alih menentukan daftar lengkap kunci yang mungkin, MMP dapat membuat kumpulan kunci yang kosong (atau sebagian kosong) dan menetapkan nilai minimum, sehingga hanya kunci (yang tidak dideklarasikan sebelumnya) dengan nilai yang melebihi nilai minimum tersebut yang disertakan dalam output.
  • MMP menerima laporan ringkasan yang menyertakan nilai derau untuk kunci yang memiliki nilai kontribusi di atas nilai minimum yang ditetapkan. Laporan ini juga dapat menyertakan kunci yang tidak memiliki kontribusi pengguna nyata terkait dan sepenuhnya merupakan nilai derau.
  • MMP menggunakan kolom x_network_bit_mapping dalam pendaftaran pemicu untuk menentukan teknologi iklan yang sesuai dengan kunci.
  • MMP kemudian dapat menghubungi teknologi iklan yang melakukan penayangan yang sesuai untuk memahami nilai dalam kunci sumber.

Singkatnya, penemuan kunci memungkinkan MMP memperoleh kunci agregasi tanpa mengetahuinya terlebih dahulu, dan menghindari pemrosesan kunci sumber dalam jumlah besar dengan mengorbankan derau tambahan.

Pengalihan daisy chain

Dengan menyediakan beberapa header Attribution-Reporting-Redirect dalam respons server HTTPS pendaftaran sumber atau pemicu, teknologi iklan dapat menggunakan Attribution Reporting API untuk melakukan beberapa pendaftaran sumber dan pemicu dengan satu panggilan API pendaftaran.

Dalam respons server, teknologi iklan juga dapat menyertakan satu Location (pengalihan 302) dengan URL, yang kemudian mengarah ke pendaftaran domain, hingga batas yang ditentukan.

Kedua jenis header bersifat opsional dan tidak ada yang dapat diberikan jika pengalihan tidak diperlukan. Salah satu atau kedua jenis header dapat diberikan. Permintaan pendaftaran sumber dan pemicu (termasuk pengalihan) dicoba lagi dalam terjadi kegagalan jaringan. Jumlah percobaan ulang per permintaan dibatasi hingga nomor tetap untuk menghindari dampak yang signifikan pada perangkat.

Pengalihan tidak diterima untuk registerWebSource dan registerWebTrigger yang digunakan oleh browser. Detail selengkapnya dapat ditemukan di halaman Lintas Web dan Aplikasi Panduan Penerapan.

Melihat data pengukuran dalam laporan atribusi

Attribution Reporting API memungkinkan jenis laporan berikut, yang dijelaskan secara lebih mendetail nanti di halaman ini:

  • Laporan tingkat peristiwa mengaitkan sumber atribusi tertentu (klik atau penayangan) dengan bit data pemicu fidelitas tinggi yang terbatas.
  • Laporan agregat tidak harus terikat dengan sumber atribusi tertentu. Laporan ini memberikan data pemicu yang lebih lengkap dengan fidelitas lebih tinggi dibandingkan laporan tingkat peristiwa, tetapi data ini hanya tersedia dalam bentuk agregat.

Kedua jenis laporan ini saling melengkapi dan dapat digunakan secara bersamaan.

Laporan tingkat peristiwa

Setelah pemicu diatribusikan ke sumber atribusi, laporan tingkat peristiwa akan dibuat dan disimpan di perangkat hingga dapat dikirimkan kembali ke setiap URL postback teknologi iklan selama salah satu dari jangka waktu untuk mengirim laporan, yang akan dijelaskan secara lebih mendetail nanti dalam halaman ini.

Laporan tingkat peristiwa berguna jika sangat sedikit informasi yang diperlukan tentang pemicu. Data pemicu tingkat peristiwa dibatasi hingga 3 bit data pemicu untuk klik. Artinya, pemicu dapat diberi salah satu dari delapan kategori, dan 1 bit untuk penayangan. Selain itu, laporan tingkat peristiwa tidak mendukung encoding data sisi pemicu dengan fidelitas tinggi, seperti waktu pemicu atau harga tertentu. Karena atribusi terjadi di perangkat, tidak ada dukungan untuk analisis lintas perangkat dalam laporan tingkat peristiwa.

Laporan tingkat peristiwa berisi data seperti berikut:

  • Tujuan: Nama paket aplikasi pengiklan atau eTLD+1 tempat pemicunya terjadi
  • ID Sumber Atribusi: ID sumber atribusi yang sama dengan yang digunakan untuk mendaftarkan sumber atribusi
  • Jenis pemicu: 1 atau 3 bit data pemicu dengan fidelitas rendah, bergantung pada jenis sumber atribusi

Mekanisme yang menjaga privasi diterapkan ke semua laporan

Batasan berikut diterapkan setelah prioritas terkait sumber atribusi dan pemicu akan dipertimbangkan.

Batasan jumlah teknologi iklan

Ada batasan jumlah teknologi iklan yang dapat mendaftarkan atau menerima laporan dari API, dengan proposal saat ini sebagai berikut:

  • 100 teknologi iklan dengan sumber atribusi per {aplikasi sumber, aplikasi tujuan, 30 hari, perangkat}.
  • 10 teknologi iklan dengan pemicu atribusi per {aplikasi sumber, aplikasi tujuan, 30 hari, perangkat}.
  • 20 teknologi iklan dapat mendaftarkan satu pemicu atau sumber atribusi (melalui Attribution-Reporting-Redirect)

Batasan jumlah tujuan unik

Batasan ini mempersulit kumpulan teknologi iklan untuk berkomunikasi dengan membuat kueri sejumlah besar aplikasi guna memahami perilaku penggunaan aplikasi pengguna tertentu.

  • Di semua sumber terdaftar dan teknologi iklan, API mendukung tidak lebih dari 200 tujuan unik, per aplikasi sumber, per menit.
  • Di semua sumber terdaftar, untuk satu teknologi iklan, API mendukung tidak lebih dari 50 tujuan unik, per aplikasi sumber, per menit. Batasan ini mencegah satu teknologi iklan menggunakan seluruh anggaran dari batas kapasitas yang disebutkan sebelumnya.

Sumber yang habis masa berlakunya tidak diperhitungkan untuk batas kapasitas.

Satu asal pelaporan per aplikasi sumber per hari

Platform teknologi iklan tertentu mungkin hanya menggunakan satu asal pelaporan untuk mendaftarkan sumber di aplikasi penayang, untuk perangkat tertentu, pada hari yang sama. Batas kapasitas ini mencegah teknologi iklan menggunakan beberapa asal pelaporan untuk mengakses anggaran privasi tambahan.

Pertimbangkan skenario berikut, ketika satu teknologi iklan ingin menggunakan beberapa asal pelaporan untuk mendaftarkan sumber di aplikasi penayang, untuk satu perangkat.

  1. Asal pelaporan 1 teknologi iklan A mendaftarkan sumber di Aplikasi B
  2. Dua belas jam kemudian, asal pelaporan teknologi iklan A 2 mencoba untuk mendaftarkan sumber di Aplikasi B

Sumber kedua, untuk asal pelaporan 2 teknologi iklan A, akan ditolak oleh API. Asal pelaporan 2 teknologi iklan A tidak akan berhasil mendaftarkan sumber di perangkat yang sama di Aplikasi B hingga hari berikutnya.

Batas kapasitas dan periode tunggu

Untuk membatasi jumlah kebocoran identitas pengguna di antara pasangan {sumber, tujuan}, API akan men-throttle jumlah total informasi yang dikirim dalam jangka waktu tertentu untuk pengguna.

Proposal saat ini adalah membatasi setiap teknologi iklan hingga 100 pemicu atribusi per {aplikasi sumber, aplikasi tujuan, 30 hari, perangkat}.

Jumlah tujuan unik

API membatasi jumlah tujuan yang dapat diukur oleh teknologi iklan. Semakin rendah batasnya, semakin sulit bagi teknologi iklan untuk menggunakan API dalam upaya mengukur aktivitas penjelajahan pengguna yang tidak terkait dengan iklan yang ditampilkan.

Proposal saat ini adalah membatasi setiap teknologi iklan hingga 100 tujuan yang berbeda dengan sumber yang masih berlaku per aplikasi sumber.

Mekanisme perlindungan privasi yang diterapkan ke laporan tingkat peristiwa

Fidelitas data pemicu terbatas

API menyediakan 1 bit untuk pemicu tonton-habis dan 3 bit untuk pemicu klik-tayang. Sumber atribusi terus mendukung metadata 64 bit lengkap.

Anda harus mengevaluasi apakah dan bagaimana mengurangi informasi yang dinyatakan dalam pemicu sehingga berfungsi dengan jumlah bit yang terbatas dalam laporan tingkat peristiwa.

Framework untuk derau privasi diferensial

Tujuan API ini adalah untuk memungkinkan pengukuran tingkat peristiwa untuk memenuhi persyaratan privasi diferensial lokal dengan menggunakan respons acak k untuk menghasilkan output yang memiliki banyak derau untuk setiap peristiwa sumber.

Derau diterapkan untuk melihat apakah peristiwa sumber atribusi dilaporkan secara jujur. Sumber atribusi terdaftar pada perangkat dengan probabilitas $ 1-p $ yang berarti sumber atribusi tersebut terdaftar seperti biasa, dan dengan probabilitas $ p $ bahwa perangkat secara acak memilih di antara semua kemungkinan status output dari API (termasuk tidak melaporkan apa pun atau melaporkan beberapa laporan palsu).

Respons acak k adalah algoritma yang bersifat epsilon diferensial pribadi jika persamaan berikut terpenuhi:

\[ p = \frac{k}{k + e^ε - 1} \]

Untuk nilai ε yang rendah, output sebenarnya dilindungi oleh mekanisme respons acak k. Parameter derau yang tepat sedang dalam proses dan dapat berubah berdasarkan masukan, dengan proposal saat ini sebagai berikut:

  • p=0,24% untuk sumber navigasi
  • p=0,00025% untuk sumber peristiwa

Batasan pada pemicu yang tersedia (konversi)

Terdapat batasan jumlah pemicu per sumber atribusi, dengan proposal saat ini sebagai berikut:

  • 1-2 pemicu untuk sumber atribusi tampilan iklan (2 pemicu hanya tersedia untuk atribusi pascapenginstalan)
  • 3 pemicu untuk sumber atribusi iklan klik

Periode waktu tertentu untuk mengirim laporan (perilaku default)

Laporan tingkat peristiwa untuk sumber atribusi tampilan iklan dikirim 1 jam setelah sumber berakhir masa berlakunya. Tanggal masa berakhir ini dapat dikonfigurasi, tetapi tidak boleh kurang dari 1 hari atau lebih dari 30 hari. Jika dua pemicu diatribusikan ke sumber atribusi tampilan iklan (melalui atribusi pasca-penginstalan), laporan tingkat peristiwa dapat dikirim pada interval periode pelaporan yang ditentukan sebagai berikut.

Laporan tingkat peristiwa untuk sumber atribusi klik iklan tidak dapat dikonfigurasi dan dikirim sebelum atau ketika sumber berakhir masa berlakunya, pada waktu tertentu yang ditentukan saat sumber didaftarkan. Waktu antara sumber atribusi dan masa berakhir dibagi menjadi beberapa periode pelaporan. Setiap periode pelaporan memiliki batas waktu (dari waktu sumber atribusi). Di akhir setiap periode pelaporan, perangkat akan mengumpulkan semua pemicu yang terjadi sejak periode pelaporan sebelumnya dan mengirim laporan terjadwal. API ini mendukung periode pelaporan berikut:

  • 2 hari: Perangkat mengumpulkan semua pemicu yang terjadi maksimal 2 hari setelah sumber atribusi didaftarkan. Laporan ini dikirim 2 hari dan 1 jam setelah sumber atribusi didaftarkan.
  • 7 hari: Perangkat mengumpulkan semua pemicu yang terjadi lebih dari 2 hari, tetapi tidak lebih dari 7 hari setelah sumber atribusi didaftarkan. Laporan ini dikirim 7 hari dan 1 jam setelah sumber atribusi didaftarkan.
  • Durasi kustom, ditentukan oleh atribut "masa berakhir" pada sumber atribusi. Laporan dikirim 1 jam setelah waktu masa berakhir yang ditentukan. Nilai ini tidak boleh kurang dari 1 hari atau lebih dari 30 hari.

Konfigurasi tingkat peristiwa fleksibel

Konfigurasi default untuk pelaporan tingkat peristiwa adalah saran teknologi iklan yang mulai digunakan saat memulai pengujian utilitas, tetapi mungkin tidak ideal untuk semua kasus penggunaan. Attribution Reporting API akan mendukung konfigurasi opsional yang lebih fleksibel sehingga teknologi iklan meningkatkan kontrol terhadap struktur laporan tingkat peristiwa dan dapat memaksimalkan utilitas data.

Fleksibilitas tambahan ini akan diperkenalkan ke dalam Attribution Reporting API dalam dua fase:

  • Fase 1: Konfigurasi tingkat peristiwa fleksibel Lite
    • Versi ini menyediakan subset dari fitur lengkap, dan dapat digunakan secara terpisah dari Fase 2.
  • Fase 2: Versi penuh konfigurasi tingkat peristiwa fleksibel

Fase 1 (Tingkat peristiwa fleksibel Lite) dapat digunakan untuk:

  • Memvariasikan frekuensi laporan dengan menentukan jumlah periode pelaporan
  • Memvariasikan jumlah atribusi per pendaftaran sumber
  • Mengurangi jumlah total derau dengan mengurangi parameter di atas
  • Mengonfigurasi periode pelaporan, bukan menggunakan periode default

Fase 2 (Tingkat peristiwa fleksibel penuh) dapat digunakan untuk melakukan semua kemampuan dalam Fase 1 dan:

  • Memvariasikan kardinalitas data pemicu dalam laporan
  • Mengurangi jumlah total derau dengan mengurangi kardinalitas data pemicu

Mengurangi satu dimensi konfigurasi default memungkinkan teknologi iklan untuk meningkatkan dimensi lain. Atau, jumlah total derau dalam laporan tingkat peristiwa dapat dikurangi dengan mengurangi parameter bersih yang disebutkan di atas.

Selain menetapkan level derau secara dinamis berdasarkan konfigurasi teknologi iklan yang dipilih, kami akan menetapkan beberapa batas parameter untuk menghindari biaya komputasi dan konfigurasi yang besar dengan terlalu banyak status output (di mana derau akan meningkat secara signifikan). Berikut adalah contoh kumpulan pembatasan. Kami mengharapkan masukan pada [proposal desain][50]:

  • Total maksimum 20 laporan, secara global dan per trigger_data
  • Maksimum 5 kemungkinan periode pelaporan per trigger_data
  • Maksimum 32 kardinalitas data pemicu (tidak berlaku untuk Fase 1: Tingkat Peristiwa Fleksibel Lite)

Saat teknologi iklan mulai menggunakan fitur ini, harap diingat bahwa penggunaan nilai ekstrem dapat menghasilkan derau dalam jumlah besar, atau kegagalan dalam mendaftar jika tingkat privasi tidak terpenuhi.

Laporan agregat

Sebelum menggunakan laporan agregat, Anda harus menyiapkan akun cloud Anda dan mulai menerima laporan agregat.

Laporan agregat memberikan data pemicu dengan fidelitas lebih tinggi dari perangkat, lebih cepat, di luar yang ditawarkan untuk laporan tingkat peristiwa. Data dengan fidelitas lebih tinggi ini hanya dapat dipelajari secara agregat, dan tidak terkait dengan pemicu atau pengguna tertentu. Kunci agregasi hingga 128 bit, dan ini memungkinkan laporan gabungan mendukung pelaporan kasus penggunaan seperti berikut:

  • Laporan untuk nilai pemicu, seperti pendapatan
  • Menangani jenis pemicu lainnya

Selain itu, laporan agregat menggunakan logika atribusi yang diprioritaskan dengan sumber yang sama seperti laporan tingkat peristiwa, tetapi mendukung lebih banyak konversi yang diatribusikan ke klik atau tampilan.

Keseluruhan desain cara Attribution Reporting API mempersiapkan dan mengirim laporan agregat, yang ditampilkan dalam diagram, adalah sebagai berikut:

  1. Perangkat mengirim laporan agregat yang dienkripsi ke teknologi iklan. Dalam lingkungan produksi, teknologi iklan tidak dapat menggunakan laporan ini secara langsung.
  2. Teknologi iklan mengirimkan sekumpulan laporan agregat ke layanan agregasi untuk digabungkan.
  3. Layanan agregasi membaca sekumpulan laporan agregat, mendekripsi, dan mengagregasinya.
  4. Agregat akhir dikirim kembali ke teknologi iklan dalam laporan ringkasan.
Proses yang digunakan Attribution Reporting API untuk menyiapkan dan mengirim laporan agregat.

Laporan agregat berisi data berikut yang terkait dengan sumber atribusi:

  • Tujuan: Nama paket aplikasi atau URL web eTLD+1 tempat pemicu terjadi.
  • Tanggal: Tanggal saat peristiwa yang diwakili oleh sumber atribusi terjadi.
  • Payload: Nilai pemicu, dikumpulkan sebagai key-value pair terenkripsi yang digunakan di layanan agregasi tepercaya untuk menghitung agregasi.

Layanan agregasi

Layanan berikut memberikan fungsi agregasi dan membantu melindungi dari akses data agregasi yang tidak pantas.

Layanan ini dikelola oleh berbagai pihak, yang nanti akan dijelaskan lebih mendetail di halaman ini:

  • Layanan agregasi adalah satu-satunya yang diharapkan oleh teknologi iklan untuk di-deploy.
  • Layanan pengelolaan kunci dan akuntabilitas laporan agregat dijalankan oleh pihak tepercaya yang disebut koordinator. Koordinator ini membuktikan bahwa kode yang menjalankan layanan agregasi adalah kode yang tersedia secara publik dan disediakan oleh Google, dan bahwa semua pengguna layanan agregasi memiliki kunci yang sama dan menggunakan layanan akuntansi laporan agregat.
Layanan agregasi

Platform teknologi iklan harus terlebih dahulu men-deploy layanan agregasi yang berdasarkan biner dan disediakan oleh Google.

Layanan agregasi ini beroperasi di Trusted Execution Environment (TEE) yang dihosting di cloud. TEE menawarkan manfaat keamanan berikut:

  • Ini memastikan bahwa kode yang beroperasi di TEE adalah biner khusus yang ditawarkan oleh Google. Kecuali jika kondisi ini terpenuhi, layanan agregasi tidak dapat mengakses kunci dekripsi yang diperlukan untuk beroperasi.
  • Layanan ini menawarkan keamanan seputar proses yang berjalan, mengisolasinya dari pemantauan atau gangguan eksternal.

Manfaat keamanan ini memberikan keamanan lebih bagi layanan agregasi untuk menjalankan operasi yang sensitif, seperti mengakses data terenkripsi.

Untuk mengetahui informasi selengkapnya tentang pertimbangan desain, alur kerja, dan keamanan layanan agregasi, lihat dokumen layanan agregasi di GitHub.

Key management service

Layanan ini memverifikasi bahwa layanan agregasi menjalankan versi biner yang disetujui, lalu menyediakan layanan agregasi di teknologi iklan dengan kunci dekripsi yang benar untuk data pemicunya.

Akuntansi laporan agregat

Layanan ini melacak seberapa sering layanan agregasi teknologi iklan mengakses pemicu tertentu—yang dapat berisi beberapa kunci agregasi—dan membatasi akses ke jumlah dekripsi yang sesuai. Lihat proposal desain Layanan Agregasi untuk Attribution Reporting API untuk mengetahui detailnya.

Aggregatable Reports API

API untuk membuat kontribusi ke laporan agregat menggunakan API dasar yang sama seperti saat mendaftarkan sumber atribusi untuk laporan tingkat peristiwa. Bagian berikut ini menjelaskan ekstensi API tersebut.

Mendaftarkan data sumber agregat

Saat API membuat permintaan ke URI Sumber Atribusi, teknologi iklan dapat mendaftarkan daftar kunci agregasi bernama histogram_contributions, dengan merespons menggunakan kolom baru bernama aggregation_keys di header HTTP Attribution-Reporting-Register-Source, dengan kunci sebagai key_name dan nilai sebagai key_piece:

  • (Kunci) Nama kunci: String untuk nama kunci. Digunakan sebagai kunci penghubung untuk digabungkan dengan kunci sisi pemicu untuk membuat kunci akhir.
  • (Nilai) Bagian kunci: Nilai bitstring untuk kunci.

Kunci bucket histogram akhir sepenuhnya ditentukan pada waktu pemicu dengan melakukan biner ATAU operasi pada bagian-bagian tersebut dan bagian sisi pemicu.

Kunci akhir dibatasi maksimum 128 bit; kunci yang lebih panjang dari ini akan terpotong. Artinya, string hex dalam JSON harus dibatasi maksimal 32 digit.

Pelajari lebih lanjut cara menyusun dan mengonfigurasi kunci agregasi.

Pada contoh berikut, teknologi iklan menggunakan API untuk mengumpulkan hal berikut:

  • Jumlah konversi agregat di tingkat kampanye
  • Nilai pembelian agregat pada tingkat geografis
// This is where the Attribution-Reporting-Register-Source object appears when
// an ad tech registers an attribution source.

// Attribution source metadata specifying histogram contributions in aggregate report.
Attribution-Reporting-Register-Source:
…
aggregation_keys: {
  // Generates a "0x159" key piece named (low order bits of the key) for the key
  // named "campaignCounts".
  // User saw an ad from campaign 345 (out of 511).

  "campaignCounts": "0x159",
  // Generates a "0x5" key piece (low order bits of the key) for the key name "geoValue"
  // Source-side geo region = 5 (US), out of a possible ~100 regions.
  "geoValue": "0x5"
}

Mendaftarkan pemicu agregat

Pendaftaran pemicu mencakup dua kolom tambahan.

Kolom pertama digunakan untuk mendaftarkan daftar kunci agregat pada sisi pemicu. Teknologi iklan harus merespons kembali dengan kolom aggregatable_trigger_data di header HTTP Attribution-Reporting-Register-Trigger, dengan kolom berikut untuk setiap kunci agregat dalam daftar:

  • Bagian kunci: Nilai bitstring untuk kunci.
  • Kunci sumber: Daftar string dengan nama kunci sisi sumber atribusi yang harus digabungkan dengan kunci pemicu untuk membentuk kunci akhir.

Kolom kedua digunakan untuk mendaftarkan daftar nilai yang akan berkontribusi pada setiap kunci. Teknologi iklan harus merespons kembali dengan kolom aggregatable_values di header HTTP Attribution-Reporting-Register-Trigger. Kolom kedua digunakan untuk mendaftarkan daftar nilai yang harus berkontribusi pada setiap kunci, yang dapat berupa bilangan bulat dalam rentang $ [1, 2^{16}] $.

Setiap pemicu dapat memberikan beberapa kontribusi pada laporan agregat. Jumlah total kontribusi ke setiap sumber peristiwa tertentu terikat oleh parameter $ L1 $, yang merupakan jumlah maksimum kontribusi (nilai) di seluruh kunci agregat untuk sumber tertentu. $ L1 $ mengacu pada sensitivitas atau norma L1 dari kontribusi histogram per peristiwa sumber. Jika batas ini terlampaui, kontribusi di masa mendatang akan berkurang secara perlahan. Proposal awal adalah untuk menetapkan $ L1 $ ke $ 2^{16} $ (65536).

Derau di layanan agregasi diskalakan dengan proporsi pada parameter ini. Oleh karena itu, sebaiknya skalakan nilai yang dilaporkan untuk kunci agregat tertentu sesuai dengan porsi anggaran $ L1 $ yang dialokasikan untuk kunci tersebut. Pendekatan ini membantu memastikan bahwa laporan agregat mempertahankan fidelitas setinggi mungkin ketika derau diterapkan. Mekanisme ini sangat fleksibel dan dapat mendukung banyak strategi agregasi.

Pada contoh berikut, anggaran privasi dibagi secara merata antara campaignCounts dan geoValue dengan membagi kontribusi $ L1 $ ke masing-masing:

// This is where the Attribution-Reporting-Register-Trigger object appears
// when an ad tech registers a conversion trigger.

// Specify a list of dictionaries that generates aggregation keys.
Attribution-Reporting-Register-Trigger:{
    …
    "aggregatable_trigger_data":

    [
    // Each dictionary independently adds pieces to multiple source keys.
    {
    // Conversion type purchase = 2 at a 9-bit offset, i.e. 2 << 9.
    // A 9-bit offset is needed because there are 511 possible campaigns, which
    // will take up 9 bits in the resulting key.
        "key_piece": "0x400",// Conversion type purchase = 2
        // Apply this key piece to:
        "source_keys": ["campaignCounts"]
    },
    {
    // Purchase category shirts = 21 at a 7-bit offset, i.e. 21 << 7.
    // A 7-bit offset is needed because there are ~100 regions for the geo key,
    // which will take up 7 bits of space in the resulting key.
        "key_piece": "0xA80",
        // Apply this key piece to:
        "source_keys": ["geoValue", "nonMatchingIdsListedHereAreIgnored"]
    }
    ]

    // Specify an amount of an abstract value which can be integers in [1, 2^16] to
    // contribute to each key that is attached to aggregation keys in the order that
    // they're generated.
    aggregatable_values:
    {
    // Privacy budget for each key is L1 / 2 = 2^15 (32768).
    // Conversion count was 1.
    // Scale the count to use the full budget allocated: 1 * 32768 = 32768.
        "campaignCounts": 32768,

    // Purchase price was $52.
    // Purchase values for the app range from $1 to $1,024 (integers only).
    // Scaling factor applied is 32768 / 1024 = 32.
    // For $52 purchase, scale the value by 32 ($52 * 32 = $1,664).
        "geoValue": 1664
    }
}

Contoh sebelumnya menghasilkan kontribusi histogram berikut:

[
  // campaignCounts:
  {
    "key": "0x559", // = 0x159 | 0x400
    "value": 32768
  },
  // geoValue:
  {
    "key": "0xA85",  // = 0x5 | 0xA80
    "value": 1664
  }
]

Faktor penskalaan dapat dibalik untuk mendapatkan nilai yang benar, derau modular yang diterapkan:

L1 = 65536
trueCampaignCounts = campaignCounts / (L1 / 2)
trueGeoValue = geoValue / (L1 / 2) * 1024

Privasi diferensial

Tujuan API ini adalah memiliki framework yang dapat mendukung pengukuran agregat pribadi secara diferensial. Hal ini dapat dicapai dengan menambahkan derau yang proporsional dengan anggaran $ L1 $, seperti memilih derau dengan distribusi berikut:

\[ Laplace(\frac{L1}{ε}) \]

Integrasi Protected Audience API dan Attribution Reporting API

Integrasi lintas API di seluruh Protected Audience dan Attribution Reporting API memungkinkan teknologi iklan mengevaluasi performa atribusi di berbagai taktik pemasaran ulang untuk memahami jenis audiens mana yang menghasilkan ROI tertinggi.

Melalui integrasi lintas-API ini, teknologi iklan dapat:

  • Membuat peta nilai kunci URI yang akan digunakan untuk 1) pelaporan interaksi dan 2) pendaftaran sumber.
  • Menyertakan CustomAudience dalam konfigurasi tombol sisi sumber untuk pelaporan ringkasan gabungan (menggunakan Attribution Reporting API).

Saat pengguna melihat atau mengklik iklan:

  • URL yang digunakan untuk melaporkan interaksi tersebut yang menggunakan Protected Audience juga akan digunakan untuk mendaftarkan penayangan atau klik sebagai sumber yang memenuhi syarat dengan Attribution Reporting API.
  • Teknologi iklan dapat memilih untuk meneruskan CustomAudience (atau informasi kontekstual relevan lainnya tentang iklan seperti penempatan iklan atau durasi tonton) menggunakan URL tersebut sehingga metadata ini dapat diterapkan ke laporan ringkasan saat teknologi iklan meninjau performa kampanye gabungan.

Untuk informasi selengkapnya tentang cara mengaktifkannya dalam Protected Audience, lihat bagian yang relevan dalam penjelasan Protected Audience API.

Contoh pelaporan, atribusi, dan prioritas pendaftaran

Contoh ini menunjukkan sekumpulan interaksi pengguna dan pengaruh teknologi atribusi serta sumber pemicu yang ditentukan teknologi iklan terhadap laporan yang diatribusikan. Dalam contoh ini, kami asumsikan beberapa hal berikut:

  • Semua sumber atribusi dan pemicu didaftarkan oleh teknologi iklan yang sama, untuk pengiklan yang sama.
  • Semua sumber dan pemicu atribusi terjadi selama periode pelaporan peristiwa pertama (dalam 2 hari sejak awal menampilkan iklan di aplikasi penayang).

Pertimbangkan kasus saat pengguna melakukan hal berikut:

  1. Pengguna melihat iklan. Teknologi iklan mendaftarkan sumber atribusi dengan API, dengan prioritas 0 (tampilan #1).
  2. Pengguna melihat iklan yang terdaftar dengan prioritas 0 (tampilan #2).
  3. Pengguna mengklik iklan yang terdaftar dengan prioritas 1 (klik #1).
  4. Pengguna melakukan konversi (mencapai halaman landing) di aplikasi pengiklan. Teknologi iklan mendaftarkan pemicu menggunakan API, dengan prioritas 0 (konversi #1).
    • Saat pemicu didaftarkan, API akan melakukan atribusi terlebih dahulu sebelum membuat laporan.
    • Ada 3 sumber atribusi yang tersedia: penayangan #1, penayangan #2, dan klik #1. API mengatribusikan pemicu ini ke klik #1 karena merupakan prioritas tertinggi dan terbaru.
    • Tampilan #1 dan tampilan #2 dibuang dan tidak lagi memenuhi syarat untuk atribusi mendatang.
  5. Pengguna menambahkan item ke keranjang di aplikasi pengiklan, yang terdaftar dengan prioritas 1 (konversi #2).
    • Klik #1 adalah satu-satunya sumber atribusi yang memenuhi syarat. API mengatribusikan pemicu ini ke klik #1.
  6. Pengguna menambahkan item ke keranjang di aplikasi pengiklan, yang terdaftar dengan prioritas 1 (konversi #3).
    • Klik #1 adalah satu-satunya sumber atribusi yang memenuhi syarat. API mengatribusikan pemicu ini ke klik #1.
  7. Pengguna menambahkan item ke keranjang di aplikasi pengiklan, yang terdaftar dengan prioritas 1 (konversi #4).
    • Klik #1 adalah satu-satunya sumber atribusi yang memenuhi syarat. API mengatribusikan pemicu ini ke klik #1.
  8. Pengguna melakukan pembelian di aplikasi pengiklan, yang didaftarkan dengan prioritas 2 (konversi #5).
    • Klik #1 adalah satu-satunya sumber atribusi yang memenuhi syarat. API mengatribusikan pemicu ini ke klik #1.

Laporan tingkat peristiwa memiliki karakteristik berikut:

  • Secara default, 3 pemicu pertama yang diatribusikan ke sebuah klik dan pemicu pertama yang diatribusikan ke tampilan dikirim setelah periode pelaporan yang berlaku.
  • Dalam periode pelaporan, jika ada pemicu yang terdaftar dengan prioritas lebih tinggi, pemicu tersebut akan lebih diutamakan dan menggantikan pemicu terbaru.
  • Dalam contoh sebelumnya, teknologi iklan menerima 3 laporan peristiwa setelah periode pelaporan 2 hari, untuk konversi #2, konversi #3, dan konversi #5.
    • Kelima pemicu diatribusikan ke klik #1. Secara default, API akan mengirimkan laporan untuk 3 pemicu pertama: konversi #1, konversi #2, dan konversi #3.
    • Namun, prioritas konversi #4 (1) lebih tinggi daripada prioritas konversi #1 (0). Laporan peristiwa konversi #4 menggantikan laporan peristiwa konversi #1 yang akan dikirim.
    • Selain itu, prioritas konversi #5 (2) lebih tinggi daripada pemicu lainnya. Laporan peristiwa konversi #5 menggantikan laporan konversi #4 yang akan dikirim.

Laporan agregat memiliki karakteristik berikut:

  • Laporan gabungan yang dienkripsi dikirim ke teknologi iklan segera setelah diproses, beberapa jam setelah pemicu didaftarkan.

    Sebagai teknologi iklan, Anda membuat batch berdasarkan informasi yang tidak dienkripsi dalam laporan agregat. Informasi ini dimuat dalam kolom shared_info dalam laporan agregat Anda, dan menyertakan stempel waktu dan asal pelaporan. Anda tidak dapat melakukan batch berdasarkan informasi terenkripsi dalam key-value pair agregasi Anda. Beberapa strategi sederhana yang dapat Anda ikuti adalah mengelompokkan laporan setiap hari atau setiap minggu. Idealnya, batch harus berisi minimal 100 laporan.

  • Teknologi iklan bergantung pada waktu dan cara mengelompokkan laporan gabungan dan mengirimkannya ke layanan agregasi.

  • Dibandingkan dengan laporan tingkat peristiwa, laporan agregat yang dienkripsi dapat mengatribusikan lebih banyak pemicu ke sumber.

  • Dalam contoh sebelumnya, 5 laporan agregat dikirimkan, satu laporan untuk setiap pemicu yang terdaftar.

Laporan proses debug transisi

Attribution Reporting API merupakan cara baru untuk melakukan pengukuran atribusi tanpa ID lintas aplikasi, dan cara ini cukup rumit. Oleh karena itu, kami mendukung mekanisme transisi untuk mempelajari informasi laporan atribusi lebih lanjut saat ID iklan tersedia (pengguna belum memilih untuk menonaktifkan personalisasi menggunakan ID iklan dan aplikasi penayang atau pengiklan telah mendeklarasikan izin ID iklan). Hal ini memastikan API dapat dipahami sepenuhnya selama peluncuran, membantu menghilangkan bug, dan lebih mudah membandingkan performa dengan alternatif berbasis ID iklan. Ada dua jenis laporan proses debug: laporan atribusi-sukses dan laporan panjang.

Baca panduan tentang laporan proses debug transisi untuk mengetahui detail tentang laporan proses debug dengan pengukuran aplikasi ke web dan web ke aplikasi.

Laporan proses debug atribusi-sukses

Pendaftaran sumber dan pemicu menerima kolom debug_key 64-bit baru (yang diformat sebagai String), yang diisi oleh teknologi iklan. source_debug_key dan trigger_debug_key diteruskan tanpa diubah dalam laporan tingkat peristiwa dan agregat.

Jika laporan dibuat dengan kunci debug sumber dan pemicu, laporan debug duplikat akan dikirim ke endpoint .well-known/attribution-reporting/debug/report-event-attribution dengan penundaan terbatas. Laporan debug identik dengan laporan normal, termasuk kedua kolom kunci debug. Dengan menyertakan kunci-kunci ini ke dalam kedua laporan tersebut, laporan normal akan dapat diikat ke aliran laporan debug yang terpisah.

  • Untuk laporan tingkat peristiwa:
    • Laporan debug duplikat dikirim dengan penundaan terbatas sehingga tidak disembunyikan oleh batas pada pemicu yang tersedia, yang memungkinkan teknologi iklan memahami dampak dari batas tersebut untuk laporan tingkat peristiwa.
    • Laporan tingkat peristiwa yang terkait dengan peristiwa pemicu palsu tidak akan memiliki trigger_debug_key. Hal ini memungkinkan teknologi iklan memahami lebih lanjut cara derau diterapkan di API.
  • Untuk laporan gabungan:
    • Kami akan mendukung kolom debug_cleartext_payload baru yang berisi payload yang didekripsi, hanya jika source_debug_key dan trigger_debug_key ditetapkan.

Laporan proses debug panjang

Laporan proses debug panjang memungkinkan developer memantau kegagalan tertentu di sumber atribusi atau pendaftaran pemicu. Laporan proses debug ini dikirim dengan penundaan terbatas setelah sumber atribusi atau pendaftaran pemicu ke Endpoint well-known/attribution-reporting/debug/verbose.

Setiap laporan panjang berisi kolom-kolom berikut:

  • Jenis: penyebab laporan dibuat. Lihat daftar lengkap jenis laporan panjang.
    • Secara umum, ada laporan panjang sumber dan laporan panjang pemicu.
    • Laporan panjang sumber memerlukan ID iklan agar tersedia untuk aplikasi penayang, dan laporan panjang pemicu memerlukan ID iklan agar tersedia untuk aplikasi pengiklan.
    • Laporan panjang pemicu (kecuali trigger-no-matching-source) dapat menyertakan source_debug_key secara opsional. Kunci ini hanya dapat disertakan jika ID iklan juga tersedia untuk aplikasi penayang.
  • Isi: Isi laporan, yang bergantung pada jenisnya.

Teknologi iklan harus memilih untuk menerima laporan proses debug panjang melalui kolom kamus debug_reporting yang baru di header Attribution-Reporting-Register_Source dan Attribution-Reporting-Register-Trigger.

  • Laporan panjang sumber hanya memerlukan keikutsertaan pada header pendaftaran sumber.
  • Laporan debug pemicu hanya memerlukan keikutsertaan pada header pendaftaran pemicu.

Cara menggunakan laporan debug

Jika konversi terjadi (sesuai dengan sistem pengukuran yang ada) dan laporan debug diterima untuk konversi tersebut, ini berarti pemicu berhasil didaftarkan.

Untuk setiap laporan atribusi debug, pastikan Anda menerima laporan atribusi reguler yang cocok dengan kedua kunci debug.

Jika tidak ada kecocokan, penyebabnya bisa beberapa hal.

Berfungsi sebagaimana mestinya:

  • Perilaku API yang menjaga privasi:
    • Pengguna mencapai batas kapasitas laporan sehingga menyebabkan semua laporan berikutnya tidak dikirim dalam jangka waktu tertentu; atau sumber dihapus karena adanya penundaan batas tujuan.
    • Untuk laporan tingkat peristiwa: laporan tunduk pada respons acak (derau) dan disembunyikan, atau Anda mungkin menerima laporan acak.
    • Untuk laporan tingkat peristiwa: batas tiga laporan (untuk klik) atau satu laporan (untuk tampilan) telah tercapai, dan prioritas eksplisit laporan berikutnya belum ditetapkan atau prioritasnya lebih rendah dari laporan yang ada.
    • Batas kontribusi untuk laporan agregat telah terlampaui.
  • Logika bisnis yang ditentukan oleh teknologi iklan:
    • Pemicu difilter melalui filter atau aturan prioritas.
  • Jeda waktu atau interaksi dengan ketersediaan jaringan (misalnya, pengguna mematikan perangkat untuk jangka waktu yang lama).

Penyebab yang tidak diinginkan:

  • Masalah penerapan:
    • Header sumber tidak dikonfigurasi dengan benar.
    • Header pemicu tidak dikonfigurasi dengan benar.
    • Masalah konfigurasi lainnya.
  • Masalah perangkat atau jaringan:
    • Kegagalan akibat kondisi jaringan.
    • Respons pendaftaran sumber atau pemicu tidak menjangkau klien.
    • Bug API.

Pertimbangan pada masa mendatang & pertanyaan terbuka

Attribution Reporting API sedang dalam proses. Kami juga mengeksplorasi potensi fitur di masa mendatang, seperti model atribusi non-klik terakhir dan kasus penggunaan pengukuran lintas-perangkat.

Selain itu, kami ingin meminta masukan dari komunitas terkait beberapa masalah:

  1. Apakah ada laporan kasus penggunaan untuk penginstal terverifikasi yang ingin Anda kirimkan melalui API? Laporan ini akan dihitung berdasarkan batas kapasitas setiap platform teknologi iklan.
  2. Apakah Anda mengalami kesulitan dalam meneruskan InputEvent dari aplikasi ke teknologi iklan untuk pendaftaran sumber?
  3. Apakah Anda memiliki kasus penggunaan atribusi khusus untuk aplikasi bawaan atau aplikasi yang diinstal ulang?