Panduan Penerapan Lintas Web dan Aplikasi Attribution Reporting API

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.

Alur atribusi aplikasi ke web
Alur atribusi aplikasi ke web

Pendaftaran sumber aplikasi:

  1. SDK teknologi iklan di Aplikasi Android Daily News mendaftarkan klik menggunakan registerSource()

  2. Attribution Reporting API di Android mengirimkan permintaan ke URL server teknologi iklan yang diberikan ke registerSource()

  3. Server teknologi iklan merespons dengan header Attribution-Reporting-Register-Source untuk menyelesaikan pendaftaran sumber

Pendaftaran pemicu web:

  1. Teknologi iklan mendaftarkan pemicu dan memeriksa ketersediaan OS di Attribution Reporting API

  2. ARA web menampilkan informasi tentang platform yang didukung

  3. Header OS-Trigger memberi tahu ARA API web untuk memanggil fungsi registerWebTrigger() ARA API OS

  4. Panggilan ke registerWebTrigger() terjadi di balik layar dan developer tidak perlu memanggil registerWebTrigger() dengan OS secara langsung

  5. ARA OS mengambil alih dan mengirim permintaan ke URL server teknologi iklan yang disediakan oleh header Attribution-Reporting-Register-OS-Trigger

  6. Teknologi iklan akan menyelesaikan pendaftaran pemicu dengan OS API

  7. 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:

  1. 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
      
    • Proses pendaftaran sumber lainnya sama dengan pendaftaran sumber aplikasi ke aplikasi standar.

  2. 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

      1. Permintaan pixel atau fetch() dapat digunakan untuk membuat permintaan guna mendaftarkan pemicu

      2. Header permintaan Attribution-Reporting-Support ditampilkan oleh Chrome ke teknologi iklan. Jika API diaktifkan di browser Chrome dan perangkat Android, header akan menampilkan os, 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:

      1. Memberi tahu Chrome untuk mendelegasikan pendaftaran ke OS

      2. Chrome mendelegasikan pendaftaran ke OS dengan memanggil fungsi OS API registerWebTrigger()

        • Panggilan ke registerWebTrigger() terjadi di balik layar, teknologi iklan tidak perlu memanggil registerWebTrigger() secara langsung
      3. 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 header Attribution-Reporting-Info. Kuncinya adalah platform-pilihan dan nilai yang diizinkan adalah os dan web. 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"]}
        ],
        ...
    }
    

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.

Alur atribusi web ke aplikasi
Alur atribusi web ke aplikasi

Pendaftaran sumber web:

  1. Teknologi iklan mendaftarkan sumber dan memeriksa ketersediaan OS di Attribution Reporting API

  2. ARA web menampilkan informasi tentang platform yang didukung

  3. Header OS-Source memberi tahu ARA API web untuk memanggil fungsi registerWebSource() ARA API OS

  4. Panggilan ke registerWebSource() terjadi di balik layar dan developer tidak perlu memanggil registerWebSource() dengan OS secara langsung

  5. ARA OS mengambil alih dan mengirim permintaan ke URL server teknologi iklan yang disediakan oleh header Attribution-Reporting-Register-OS-Source

  6. Teknologi iklan akan menyelesaikan pendaftaran sumber dengan OS API

Pendaftaran pemicu aplikasi:

  1. SDK teknologi iklan di aplikasi Android toko Pakaian mendaftarkan pemicu dengan ARA OS

  2. Attribution Reporting API di Android mengirimkan permintaan ke URL server teknologi iklan yang diberikan ke registerTrigger()

  3. Server teknologi iklan merespons dengan header Attribution-Reporting-Register-Trigger untuk menyelesaikan pendaftaran pemicu

  4. 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:

  1. 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">
    
  2. Header permintaan Attribution-Reporting-Support ditampilkan oleh Chrome ke teknologi iklan. Jika API diaktifkan di browser Chrome dan perangkat Android, header akan menampilkan os, web.

    Attribution-Reporting-Support: os, web
    
  3. Teknologi iklan harus memberi tahu Chrome untuk mendelegasikan ke API tingkat OS menggunakan header Attribution-Reporting-Register-OS-Source yang:

    1. Memberi tahu Chrome untuk mendelegasikan pendaftaran ke OS
    2. Chrome mendelegasikan pendaftaran ke OS dengan memanggil fungsi OS API registerWebSource()
    3. Panggilan ke registerWebSource() terjadi di balik layar, teknologi iklan tidak perlu memanggil registerWebSource() secara langsung
    4. 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 header Attribution-Reporting-Info. Kuncinya adalah platform-pilihan dan nilai yang diizinkan adalah os dan web. 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.
  4. 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

  1. 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.
  2. 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 header Attribution-Reporting-Register-Source untuk mengaktifkan pelaporan kasar dan mengurangi derau. Jika sumber dengan kolom coarse_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.

  1. Daftarkan sumber aplikasi dan pemicu Tab Kustom:

  2. Daftarkan sumber Tab Kustom dan pemicu aplikasi:

  3. Mendaftarkan sumber CCT dan pemicu CCT

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.

  1. Agar WebView dapat menggunakan Attribution Reporting API, aplikasi penyematan harus dikonfigurasi dengan izin yang benar.

  2. Hanya atribusi tingkat OS yang tersedia di WebView. Header Attribution-Reporting-Support hanya akan menampilkan os, dan hanya jika Attribution Reporting API Android tersedia.

  3. Saat mendelegasikan ke OS, WebView dapat menggunakan registerSource atau registerWebSource dan registerTrigger atau registerWebTrigger. Metode yang digunakan oleh WebView ditetapkan oleh aplikasi yang merender WebView dan ditentukan berdasarkan WebView.

    • Perbedaan antara registerSource dan registerWebSource adalah sumber mana yang dicatat ke dalam log sebagai penayang. Dengan registerSource, aplikasi akan dicatat sebagai penayang; contoh kapan harus menggunakan registerSource adalah aplikasi penayang yang menampilkan iklan yang dirender menggunakan WebView. Dengan registerWebSource, situs yang dihosting di WebView akan dicatat ke dalam log sebagai penayang; contoh kapan harus menggunakan registerWebSource adalah aplikasi yang menghosting WebView, dan situs yang dirender oleh WebView menampilkan iklan. registerTrigger dan registerWebTrigger berperilaku serupa. Diagram di item #3 menjelaskan berbagai skenario saat developer aplikasi atau SDK ingin mengonfigurasi API untuk menggunakan registerSource atau registerWebSource, dan registerTrigger atau registerWebTrigger.
    • Secara default, WebView akan menggunakan registerSource dan registerWebTrigger 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() atau registerWebTrigger(), bukan registerSource() atau registerTrigger().

      • 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.
    1. Pendaftaran sumber dan pemicu dari WebView
    2. Teknologi iklan harus merespons pendaftaran sumber menggunakan header Attribution-Reporting-Register-OS-Source. Berdasarkan perilaku yang ditetapkan untuk WebView, tindakan ini akan memanggil registerSource() atau registerWebSource() 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",
        ...
      }
      
    3. Sisa pendaftaran sumber tetap sama.

    4. Teknologi iklan harus merespons pendaftaran pemicu menggunakan header Attribution-Reporting-Register-OS-Trigger. Berdasarkan perilaku yang ditetapkan untuk WebView, tindakan ini akan memanggil registerTrigger() atau registerWebTrigger() dengan OS dan memulai panggilan API sekunder dari Rb ke URI teknologi iklan.

    5. 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"]}
        ],
        ...
    }
    

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.