Mendaftarkan pemicu atribusi

Pelajari cara mendaftarkan pemicu atribusi untuk menghitung konversi Anda.

Pemicu atribusi adalah peristiwa yang memberi tahu browser untuk mencatat konversi.

Dengan mengikuti langkah-langkah dalam dokumen ini, Anda dapat mendaftarkan pemicu untuk mencatat konversi yang kemudian diatribusikan browser ke peristiwa sumber yang relevan—yaitu, tayangan iklan atau klik iklan.

Metode pendaftaran

Untuk mendaftarkan pemicu, gunakan elemen HTML atau panggilan JavaScript:

• Tag <img>
• Tag <script>
• fetch panggilan
• XMLHttpRequest

Tindakan ini akan menghasilkan permintaan jaringan yang kemudian Anda respons dengan header respons HTTP pendaftaran pemicu.

Mendaftarkan pemicu untuk mengatribusikan konversi

Mendaftarkan pemicu mirip dengan mendaftarkan peristiwa sumber atribusi. Langkah-langkah lengkapnya akan dijelaskan nanti. Berikut ringkasannya:

1. Memulai pendaftaran pemicu. Gunakan piksel atau panggilan fetch() untuk melakukan membuat permintaan.

2. Menyelesaikan pendaftaran pemicu dengan merespons menggunakan pemicu header pendaftaran.

   Setelah menerima permintaan piksel—dikirim ke endpoint yang ditentukan dalam atribut src biasa, atau ke endpoint yang ditentukan di attributionsrc jika Anda telah memilih untuk menggunakan attributionsrc dan memberikannya nilai—respons dengan header Attribution-Reporting-Register-Trigger.

   Di header ini, tentukan data pemicu yang ingin Anda tampilkan pada akhirnya. Respons apa pun dapat menetapkan header ini. Selama masih merespons permintaan yang dibuat dari situs yang cocok dengan destination, sumber akan dicocokkan. Ketika header diterima, browser mencari sumber yang cocok dan menjadwalkan laporan.

   Contoh untuk laporan tingkat peristiwa:

   {
     "event_trigger_data": [{
       "trigger_data": "[unsigned 64-bit integer]",
       "priority": "[signed 64-bit integer]",
       "deduplication_key": "[unsigned 64-bit integer]"
     }]
   }
   

   Contoh untuk laporan ringkasan:

   {
     ... // existing fields, such as "event_trigger_data"
   
     "aggregatable_trigger_data": [
      {
        "key_piece": "0x400",
        "source_keys": ["campaignCounts"]
      },
      {
        "key_piece": "0xA80",
        "source_keys": ["geoValue", "nonMatchingKeyIdsAreIgnored"]
      }
     ],
     "aggregatable_values": {
       "campaignCounts": 32768,
       "geoValue": 1664
     }
   }
   

Catatan: Saat browser menerima respons pemicu atribusi dari URL attributionsrc di halaman tertentu, pencarian penyimpanan lokal dilakukan untuk menemukan sumber yang cocok dengan situs asal dan tujuan attributionsrc yang mencakup halaman tersebut. Jika beberapa sumber ditemukan, browser akan memilih sumber yang terakhir disimpan—kecuali jika sumber memiliki prioritas yang berbeda, browser akan memilih sumber yang memiliki prioritas terbesar.

Menangani subdomain

Jika destination adalah https://advertiser.example, konversi pada kedua https://advertiser.example dan subdomainnya, seperti https://shop.advertiser.example dapat diatribusikan.

Jika destination adalah https://shop.advertiser.example, konversi pada https://advertiser.example dan https://shop.advertiser.example dapat diatribusikan.

Atribut wajib dan opsional

Saat menggunakan elemen HTML atau melakukan panggilan JavaScript untuk mendaftarkan pemicu, Anda mungkin perlu menggunakan attributionsrc atau attributionReporting. Lihat tabel berikut untuk mengetahui detail tentang kapan tidak diperlukan.

Jika attributionsrc bersifat opsional, berarti permintaan tersebut memenuhi syarat untuk Attribution Reporting. Jika Anda menggunakan attributionsrc, browser akan mengirimkan Header Attribution-Reporting-Eligible. Juga berguna untuk aplikasi ke web pengukuran: jika attributionsrc ada, browser akan mengirim metode Header Attribution-Reporting-Support.

Metode pendaftaran	Pemicu
Tag <a>	T/A: Anchor tidak dapat mendaftarkan pemicu.
Tag <img>	attributionsrc bersifat opsional. {i>Header<i} sudah cukup untuk mendaftarkan pemicu.
Tag <script>	attributionsrc bersifat opsional. {i>Header<i} sudah cukup untuk mendaftarkan pemicu.
fetch panggilan	Opsi attributionReporting adalah wajib.
XMLHttpRequest	Opsi attributionReporting adalah wajib.
window.open()	T/A: window.open tidak dapat mendaftarkan pemicu.

Langkah 1: Memulai pendaftaran pemicu

Anda dapat mendaftarkan pemicu menggunakan piksel (tag <img>) atau tag skrip.

Menggunakan piksel konversi baru atau yang ada

Contoh berikut memicu atribusi pada gambar yang ada dengan menambahkan atribut attributionsrc.

Asal untuk attributionsrc harus cocok dengan asal yang melakukan pendaftaran sumber.

<img src="https://advertiser.example/conversionpixel"
     attributionsrc="https://adtech.example/attribution_trigger?purchase=13">

Contoh berikutnya memicu atribusi dengan menambahkan atribut attributionsrc piksel konversi baru.

Asal untuk src harus cocok dengan asal yang melakukan pendaftaran sumber.

<img src="https://adtech.example/conversionpixel"
     attributionsrc>

Poin penting: Dalam kedua kasus tersebut, atribusi hanya dapat dipicu di halaman yang situsnya cocok dengan situs yang disediakan di tujuan setelah pendaftaran sumber.

Menggunakan tag skrip

Anda dapat melakukan pendaftaran pemicu dengan tag skrip; perilakunya identik dengan <img>. Contoh kode berikut mengilustrasikan penggunaan fetch() dan XMLHttpRequest() (XHR).

Kode ini secara efektif menyimulasikan fungsi permintaan HTML dengan attributionsrc:

const attributionReporting = {
  eventSourceEligible: false,
  triggerEligible: true,
};

const req = new XMLHttpRequest();
req.open("GET", url);
req.setAttributionReporting(attributionReporting);
req.send();

const attributionReporting = {
  eventSourceEligible: false,
  triggerEligible: true,
};

// Optionally set keepalive to ensure the request outlives the page.
window.fetch("https://adtech.example/attribution_source?my_ad_id=123",
  { keepalive: true, attributionReporting });

Poin penting:

• Asal atau url yang ditetapkan dalam fetch() atau open() harus cocok dengan asal yang melakukan pendaftaran sumber.
• Atribusi hanya dapat dipicu di halaman yang situsnya cocok dengan situs yang disediakan di tujuan setelah pendaftaran sumber.

attributionsrc dengan atau tanpa nilai

Anda dapat menambahkan attributionsrc dengan atau tanpa nilai.

<!-- Without a value -->
<img src="..." width="1" height="1" attributionsrc>

<!-- With a value (URL) -->
<img src="..." width="1" height="1" attributionsrc="https://...">

Jika Anda menetapkan nilai untuk attributionsrc, nilai tersebut dapat berupa satu atau beberapa URL yang dipisahkan spasi.

Penggunaan URL menyebabkan browser memulai permintaan pengambilan keepalive terpisah—yaitu untuk setiap URL—yang mencakup permintaan Attribution-Reporting-Eligible {i>header<i}.

Hal ini berguna jika Anda ingin membuat pendaftaran pemicu dengan merespons sebuah yang terpisah dari permintaan utama elemen.

Misalnya, jika Anda perlu mendaftarkan {i>trigger<i} pada elemen gambar, Anda mungkin sebenarnya tidak mengontrol respons gambar; dalam hal ini, Anda perlu konfigurasi yang memungkinkan Anda mengirim header pendaftaran pemicu sebagai respons terhadap permintaan yang terpisah dari gambar, dan dapat Anda kontrol sepenuhnya. Menurut menentukan nilai eksplisit untuk attributionsrc, Anda menginstruksikan untuk membuat permintaan tambahan itu dan mengonfigurasi tujuannya.

Langkah 2: Tanggapi dengan header

Setelah menerima permintaan browser, tanggapi dan sertakan header Attribution-Reporting-Register-Trigger dalam respons Anda:

JSON.stringify({
  event_trigger_data: [{
    trigger_data: "412444888111012",
    // Optional
    priority: "1000000000000",
    deduplication_key: "2345698765"
  }],
  debug_key: "1115698977"
});

Perhatian: Nilai kolom event_trigger_data harus disusun bertingkat dalam tanda kurung siku, karena browser mengharapkan array JSON. Hal ini berguna untuk filter.

Langkah berikutnya

Pelajari cara Mendaftarkan sumber atribusi.