Menentukan data audiens

Pelajari cara menentukan audiens dengan membuat grup minat menggunakan Protected Audience API. Baca panduan developer untuk mengetahui siklus proses lengkap Protected Audience API, dan lihat penjelasan Protected Audience API untuk mengetahui proposal mendalam tentang cara browser mencatat grup minat.

Bukan developer? Lihat ringkasan Protected Audience API.

Grup minat Protected Audience API

Grup minat Protected Audience API mewakili sekelompok orang dengan minat yang sama, yang sesuai dengan daftar pemasaran ulang. Setiap grup minat Protected Audience API memiliki pemilik.

Pemilik grup minat bertindak sebagai pembeli dalam lelang iklan Protected Audience API. Keanggotaan grup minat disimpan oleh browser, di perangkat pengguna, dan tidak dibagikan kepada vendor browser atau orang lain.

Fungsi API

joinAdInterestGroup()

Platform sisi permintaan (DSP) pengiklan atau pengiklan itu sendiri memanggil navigator.joinAdInterestGroup() untuk meminta browser menambahkan grup minat ke daftar keanggotaan browser.

Asal konteks panggilan untuk joinAdInterestGroup() harus cocok dengan asal pemilik grup minat, sehingga joinAdInterestGroup() harus dipanggil dari iframe (misalnya, dari DSP) kecuali jika asal pemilik grup minat cocok dengan asal dokumen saat ini (misalnya, situs dengan grup minatnya sendiri).

joinAdInterestGroup() memerlukan izin dari:

Artinya, malicious.example tidak dapat memanggil joinAdInterestGroup() untuk grup minat yang dimiliki oleh dsp.example.com, tanpa dsp.example.com memberikan izin.

Izin dari situs yang dikunjungi

Izin dapat diberikan dari origin yang sama atau lintas origin. Secara default, izin diberikan untuk panggilan joinAdInterestGroup() dari origin yang sama dengan situs yang dikunjungi, (dengan kata lain, dari origin yang sama dengan frame tingkat teratas halaman saat ini).

Contoh penggunaan

Berikut adalah contoh cara menentukan grup minat dan meminta browser untuk bergabung ke grup tersebut.

const interestGroup = {
  owner: 'https://dsp.example',
  name: 'custom-bikes',
  biddingLogicUrl: ...,
  biddingWasmHelperUrl: ...,
  updateUrl: ...,
  trustedBiddingSignalsUrl: ...,
  trustedBiddingSignalsKeys: ['key1', 'key2'],
  userBiddingSignals: {...},
  ads: [bikeAd1, bikeAd2, bikeAd3],
  adComponents: [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2],
};

navigator.joinAdInterestGroup(interestGroup, 7 * kSecsPerDay);

Objek interestGroup yang diteruskan ke fungsi tidak boleh berukuran lebih dari 50 kiB, jika tidak, panggilan akan gagal. Parameter kedua menentukan durasi grup minat, dengan batas 30 hari. Panggilan berturut-turut akan menimpa nilai yang disimpan sebelumnya.

Properti wajib

Satu-satunya properti yang wajib ada untuk grup minat adalah owner dan name:

Properti Contoh Peran
owner https://dsp.example Asal pemilik grup minat.
name custom-bikes Nama grup minat.

Properti opsional

Properti lainnya bersifat opsional:

biddingLogicUrl1, 2
Contoh: https://dsp.example/bid/custom-bikes/bid.js
Peran: URL untuk menjalankan JavaScript bidding di worklet.
biddingWasmHelperUrl1, 2
Contoh: https://dsp.example/bid/custom-bikes/bid.wasm
Peran: URL untuk kode WebAssembly yang didorong dari biddingLogicUrl.
updateUrl2
Contoh: https://dsp.example/bid/custom-bikes/update
Role: URL yang menampilkan JSON untuk memperbarui atribut grup minat. (Lihat Memperbarui data audiens dan memuat ulang iklan.)
trustedBiddingSignalsUrl2
Contoh: https://dsp.example/trusted/bidding-signals
Peran: URL Dasar untuk permintaan nilai kunci ke layanan Nilai Kunci tepercaya bidder.
trustedBiddingSignalsKeys
Contoh: ['key1', 'key2' ...]
Peran: Kunci untuk permintaan ke layanan Key/Value tepercaya.
userBiddingSignals
Contoh: {...}
Peran: Metadata tambahan yang dapat digunakan pemilik selama bidding.
ads1
Contoh: [bikeAd1, bikeAd2, bikeAd3]
Peran: Iklan yang mungkin dirender untuk grup minat ini.
adComponents
Contoh: [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2]
Peran: Komponen untuk iklan yang terdiri dari beberapa bagian.

1 Properti biddingLogicUrl dan ads bersifat opsional, tetapi diperlukan untuk berpartisipasi dalam lelang. Mungkin ada kasus penggunaan untuk membuat grup minat tanpa properti ini: misalnya, pemilik grup minat mungkin ingin menambahkan browser ke grup minat untuk kampanye yang belum berjalan, atau untuk penggunaan lain di masa mendatang, atau mereka mungkin untuk sementara kehabisan anggaran iklan.

2 Dalam penerapan Protected Audience API saat ini, biddingLogicUrl, biddingWasmHelperUrl, updateUrl, dan trustedBiddingSignalsUrl harus memiliki origin yang sama dengan pemilik. Hal ini mungkin bukan batasan jangka panjang, dan URL ads serta adComponents tidak memiliki batasan tersebut.

Menentukan iklan untuk grup minat

Objek ads dan adComponents menyertakan URL untuk materi iklan dan, secara opsional, metadata arbitrer yang dapat digunakan pada waktu bidding.

Contoh:

{
  renderUrl: 'https://cdn.example/.../bikeAd1.html',
  metadata: bikeAd1metadata // optional
}

leaveAdInterestGroup()

Pemilik grup minat dapat meminta agar browser dihapus dari grup minat. Browser menghapus grup minat dari daftar keanggotaannya.

navigator.leaveAdInterestGroup({
  owner: 'https://dsp.example',
  name: 'custom-bikes'
});

Jika pengguna kembali ke situs yang meminta browser untuk menambahkan grup minat, pemilik grup minat dapat memanggil fungsi navigator.leaveAdInterestGroup() untuk meminta browser menghapus grup minat.

Kode untuk iklan juga dapat memanggil fungsi ini untuk grup minatnya.

Pertanyaan umum (FAQ)

Berapa jumlah maksimum grup minat per pemilik grup untuk satu pengguna?

Chrome mengizinkan hingga 1.000 grup minat per pemilik, dan hingga 1.000 pemilik grup minat. Batas ini dimaksudkan sebagai panduan, bukan untuk dicapai dalam operasi reguler.

Bagaimana cara memaksimalkan iklan grup minat yang memenuhi nilai minimum k-anonimitas?

Seperti yang dijelaskan dalam penjelasan publik, karena satu grup minat dapat membawa beberapa kemungkinan iklan yang mungkin ditampilkan, grup tersebut akan memiliki peluang untuk mengajukan ulang bid pada salah satu iklannya untuk bertindak sebagai "iklan pengganti" kapan saja pilihan yang paling disukainya berada di bawah nilai minimum. Artinya, iklan kecil khusus yang masih di bawah batas 𝑘-anonimitas masih dapat memilih untuk berpartisipasi dalam lelang, dan grup minatnya memiliki cara untuk kembali ke iklan yang lebih umum hingga iklan yang lebih khusus memiliki audiens yang cukup besar.

Dari perspektif taktis, Anda dapat mempertimbangkan hal berikut:

  • Agar iklan baru mulai ditampilkan, cukup mulai mengajukan bid dengannya jika Anda ingin iklan tersebut ditampilkan. Anda tidak perlu melakukan tindakan tambahan apa pun.
  • Anda dapat memiliki iklan pengganti yang digunakan saat iklan baru tidak 𝑘-anonim. Ada beberapa risiko bahwa iklan pengganti Anda sendiri tidak 𝑘-anonim, jadi Anda dapat mempertimbangkan untuk terkadang mengajukan bid dengan iklan pengganti sejak awal. Mungkin lakukan ini 1% dari waktu, misalnya, jika itu adalah tingkat yang baik untuk memastikan bahwa Anda mengharapkan penggantian tetap di atas nilai minimum.

Baru-baru ini ada diskusi tentang cara kerja lain, jadi jika Anda memiliki kasus penggunaan yang akan menimbulkan masalah bagi mekanisme ini, teruslah berpartisipasi dalam percakapan publik tentang cara peningkatan kualitas API.

Semua referensi Protected Audience API

Panduan referensi API tersedia:

Penjelasan Protected Audience API juga memberikan detail tentang dukungan dan batasan fitur.