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 untuk Android daripada menangani pendaftaran tersebut di browser. Hal ini memungkinkan Android mencocokkan sumber dan pemicu di situs dan aplikasi.

Panduan ini akan mengajari Anda cara menyiapkan atribusi lintas aplikasi dan web.

Saat Anda menyiapkan atribusi lintas aplikasi dan web, sebaiknya pelajari solusi proses debug yang tersedia untuk memastikan apakah penyiapan berfungsi sebagaimana mestinya.

Mendaftarkan sumber dan pemicu dengan Android OS

Atribusi lintas aplikasi dan web hanya akan tersedia jika Atribusi Reporting API diaktifkan di browser dan Android OS pada waktu yang sama perangkat seluler. Ketersediaan Android Attribution Reporting API telah dikirim melalui header Attribution-Reporting-Support. {i>Header<i} ini akan mengembalikan os, web, atau keduanya, tergantung pada apa yang tersedia di perangkat itu. Jika keduanya adalah teknologi iklan akan memiliki pilihan untuk mendaftarkan sumber web dan dipicu dengan browser atau OS.

Teknologi iklan harus memutuskan apakah akan mendaftarkan sumber web atau pemicu web dengan {i>browser<i} atau OS.

  • Untuk kampanye khusus web, teknologi iklan tetap dapat mendaftarkan sumber dan pemicu dengan Attribution Reporting API Chrome atau memilih untuk mendelegasikan keduanya ke OS. Untuk kampanye khusus web tempat sumber atau pemicu dapat terjadi di WebView, teknologi iklan harus mendelegasikan pendaftaran sumber dan pemicu ke OS. Lihat bagian tentang WebView untuk informasi selengkapnya.
  • Teknologi iklan harus menghindari mendaftarkan sumber dan pemicu dengan Chrome dan Android API secara bersamaan untuk menghindari pembuatan atribusi duplikat laporan.
  • Atribusi terjadi secara terpisah untuk browser dan OS. Jika suatu sumber terdaftar dengan browser tetapi pemicu terdaftar pada OS, keduanya tidak dapat dicocokkan begitu sebaliknya.
  • Untuk sumber yang dapat menghasilkan pemicu aplikasi atau web, hal ini sangat disarankan agar teknologi iklan mendelegasikan pendaftaran sumber web dan pemicu ke Attribution Reporting API Android.
  • Untuk pemicu yang mungkin telah didorong oleh sumber berbasis aplikasi, teknologi iklan dapat memilih untuk mendelegasikan pendaftaran pemicu web ke Pelaporan Atribusi Android Compute Engine API.
  • Untuk kampanye yang sumber dan pemicunya terjadi di aplikasi, keduanya akan harus terdaftar di Attribution Reporting API OS.

Mendaftarkan sumber aplikasi dan pemicu web

Untuk beberapa kampanye, sumber dapat terjadi di aplikasi saat pemicu akan terjadi di situs web di {i>browser<i} seluler pada perangkat yang sama.

Contoh

Seorang pengguna sedang membaca artikel di aplikasi berita favoritnya. Mereka melihat iklan murah penerbangan ke Paris dan dengan antusias mengklik untuk memesan. Teknologi iklan yang menayangkan iklan dalam aplikasi berita mendaftarkan sumber klik dengan Attribution Reporting API Android. Pengguna diarahkan ke halaman web pengiklan di Chrome tempat mereka dapat mengonversi. Teknologi iklan di situs pengiklan memeriksa apakah API level OS tersedia, dan memang tersedia. Teknologi iklan mendaftarkan pemicu konversi dengan memerintahkan Chrome untuk mendelegasikan pendaftaran ke OS, bukan mendaftar langsung dengan Attribution Reporting API Chrome. Atribusi tingkat OS Reporting API 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 dengan menggunakan registerSource()

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

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

Pendaftaran pemicu web:

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

  2. ARA web menampilkan informasi tentang platform yang didukung

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

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

  5. OS ARA 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. OS ARA akan melakukan atribusi sesuai dengan logika yang sama yang diterapkan pada atribusi 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 Atribusi Android Reporting API dengan penyesuaian berikut:

    • Untuk mendaftarkan sumber aplikasi yang diharapkan melakukan konversi di situs, Header respons Attribution-Reporting-Register-Source harus menyertakan halaman web tujuan aplikasi (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 di header Attribution-Reporting-Redirect di latar belakang dan di saat jalur pengalihan 302 dijalankan di latar depan, terhadap permintaan navigasi. Permintaan ini akan diarahkan ke URL yang sama dan dapat mengakibatkan di pendaftaran penghitungan ganda penyedia pengukuran pihak ketiga. Kepada mencegah pendaftaran ganda, teknologi iklan dapat mengubah perilaku pengalihan untuk mengirim pendaftaran Attribution Reporting API ke alternatif URL determenistik.
    • Untuk mengaktifkan perilaku ini, teknologi iklan perlu menyertakan header HTTP baru saat menanggapi permintaan pendaftaran:

      • Header-nya 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 adalah sama dengan proses pendaftaran sumber aplikasi ke aplikasi.

  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 di Chrome

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

      2. Header permintaan Attribution-Reporting-Support ditampilkan oleh Chrome di bidang teknologi iklan. Jika API diaktifkan di browser Chrome dan Di perangkat Android, header-nya akan menampilkan os, web

      Attribution-Reporting-Support: os, web
      
    • Teknologi iklan kemudian akan 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, yaitu 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 tetap dapat menetapkan untuk menangani pendaftaran pemicu dengan menyertakan Header Attribution-Reporting-Info. Kuncinya adalah platform yang disukai dan nilai yang diizinkan adalah os dan web. Browser akan menggunakan platform pilihan ketika tersedia dan akan kembali ke platform web ketika OS tidak tersedia.

    Attribution-Reporting-Info: preferred-platform=os
    
    • Untuk menyelesaikan pendaftaran pemicu, endpoint teknologi iklan harus merespons ke 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 sebagian kampanye, sumber dapat muncul di situs pada browser seluler sementara pemicu terjadi di aplikasi pada perangkat yang sama.

Contoh

Seorang pengguna sedang menjelajahi situs di browser Chrome pada ponsel Android-nya. Dia melihat iklan sweter dari salah satu toko favoritnya. Mereka mengeklik mereka dan diarahkan ke aplikasi yang telah mereka download. Teknologi iklan di situs tempat iklan ditayangkan mendaftarkan sumber klik dengan memerintahkan Chrome untuk mendelegasikan pendaftaran ke Android Attribution Reporting API, menggunakan Attribution Reporting API di Chrome. Pengguna membeli {i>sweater<i} di aplikasi belanja. Teknologi iklan di aplikasi pengiklan kemudian mendaftarkan pemicu konversi dengan Attribution Reporting API Android. Tingkat OS Attribution Reporting API dapat mencocokkan sumber web dan pemicu aplikasi dan 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 bagian Attribution Reporting API

  2. ARA web menampilkan informasi tentang platform yang didukung

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

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

  5. OS ARA mengambil alih dan mengirim permintaan ke URL server teknologi iklan yang disediakan berdasarkan 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 server teknologi iklan URL diberikan kepada registerTrigger()

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

  4. OS ARA akan melakukan atribusi sesuai dengan logika yang sama yang diterapkan pada atribusi 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 memerintahkan Chrome untuk mendelegasikan pendaftaran ke Android Attribution Reporting API:

    • Untuk kasus penggunaan web ke aplikasi, saat mendaftarkan sumber, atribusi sumber 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 level 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, sedangkan teknologi iklan melakukannya 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 ditangani pendaftaran sumber dengan menyertakan header Attribution-Reporting-Info. Kuncinya adalah platform pilihan dan nilai yang diizinkan adalah os dan web. Tujuan browser akan menggunakan platform pilihan jika tersedia dan akan kembali ke platform web ketika OS tidak tersedia.
    Attribution-Reporting-Info: preferred-platform=os
    
    • Untuk menyelesaikan pendaftaran sumber, endpoint teknologi iklan harus merespons ke 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",
        ...
    }
    
    • Guna mendukung pengalihan untuk pendaftaran sumber, Chrome akan mengikuti mengalihkan dan memanggil API konteks web untuk setiap hop pengalihan.
    • Sisa dari pendaftaran sumber tetap sama.
  4. Teknologi iklan di aplikasi pengiklan mendaftarkan pemicu dengan Android Attribution Reporting API:

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

Kampanye yang memiliki potensi tujuan aplikasi dan web

  1. Menyiapkan tujuan ganda

    • Beberapa kampanye mungkin disiapkan untuk menghasilkan 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 dengan OS, baik tujuan aplikasi dan web dapat ditentukan dalam parameter masing-masing.
    • Tujuan aplikasi harus ada di kolom destination
    • Tujuan web harus ada 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 umum akan menjelaskan cara menggunakan tujuan ganda dapat memengaruhi derau dalam laporan Anda.
  2. Menggunakan pelaporan umum untuk mengurangi derau dalam laporan tingkat peristiwa untuk sumber tujuan:

    • Jika OS (aplikasi) dan tujuan Web ditentukan di sumber pendaftaran, 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 bagian Header Attribution-Reporting-Register-Source untuk mengaktifkan pelaporan umum dan mengurangi derau. Jika sumber dengan coarse_event_report_destinations yang ditentukan, laporan yang dihasilkan akan menyertakan aplikasi dan tujuan web tanpa membedakan tempat pemicu terjadi, tetapi dengan lebih sedikit derau daripada laporan tempat tujuan aplikasi atau web ditentukan.
    • Laporan agregat tetap tidak berubah.

Untuk aplikasi yang menggunakan Tab Khusus Chrome

Beberapa aplikasi mungkin menggunakan Tab Khusus untuk merender konten web. Perilaku tab khusus mirip dengan halaman web biasa saat melakukan pengukuran di berbagai aplikasi dan situs web seluler.

  1. Mendaftarkan sumber aplikasi dan pemicu Tab Khusus:
  2. Mendaftarkan sumber Tab Khusus 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 aplikasi kustom fitur yang lebih cocok untuk format web.

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

  2. Saat mendelegasikan ke OS, WebView dapat menggunakan registerSource atau registerWebSource dan registerTrigger atau registerWebTrigger. Metode mana yang yang digunakan oleh WebView disetel oleh aplikasi yang merender WebView dan ditentukan di per WebView.

    • Perbedaan antara registerSource dan registerWebSource adalah sumber dicatat sebagai penayang. Dengan registerSource, aplikasi dicatat ke dalam log sebagai penayang; contoh kapan harus menggunakan registerSource adalah aplikasi penayang yang menampilkan iklan yang dirender menggunakan WebView. Dengan registerWebSource, situs yang dihosting di WebView dicatat dalam log sebagai penerbit; contoh saat menggunakan registerWebSource adalah aplikasi yang menghosting WebView, dan situs web yang dirender oleh WebView menampilkan iklan. registerTrigger dan registerWebTrigger berperilaku serupa. Tujuan diagram di item #3 menjelaskan berbagai skenario ketika developer aplikasi atau SDK ingin mengonfigurasi API untuk menggunakan registerSource atau registerWebSource, dan registerTrigger atau registerWebTrigger.
  3. Secara default, WebView akan menggunakan registerSource dan registerWebTrigger saat memanggil Attribution Reporting API Android. Fungsi ini mengaitkan sumber dengan aplikasi dan terpicu dengan asal tingkat atas dari URL di WebView saat pemicu terjadi.

    • Jika aplikasi memerlukan perilaku yang berbeda, aplikasi harus menggunakan metode baru setAttributionRegistrationBehavior di androidx.webkit.WebViewSettingsCompat . Metode ini akan menentukan apakah WebView harus memanggil registerWebSource() atau registerWebTrigger(), bukan registerSource() atau registerTrigger().
      • Perilaku ini perlu 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 sumber pendaftaran dengan situs web di WebView, bukan di aplikasi, mereka harus bergabung ke daftar yang diizinkan WebApp. Lengkapi formulir ini untuk bergabung ke daftar yang diizinkan. Tujuan tujuan daftar yang diizinkan adalah mengurangi pertimbangan privasi terkait membangun kepercayaan untuk konteks web.
    • Opsi untuk setAttributionRegistrationBehavior
    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.
  4. Pendaftaran sumber dan pemicu dari WebView

    • Teknologi iklan harus merespons pendaftaran sumber menggunakan metode 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 Atribusi Android 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 dari pendaftaran sumber tetap sama.

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

    • Untuk menyelesaikan pendaftaran pemicu, endpoint teknologi iklan harus merespons permintaan Android Attribution Reporting API dengan respons {i>header<i}.
    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 debug laporan untuk memverifikasi apakah sumber dan pemicu didaftarkan dengan benar, serta apakah keduanya tidak terdaftar, untuk menerima informasi tentang alasannya.

Untuk mengetahui langkah-langkah proses debug Pelaporan Atribusi umum, lihat Cookbook proses debug.