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 <a>
• Tag <img>
• Tag <script>
• fetch panggilan
• XMLHttpRequest
• window.open

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 membuat permintaan.

2. Selesaikan pendaftaran pemicu dengan merespons melalui header pendaftaran pemicu.
   
   

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

   Di header ini, tentukan data pemicu yang pada akhirnya ingin Anda munculkan dalam laporan. Respons apa pun dapat menetapkan header ini. Selama itu merupakan respons terhadap permintaan yang dibuat dari situs yang cocok dengan destination, sumber akan dicocokkan. Saat header diterima, browser akan 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]"
     }]
   }
   ```
   
   **Example for summary reports:**
   
   ```json
   {
     ... // 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 tempat halaman tersebut berada. 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 di 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 harus menggunakan attributionsrc atau attributionReporting. Lihat tabel berikut untuk mengetahui detail tentang kapan fitur tersebut diperlukan.

Jika attributionsrc bersifat opsional, berarti permintaan tersebut memenuhi syarat untuk Attribution Reporting. Jika Anda menggunakan attributionsrc, browser akan mengirimkan header Attribution-Reporting-Eligible. Hal ini juga berguna untuk pengukuran aplikasi ke web: jika attributionsrc ada, browser akan mengirimkan header Attribution-Reporting-Support.

Metode pendaftaran	Pemicu
Tag <a>	T/A Anchor tidak dapat mendaftarkan pemicu.
Tag <img>	attributionsrc bersifat opsional. Header cukup untuk mendaftarkan pemicu.
Tag <script>	attributionsrc bersifat opsional. Header cukup untuk mendaftarkan pemicu.
fetch panggilan	Opsi attributionReporting wajib ada.
XMLHttpRequest	Opsi attributionReporting wajib ada.
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 situs-nya cocok dengan situs yang disediakan di tujuan saat 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:

// With fetch
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 });

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

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

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 harus berupa URL tunggal.

Penggunaan URL menyebabkan browser memulai permintaan pengambilan keepalive terpisah—satu untuk setiap URL—yang mencakup header permintaan Attribution-Reporting-Eligible.

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

Misalnya, jika perlu mendaftarkan sumber untuk klik pada elemen anchor, Anda mungkin sebenarnya tidak dapat mengontrol tujuan. Dalam hal ini, Anda ingin konfigurasi dengan mengirim header pendaftaran sumber sebagai respons terhadap permintaan yang terpisah dari navigasi, dan dapat sepenuhnya Anda kontrol. Dengan menentukan nilai eksplisit untuk attributionsrc, Anda memerintahkan browser untuk membuat permintaan tambahan tersebut 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.