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 Anda menyiapkan atribusi lintas aplikasi dan web, sebaiknya Anda juga memahami solusi penelusuran kesalahan yang tersedia untuk memverifikasi bahwa 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 OS Android pada perangkat yang sama. Ketersediaan Android Attribution Reporting API 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 yang sumber atau pemicunya dapat 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 API Chrome dan Android secara bersamaan untuk menghindari pembuatan laporan atribusi duplikat.

  • 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, sebaiknya teknologi iklan mendelegasikan pendaftaran sumber dan pemicu web 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 Attribution Reporting API OS.

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. Dia melihat iklan penerbangan murah ke Paris dan dengan senang hati 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 memeriksa apakah API tingkat OS tersedia, dan ternyata tersedia. Teknologi iklan mendaftarkan pemicu konversi dengan menginstruksikan Chrome untuk mendelegasikan pendaftaran ke OS, bukan mendaftarkannya secara langsung dengan Attribution Reporting API Chrome. Kemudian, Attribution Reporting API tingkat OS dapat mencocokkan sumber aplikasi dan pemicu web serta mengirimkan 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 mana yang didukung

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

  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 ke 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 melakukan konversi di situs, header respons Attribution-Reporting-Register-Source harus menyertakan tujuan web (eTLD+1) dan 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 di header Attribution-Reporting-Redirect di latar belakang dan pada saat yang sama, jalur pengalihan 302 dieksekusi di latar depan untuk permintaan navigasi yang ada. Permintaan ini akan ditujukan ke URL yang sama dan dapat menyebabkan penyedia pengukuran pihak ketiga menghitung pendaftaran dua kali. Untuk mencegah pendaftaran dihitung dua kali, teknologi iklan dapat mengubah perilaku pengalihan untuk mengirim pendaftaran Attribution Reporting API ke URL alternatif yang 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 berupa 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 Android Attribution Reporting API:

    • Setelah pengguna menyelesaikan konversi di situs, teknologi iklan akan membuat permintaan untuk mendaftarkan pemicu dengan Chrome

      1. Permintaan piksel 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
      
    • Kemudian, teknologi iklan 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 API OS 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 preferred-platform 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 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 pada perangkat yang sama.

Contoh

Pengguna menjelajahi situs di browser Chrome di ponsel Android mereka. Mereka melihat iklan sweater dari salah satu toko favorit mereka. Mereka mengklik iklan dan diarahkan ke aplikasi yang sudah 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 tingkat OS dapat mencocokkan sumber web dan pemicu aplikasi serta mengirimkan 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 mana yang didukung

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

  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 ke 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 API OS 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 preferred-platform dan nilai yang diizinkan adalah os dan web. Browser akan menggunakan platform pilihan jika tersedia dan akan melakukan penggantian 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 untuk pendaftaran sumber, Chrome akan mengikuti pengalihan dan memanggil API konteks web untuk setiap lompatan pengalihan.
    • Bagian pendaftaran sumber lainnya tetap sama.
  4. Teknologi iklan di aplikasi pengiklan mendaftarkan pemicu dengan Android Attribution Reporting API:

    • Untuk pemicu yang terjadi di aplikasi, aplikasi mendaftarkan pemicu dengan Android Attribution Reporting API seperti biasa.

Kampanye yang memiliki tujuan potensial aplikasi dan web

  1. Menyiapkan tujuan ganda

    • Beberapa kampanye dapat disiapkan untuk berkonversi 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 terjadinya pemicu. Saat mendaftarkan sumber dengan 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 cara penggunaan tujuan ganda dapat memengaruhi derau dalam laporan Anda.
  2. Menggunakan pelaporan kasar untuk mengurangi derau dalam laporan tingkat peristiwa untuk sumber tujuan ganda:

    • Jika tujuan OS (aplikasi) dan 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 mirip dengan halaman web biasa saat mengukur di seluruh aplikasi dan situs web seluler.

  1. Mendaftarkan sumber aplikasi dan pemicu Tab Kustom:

  2. Mendaftarkan 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 sesuai 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 Android Attribution Reporting API 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 per WebView.

    • Perbedaan antara registerSource dan registerWebSource adalah sumber yang dicatat sebagai penayang. Dengan registerSource, aplikasi dicatat sebagai penayang; contoh waktu penggunaan registerSource adalah aplikasi penayang yang menampilkan iklan yang dirender menggunakan WebView. Dengan registerWebSource, situs yang dihosting di WebView dicatat sebagai penayang; contoh waktu penggunaan 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 asal tingkat atas URL di WebView saat pemicu terjadi.
      • Jika aplikasi memerlukan perilaku yang berbeda, aplikasi harus menggunakan metode baru setAttributionRegistrationBehavior pada 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() untuk 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, registerSource() atau registerWebSource() akan dipanggil 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. Bagian pendaftaran sumber lainnya tetap sama.

    4. Teknologi iklan harus merespons pendaftaran pemicu menggunakan header Attribution-Reporting-Register-OS-Trigger. Berdasarkan perilaku yang ditetapkan untuk WebView, hal 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 buku panduan proses debug.