Mendaftarkan sumber atribusi

Pelajari cara mendaftarkan sumber untuk mengatribusikan klik dan penayangan ke peristiwa yang sesuai.

Sumber atribusi adalah peristiwa terkait iklan (klik atau penayangan), tempat teknologi iklan dapat menyertakan jenis informasi berikut:

  • Data pelaporan kontekstual, seperti ID materi iklan, informasi tentang kampanye, atau geografi.
  • Tujuan konversi, seperti di situs tempat Anda mengharapkan pengguna melakukan konversi.

Dengan mengikuti langkah-langkah dalam dokumen ini, Anda dapat mendaftarkan sumber—tayangan iklan atau klik—yang kemudian diatribusikan oleh browser untuk dikonversi.

Metode pendaftaran

Untuk mendaftarkan sumber atribusi, gunakan elemen HTML atau panggilan JavaScript:

  • Tag <a>
  • Tag <img>
  • Tag <script>
  • fetch panggilan
  • XMLHttpRequest
  • window.open panggilan

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

Mendaftarkan sumber untuk klik atau penayangan

Untuk mendaftarkan sumber atribusi untuk klik atau tampilan, ikuti langkah-langkah yang diuraikan di sini. Berikut langkah-langkah lengkapnya. Berikut ringkasannya:

  1. Mulai pendaftaran sumber. Gunakan elemen HTML atau Panggilan JavaScript untuk membuat permintaan. Langkah ini berbeda untuk klik dan tampilan, seperti yang akan Anda lihat di bagian berikut.

  2. Selesaikan pendaftaran sumber dengan merespons dengan sumbernya header pendaftaran. Setelah menerima permintaan tersebut, tanggapi dengan header Attribution-Reporting-Register-Source. Di {i>header<i} tersebut, tentukan konfigurasi Pelaporan Atribusi yang diinginkan. Langkah ini sama untuk klik dan tampilan.

    Contoh untuk laporan ringkasan:

    {
  "aggregation_keys": {
    "campaignCounts": "0x159",
    "geoValue": "0x5"
  },
  "aggregatable_report_window": "86400",
  "destination": "https://example.com"
}

    Contoh untuk laporan tingkat peristiwa:

    {
  "source_event_id": "12340873456",
  "destination": "[eTLD+1]",
  "expiry": "[64-bit signed integer]",
  "priority": "[64-bit signed integer]",
  "event_report_window": "[64-bit signed integer]"
}

Atribut wajib dan opsional

Saat menggunakan elemen HTML atau melakukan panggilan JavaScript untuk mendaftarkan sumber, 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 Sumber
Tag <a> (sumber navigasi)
attributionsrc wajib diisi.
Tag <img> (sumber peristiwa)
attributionsrc wajib diisi.
Tag <script> (sumber peristiwa)
attributionsrc wajib diisi.
fetch panggilan Opsi attributionReporting adalah wajib.
XMLHttpRequest Opsi attributionReporting adalah wajib.
window.open panggilan (sumber navigasi)
attributionsrc wajib diisi.

Langkah 1: Mulai pendaftaran sumber

Langkah 1 berbeda untuk klik dan tampilan.

Untuk mendaftarkan sumber atribusi untuk klik, Anda dapat menggunakan tag <a> atau JavaScript window.open().

Menggunakan anchor

Tambahkan attributionsrc ke tag <a> yang ada yang tayangan atau kliknya ingin Anda ukur:

<a href="https://shoes.example/..." attributionsrc>Click me</a>

Tinjau kode contoh untuk mengetahui informasi selengkapnya.

Menggunakan skrip

Hubungi window.open() dengan attributionsrc:

window.open(
  "https://shoes.example/...",
  "_blank",
  "attributionsrc");

Agar diperhitungkan, metode ini harus dipanggil dalam waktu 5 detik setelah interaksi pengguna.

Daripada menambahkan attributionsrc saja, untuk gambar atau skrip, Anda dapat menentukan satu nilai URL:

<a href=... attributionsrc="https://a.example/register-source">Click me</a>

Dalam kasus JavaScript, jika Anda memberi nilai pada attributionsrc, pastikan untuk mengenkode URL tersebut jika berisi karakter khusus seperti = yang akan menyebabkan parameter tidak diuraikan dengan benar.

Lakukan encoding sebagai berikut:

const encodedUrl = encodeURIComponent(
  "https://adtech.example/attribution_source?ad_id=...");
window.open(
  "https://shoes.example/landing",
   "_blank",
   `attributionsrc=${encodedUrl}`);

attributionsrc juga dapat mengambil daftar URL yang dipisahkan spasi seperti yang diilustrasikan di sini dengan tag <a>:

<a href=... attributionsrc="https://a.example/register-source
  https://b.example/register-source">Click me</a>

atau seperti yang ada di sini menggunakan window.open().

window.open("...", "_blank", `attributionsrc=${encodedUrl1}
  attributionsrc=${encodedUrl2}`)

Dalam kasus tersebut, kedua URL akan menerima attributionsrc yang memenuhi syarat sumber navigasi permintaan (permintaan yang menyertakan header Attribution-Reporting-Eligible).

attributionsrc dengan atau tanpa nilai

Seperti yang Anda lihat sebelumnya, Anda dapat menentukan attributionsrc tanpa URL. Anda juga dapat menentukan URL tunggal. Selain itu, Anda dapat menggunakan daftar 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}.

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

Misalnya, jika Anda perlu mendaftarkan sumber untuk klik pada elemen anchor, Anda mungkin sebenarnya tidak mengontrol tujuan iklan; dalam hal ini, Anda perlu konfigurasi yang memungkinkan Anda mengirim header pendaftaran sumber sebagai respons terhadap permintaan yang terpisah dari navigasi, dan yang dapat Anda kontrol sepenuhnya. Menurut menentukan nilai eksplisit untuk attributionsrc, Anda menginstruksikan untuk membuat permintaan tambahan itu dan mengonfigurasi tujuannya.

Untuk mendaftarkan sumber atribusi untuk tampilan, Anda dapat menggunakan tag gambar atau skrip yang akan ditambahi atribut attributionsrc.

Atau, Anda dapat menggunakan JavaScript fetch() atau XMLHttpRequest().

Dengan gambar

<img attributionsrc
src="https://adtech.example/attribution_source?ad_id=...">

Dengan skrip

<script attributionsrc
  src="https://adtech.example/attribution_source?ad_id=..."></script>

Atau, Anda dapat menentukan nilai URL untuk attributionsrc dengan cara yang sama seperti untuk klik; yaitu, untuk gambar atau skrip , Anda dapat menetapkan URL attributionsrc atau URL seperti ini:

Dengan satu URL:

<img attributionsrc="https://adtech.example/attribution_source?ad_id=123">

Dengan daftar URL:

<img attributionsrc="https://a.example/register-source
  https://b.example/register-source">

Menggunakan fetch() atau XMLHttpRequest()

Kode ini secara efektif menyimulasikan fungsi permintaan HTML dengan attributionsrc:

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

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

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

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

Langkah 2: Tanggapi dengan header (klik dan penayangan)

Langkah berikutnya untuk klik dan tampilan adalah merespons dengan header Attribution-Reporting-Register-Source.

Tinjau kode contoh untuk mengetahui informasi selengkapnya.

Setelah menerima permintaan browser di server, tanggapi dan sertakan dalam respons header Attribution-Reporting-Register-Source.

res.set(
  "Attribution-Reporting-Register-Source",
  JSON.stringify({
    // Use source_event_id to map it to any granular information
    // you need at ad-serving time
    source_event_id: "412444888111012",
    destination: "https://advertiser.example",
    // Optional fields
    expiry: "604800",
    priority: "100",
    debug_key: "122939999"
  })
);

Setelah string dibuat, header Anda akan terlihat seperti ini:

{"source_event_id":"412444888111012","destination":"https://advertiser.example","expiry":"604800","priority":"100","debug_key":"122939999"}

Langkah berikutnya

Pelajari cara Mendaftarkan pemicu atribusi.