Attribution Reporting API memungkinkan atribusi lintas aplikasi dan web untuk sumber dan pemicu yang terjadi di perangkat yang sama. Browser, seperti Chrome, dapat mendelegasikan pendaftaran sumber dan pemicu ke Attribution Reporting API untuk Android, bukan menangani pendaftaran tersebut di browser. Hal ini memungkinkan Android mencocokkan sumber dan pemicu di seluruh situs dan aplikasi.
Panduan ini akan mengajarkan cara menyiapkan atribusi lintas aplikasi dan web.
Saat menyiapkan atribusi lintas aplikasi dan web, sebaiknya Anda juga memahami solusi proses debug yang tersedia untuk memastikan penyiapan Anda berfungsi sebagaimana mestinya.
Mendaftarkan sumber dan pemicu dengan Android OS
Atribusi lintas aplikasi dan web hanya akan tersedia jika Attribution Reporting API diaktifkan di browser dan Android OS di perangkat yang sama. Ketersediaan Attribution Reporting API Android dikirim melalui header Attribution-Reporting-Support. Header ini akan menampilkan OS, web, atau keduanya, bergantung pada apa yang tersedia di perangkat tersebut. Jika keduanya tersedia, teknologi iklan akan memiliki pilihan untuk mendaftarkan sumber web dan pemicu web dengan browser atau OS.
Teknologi iklan perlu memutuskan apakah akan mendaftarkan sumber web atau pemicu web dengan browser atau OS.
- Untuk kampanye khusus web, teknologi iklan masih dapat mendaftarkan sumber dan pemicu dengan Attribution Reporting API Chrome atau memilih untuk mendelegasikan keduanya ke OS. Untuk kampanye khusus web dengan sumber atau pemicu yang mungkin terjadi di WebView, teknologi iklan harus mendelegasikan pendaftaran sumber dan pemicu ke OS. Lihat bagian tentang WebView untuk mengetahui informasi selengkapnya.
Teknologi iklan harus menghindari pendaftaran sumber dan pemicu dengan Chrome dan Android API secara bersamaan untuk menghindari pembuatan laporan atribusi duplikasi.
Atribusi terjadi secara terpisah untuk browser dan OS. Jika sumber didaftarkan dengan browser, tetapi pemicu didaftarkan dengan OS, keduanya tidak dapat dicocokkan dan sebaliknya.
Untuk sumber yang dapat menghasilkan pemicu aplikasi atau web, sangat direkomendasikan bagi teknologi iklan untuk mendelegasikan pendaftaran sumber web dan pemicu ke Android Attribution Reporting API.
Untuk pemicu yang mungkin didorong oleh sumber berbasis aplikasi, teknologi iklan dapat memilih untuk mendelegasikan pendaftaran pemicu web ke Android Attribution Reporting API.
Untuk kampanye yang sumber dan pemicunya terjadi di aplikasi, keduanya harus didaftarkan dengan OS Attribution Reporting API.
Mendaftarkan sumber aplikasi dan pemicu web
Untuk beberapa kampanye, sumber dapat terjadi di aplikasi, sedangkan pemicu akan terjadi di situs di browser seluler pada perangkat yang sama.
Contoh
Seorang pengguna sedang membaca artikel di aplikasi berita favoritnya. Ia melihat iklan penerbangan murah ke Paris dan dengan antusias mengklik untuk memesan. Teknologi iklan yang menayangkan iklan di aplikasi berita mendaftarkan sumber klik dengan Android Attribution Reporting API. Pengguna akan diarahkan ke halaman web pengiklan di Chrome tempat mereka dapat melakukan konversi. Teknologi iklan di situs pengiklan akan memeriksa apakah API tingkat OS tersedia, dan memang tersedia. Teknologi iklan mendaftarkan pemicu konversi dengan memberi tahu Chrome untuk mendelegasikan pendaftaran ke OS, bukan mendaftarkannya secara langsung dengan Attribution Reporting API Chrome. Attribution Reporting API level OS kemudian dapat mencocokkan sumber aplikasi dan pemicu web serta mengirim laporan yang relevan.
Pendaftaran sumber aplikasi:
SDK teknologi iklan di Aplikasi Android Daily News mendaftarkan klik menggunakan
registerSource()
Attribution Reporting API di Android mengirimkan permintaan ke URL server teknologi iklan yang diberikan ke
registerSource()
Server teknologi iklan merespons dengan header Attribution-Reporting-Register-Source untuk menyelesaikan pendaftaran sumber
Pendaftaran pemicu web:
Teknologi iklan mendaftarkan pemicu dan memeriksa ketersediaan OS di Attribution Reporting API
ARA web menampilkan informasi tentang platform yang didukung
Header
OS-Trigger
memberi tahu ARA API web untuk memanggil fungsiregisterWebTrigger()
ARA API OSPanggilan ke
registerWebTrigger()
terjadi di balik layar dan developer tidak perlu memanggilregisterWebTrigger()
dengan OS secara langsungARA OS mengambil alih dan mengirim permintaan ke URL server teknologi iklan yang disediakan oleh header
Attribution-Reporting-Register-OS-Trigger
Teknologi iklan akan menyelesaikan pendaftaran pemicu dengan OS API
ARA OS akan melakukan atribusi sesuai dengan logika yang sama yang diterapkan pada atribusi aplikasi<>aplikasi dan mengirimkan laporan yang sama
Alur kerja
Langkah-langkah berikut mencakup detail lebih lanjut tentang cara menyelesaikan tugas:
Teknologi iklan dari aplikasi mendaftarkan sumber dengan Attribution Reporting API Android dengan penyesuaian berikut:
- Untuk mendaftarkan sumber aplikasi yang diharapkan akan berkonversi di situs, header respons
Attribution-Reporting-Register-Source
harus menyertakan tujuan web (eTLD+1), bukan tujuan aplikasi.
Attribution-Reporting-Register-Source: { "web_destination": "https://advertiser.example", ... }
- Beberapa pengiklan mungkin menggunakan beberapa penyedia pengukuran (misalnya, alat pengukuran pihak ketiga atau alat analisis) menggunakan rantai pengalihan 302. Dalam beberapa kasus, Attribution Reporting API akan mengikuti jalur pengalihan yang ditentukan dalam header Attribution-Reporting-Redirect di latar belakang dan secara bersamaan jalur pengalihan 302 akan dijalankan di latar depan untuk permintaan navigasi yang ada. Permintaan ini akan diarahkan ke URL yang sama dan dapat menyebabkan pendaftaran penghitungan ganda oleh penyedia pengukuran pihak ketiga. Untuk mencegah pendaftaran ganda, teknologi iklan dapat mengubah perilaku pengalihan untuk mengirim pendaftaran Attribution Reporting API ke URL alternatif yang bersifat deterministik.
Untuk mengaktifkan perilaku ini, teknologi iklan harus menyertakan header HTTP baru saat merespons permintaan pendaftaran:
- Headernya adalah
Attribution-Reporting-Redirect-Config
- Nilai header harus redirect-302-to-well-known
Attribution-Reporting-Redirect-Config: redirect-302-to-well-known
- Headernya adalah
Proses pendaftaran sumber lainnya sama dengan pendaftaran sumber aplikasi ke aplikasi standar.
- Untuk mendaftarkan sumber aplikasi yang diharapkan akan berkonversi di situs, header respons
Teknologi iklan di situs pengiklan mendaftarkan pemicu dengan meminta Chrome untuk mendelegasikan pendaftaran ke Attribution Reporting API Android:
Setelah pengguna menyelesaikan konversi di situs, teknologi iklan akan membuat permintaan untuk mendaftarkan pemicu dengan Chrome
Permintaan pixel atau
fetch()
dapat digunakan untuk membuat permintaan guna mendaftarkan pemicuHeader permintaan
Attribution-Reporting-Support
ditampilkan oleh Chrome ke teknologi iklan. Jika API diaktifkan di browser Chrome dan perangkat Android, header akan menampilkanos, web
Attribution-Reporting-Support: os, web
Teknologi iklan kemudian harus memberi tahu Chrome untuk mendelegasikan ke OS menggunakan header
Attribution-Reporting-Register-OS-Trigger
yang:Memberi tahu Chrome untuk mendelegasikan pendaftaran ke OS
Chrome mendelegasikan pendaftaran ke OS dengan memanggil fungsi OS API
registerWebTrigger()
- Panggilan ke
registerWebTrigger()
terjadi di balik layar, teknologi iklan tidak perlu memanggilregisterWebTrigger()
secara langsung
- Panggilan ke
OS API memulai panggilan API sekunder ke URI teknologi iklan yang diteruskan dari browser
Attribution-Reporting-Register-OS-Trigger: "https://adtech.example/register-trigger", "https://other-adtech.example/register-trigger"
Dalam beberapa kasus, header
Attribution-Reporting-Support
tidak tersedia dan tidak dapat dikirim. Jika hal ini terjadi, teknologi iklan masih dapat menetapkan platform pilihan untuk menangani pendaftaran pemicu dengan menyertakan headerAttribution-Reporting-Info
. Kuncinya adalah platform-pilihan dan nilai yang diizinkan adalahos
danweb
. Browser akan menggunakan platform pilihan jika tersedia dan akan kembali ke platform web saat OS tidak tersedia.
Attribution-Reporting-Info: preferred-platform=os
- Untuk menyelesaikan pendaftaran pemicu, endpoint teknologi iklan harus merespons permintaan Android Attribution Reporting API menggunakan header respons.
Attribution-Reporting-Register-Trigger: { "event_trigger_data": [{"trigger_data":"1"}], "aggregatable_trigger_data": [ {"key_piece":"0x400","source_keys":["campaignCounts"]}, {"key_piece":"0xA80","source_keys":["geoValue"]} ], ... }
- Bagian lain dari pendaftaran pemicu tetap sama.
Mendaftarkan sumber web dan pemicu aplikasi
Untuk beberapa kampanye, sumber dapat terjadi di situs di browser seluler, sedangkan pemicu terjadi di aplikasi di perangkat yang sama.
Contoh
Pengguna sedang menjelajahi situs di browser Chrome di ponsel Android. Ia melihat iklan sweter dari salah satu toko favoritnya. Mereka mengklik iklan dan diarahkan ke aplikasi yang telah mereka download. Teknologi iklan di situs tempat iklan ditayangkan mendaftarkan sumber klik dengan menginstruksikan Chrome untuk mendelegasikan pendaftaran ke Android Attribution Reporting API, bukan menggunakan Attribution Reporting API di Chrome. Pengguna membeli sweter di aplikasi belanja. Teknologi iklan di aplikasi pengiklan kemudian mendaftarkan pemicu konversi dengan Android Attribution Reporting API. Attribution Reporting API level OS dapat mencocokkan sumber web dan pemicu aplikasi serta mengirim laporan yang relevan.
Pendaftaran sumber web:
Teknologi iklan mendaftarkan sumber dan memeriksa ketersediaan OS di Attribution Reporting API
ARA web menampilkan informasi tentang platform yang didukung
Header
OS-Source
memberi tahu ARA API web untuk memanggil fungsiregisterWebSource()
ARA API OSPanggilan ke
registerWebSource()
terjadi di balik layar dan developer tidak perlu memanggilregisterWebSource()
dengan OS secara langsungARA OS mengambil alih dan mengirim permintaan ke URL server teknologi iklan yang disediakan oleh header
Attribution-Reporting-Register-OS-Source
Teknologi iklan akan menyelesaikan pendaftaran sumber dengan OS API
Pendaftaran pemicu aplikasi:
SDK teknologi iklan di aplikasi Android toko Pakaian mendaftarkan pemicu dengan ARA OS
Attribution Reporting API di Android mengirimkan permintaan ke URL server teknologi iklan yang diberikan ke
registerTrigger()
Server teknologi iklan merespons dengan header
Attribution-Reporting-Register-Trigger
untuk menyelesaikan pendaftaran pemicuARA OS akan melakukan atribusi sesuai dengan logika yang sama yang diterapkan pada atribusi aplikasi<>aplikasi dan mengirimkan laporan yang sama
Alur kerja
Langkah-langkah berikut mencakup detail lebih lanjut tentang cara menyelesaikan tugas:
Teknologi iklan di situs penayang mendaftarkan sumber dengan menginstruksikan Chrome untuk mendelegasikan pendaftaran ke Android Attribution Reporting API:
- Untuk kasus penggunaan web ke aplikasi, saat mendaftarkan sumber, parameter sumber atribusi harus ditentukan secara langsung, baik dengan menggunakan tag
attributionsrc
atau dengan menggunakan pendaftaran JavaScript - Contoh berikut menggunakan tag
attributionsrc
untuk menentukan parameter sumber:
<img src="https://adtech.example/conversionpixel" attributionsrc="https://adtech.example/register-source?purchase=12">
- Untuk kasus penggunaan web ke aplikasi, saat mendaftarkan sumber, parameter sumber atribusi harus ditentukan secara langsung, baik dengan menggunakan tag
Header permintaan
Attribution-Reporting-Support
ditampilkan oleh Chrome ke teknologi iklan. Jika API diaktifkan di browser Chrome dan perangkat Android, header akan menampilkanos, web
.Attribution-Reporting-Support: os, web
Teknologi iklan harus memberi tahu Chrome untuk mendelegasikan ke API tingkat OS menggunakan header
Attribution-Reporting-Register-OS-Source
yang:- Memberi tahu Chrome untuk mendelegasikan pendaftaran ke OS
- Chrome mendelegasikan pendaftaran ke OS dengan memanggil fungsi OS API
registerWebSource()
- Panggilan ke
registerWebSource()
terjadi di balik layar, teknologi iklan tidak perlu memanggilregisterWebSource()
secara langsung - OS API memulai panggilan API sekunder ke URI teknologi iklan yang diteruskan dari browser
Attribution-Reporting-Register-OS-Source: "https://adtech.example/register-source"
- Dalam beberapa kasus, header
Attribution-Reporting-Support
tidak tersedia. Jika hal ini terjadi, teknologi iklan masih dapat menetapkan platform pilihan untuk menangani pendaftaran sumber dengan menyertakan headerAttribution-Reporting-Info
. Kuncinya adalah platform-pilihan dan nilai yang diizinkan adalahos
danweb
. Browser akan menggunakan platform pilihan jika tersedia dan akan kembali ke platform web jika OS tidak tersedia.
Attribution-Reporting-Info: preferred-platform=os
- Untuk menyelesaikan pendaftaran sumber, endpoint teknologi iklan harus merespons
permintaan Android Attribution Reporting API dengan header respons
Attribution-Reporting-Register-Source
. Respons juga harus menentukan tujuan aplikasi di kolom tujuan.
Attribution-Reporting-Register-Source: { "source_event_id":"123001", "destination":"android-app://com.example.advertiser", ... }
- Untuk mendukung pengalihan bagi pendaftaran sumber, Chrome akan mengikuti pengalihan dan memanggil API konteks web untuk setiap lompatan pengalihan.
- Bagian lain dari pendaftaran sumber tetap sama.
Teknologi iklan di aplikasi pengiklan mendaftarkan pemicu dengan Attribution Reporting API Android:
- Untuk pemicu yang terjadi di aplikasi, aplikasi mendaftarkan pemicu dengan Android Attribution Reporting API seperti biasa.
Kampanye yang memiliki tujuan iklan potensial aplikasi dan web
Menyiapkan tujuan ganda
- Beberapa kampanye dapat disiapkan untuk melakukan konversi di aplikasi pengiklan atau di halaman web pengiklan, bergantung pada berbagai faktor seperti apakah pengguna telah menginstal aplikasi.
- Dalam kasus ini, sebaiknya delegasikan pendaftaran sumber ke OS jika tersedia sehingga sumber dapat diatribusikan dengan benar, terlepas dari tempat pemicu terjadi. Saat mendaftarkan sumber ke OS, tujuan aplikasi dan web dapat ditentukan dalam parameter masing-masing.
- Tujuan aplikasi harus berada di kolom
destination
- Tujuan web harus berada di kolom
web_destination
- Developer Chrome harus memperhatikan bahwa kolom
destination
untuk OS Attribution Reporting API harus berupa paket aplikasi, bukan URL.
Attribution-Reporting-Register-Source: { "source_event_id":"123001", "destination":"android-app://com.example.advertiser", "web_destination": "https://example.advertiser" ... }
- Bagian berikutnya tentang pelaporan kasar akan menjelaskan bagaimana penggunaan tujuan ganda dapat memengaruhi derau dalam laporan Anda.
Gunakan pelaporan kasar untuk mengurangi derau dalam laporan tingkat peristiwa untuk sumber tujuan ganda:
- Jika OS (aplikasi) dan tujuan Web ditentukan dalam pendaftaran sumber, laporan tingkat peristiwa akan menentukan apakah pemicu terjadi di tujuan web atau tujuan aplikasi secara default. Namun, untuk mempertahankan batas privasi, derau tambahan akan ditambahkan ke laporan ini.
- Teknologi iklan dapat menggunakan kolom
coarse_event_report_destinations
di bawah headerAttribution-Reporting-Register-Source
untuk mengaktifkan pelaporan kasar dan mengurangi derau. Jika sumber dengan kolomcoarse_event_report_destinations
yang ditentukan memenangkan atribusi, laporan yang dihasilkan akan menyertakan tujuan aplikasi dan web tanpa membedakan tempat sebenarnya pemicu terjadi, tetapi dengan lebih sedikit derau daripada laporan yang menentukan tujuan aplikasi atau web. - Laporan gabungan tidak berubah.
Untuk aplikasi yang menggunakan Tab Khusus Chrome
Beberapa aplikasi mungkin menggunakan Tab Kustom untuk merender konten web. Tab kustom berperilaku serupa dengan halaman web biasa saat melakukan pengukuran di seluruh aplikasi dan situs web seluler.
Daftarkan sumber aplikasi dan pemicu Tab Kustom:
- Ikuti petunjuk untuk mendaftarkan sumber aplikasi dan pemicu web.
Daftarkan sumber Tab Kustom dan pemicu aplikasi:
- Ikuti petunjuk untuk mendaftarkan sumber web dan pemicu aplikasi.
Mendaftarkan sumber CCT dan pemicu CCT
- Hal ini diperlakukan sama seperti atribusi web situs ke situs di Chrome.
Untuk aplikasi yang menggunakan WebView
Beberapa aplikasi mungkin menggunakan WebView untuk menampilkan konten. Ada berbagai kasus penggunaan untuk WebView, seperti merender iklan, menghosting konten web, atau fitur aplikasi kustom yang lebih cocok dengan format web.
Agar WebView dapat menggunakan Attribution Reporting API, aplikasi penyematan harus dikonfigurasi dengan izin yang benar.
Hanya atribusi tingkat OS yang tersedia di WebView. Header Attribution-Reporting-Support hanya akan menampilkan os, dan hanya jika Attribution Reporting API Android tersedia.
Saat mendelegasikan ke OS, WebView dapat menggunakan
registerSource
atauregisterWebSource
danregisterTrigger
atauregisterWebTrigger
. Metode yang digunakan oleh WebView ditetapkan oleh aplikasi yang merender WebView dan ditentukan berdasarkan WebView.- Perbedaan antara
registerSource
danregisterWebSource
adalah sumber mana yang dicatat ke dalam log sebagai penayang. DenganregisterSource
, aplikasi akan dicatat sebagai penayang; contoh kapan harus menggunakanregisterSource
adalah aplikasi penayang yang menampilkan iklan yang dirender menggunakan WebView. DenganregisterWebSource
, situs yang dihosting di WebView akan dicatat ke dalam log sebagai penayang; contoh kapan harus menggunakanregisterWebSource
adalah aplikasi yang menghosting WebView, dan situs yang dirender oleh WebView menampilkan iklan.registerTrigger
danregisterWebTrigger
berperilaku serupa. Diagram di item #3 menjelaskan berbagai skenario saat developer aplikasi atau SDK ingin mengonfigurasi API untuk menggunakanregisterSource
atauregisterWebSource
, danregisterTrigger
atauregisterWebTrigger
. - Secara default, WebView akan menggunakan
registerSource
danregisterWebTrigger
saat memanggil Android Attribution Reporting API. Hal ini mengaitkan sumber dengan aplikasi dan pemicu dengan origin tingkat atas URL di WebView saat pemicu terjadi.Jika aplikasi memerlukan perilaku yang berbeda, aplikasi harus menggunakan metode baru setAttributionRegistrationBehavior di class androidx.webkit.WebViewSettingsCompat. Metode ini akan menentukan apakah WebView harus memanggil
registerWebSource()
atauregisterWebTrigger()
, bukanregisterSource()
atauregisterTrigger()
.Perilaku ini harus ditetapkan untuk setiap WebView yang dimulai.
Jika SDK teknologi iklan memulai WebView, SDK harus menetapkan perilaku default ini.
Untuk aplikasi yang ingin menggunakan
registerWebSource()
guna mengaitkan pendaftaran sumber dengan situs di WebView, bukan aplikasi, aplikasi tersebut harus bergabung ke daftar yang diizinkan WebApp. Lengkapi formulir ini untuk bergabung ke daftar yang diizinkan. Tujuan daftar yang diizinkan adalah mengurangi pertimbangan privasi terkait menetapkan kepercayaan untuk konteks web.
Nilai Deskripsi Contoh kasus penggunaan APP_SOURCE_AND_WEB_TRIGGER (default) Mengizinkan aplikasi mendaftarkan sumber aplikasi (sumber yang terkait dengan nama paket aplikasi) dan pemicu web (pemicu yang terkait dengan eTLD+1) dari WebView. Aplikasi yang menggunakan WebView untuk menayangkan iklan, bukan mengaktifkan penjelajahan web WEB_SOURCE_AND_WEB_TRIGGER Mengizinkan aplikasi mendaftarkan sumber web dan pemicu web dari WebView. Aplikasi browser berbasis WebView, tempat tayangan iklan dan konversi dapat terjadi di situs di WebView. APP_SOURCE_AND_APP_TRIGGER Mengizinkan aplikasi mendaftarkan sumber aplikasi dan pemicu aplikasi dari WebView. Aplikasi berbasis WebView dengan tayangan iklan dan konversi harus selalu dikaitkan dengan aplikasi, bukan eTLD+1 dari WebView. DINONAKTIFKAN Menonaktifkan pendaftaran sumber dan pemicu dari WebView.
- Pendaftaran sumber dan pemicu dari WebView
Teknologi iklan harus merespons pendaftaran sumber menggunakan header
Attribution-Reporting-Register-OS-Source
. Berdasarkan perilaku yang ditetapkan untuk WebView, tindakan ini akan memanggilregisterSource()
atauregisterWebSource()
dengan OS dan memulai panggilan API sekunder dari Android Attribution Reporting API ke URI teknologi iklan.- Untuk menyelesaikan pendaftaran sumber, endpoint teknologi iklan harus merespons permintaan Android Attribution Reporting API dengan header respons.
Attribution-Reporting-Register-OS-Source: { "source_event_id":"123001", "destination":"android-app://com.example.advertiser", ... }
Sisa pendaftaran sumber tetap sama.
Teknologi iklan harus merespons pendaftaran pemicu menggunakan header
Attribution-Reporting-Register-OS-Trigger
. Berdasarkan perilaku yang ditetapkan untuk WebView, tindakan ini akan memanggilregisterTrigger()
atauregisterWebTrigger()
dengan OS dan memulai panggilan API sekunder dari Rb ke URI teknologi iklan.Untuk menyelesaikan pendaftaran pemicu, endpoint teknologi iklan harus merespons permintaan Android Attribution Reporting API dengan header respons.
Attribution-Reporting-Register-OS-Trigger: { "event_trigger_data": [{"trigger_data":"1"}], "aggregatable_trigger_data": [ {"key_piece":"0x400","source_keys":["campaignCounts"]}, {"key_piece":"0xA80","source_keys":["geoValue"]} ], ... }
- Proses pendaftaran pemicu lainnya tetap sama.
- Perbedaan antara
Debug
Saat menyiapkan penerapan aplikasi ke web, sebaiknya siapkan laporan debug untuk memverifikasi apakah sumber dan pemicu didaftarkan dengan benar, dan jika tidak didaftarkan, untuk menerima informasi tentang alasannya.
Untuk langkah-langkah proses debug Attribution Reporting umum, lihat cookbook proses debug.