Halaman ini diterjemahkan oleh Cloud Translation API.

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 mendetail tentang cara browser merekam 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:

Situs yang dikunjungi
Pemilik grup minat

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

Izin dari situs yang dikunjungi

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

Contoh penggunaan

Berikut adalah contoh cara pengguna dapat menentukan grup minat dan meminta browser untuk bergabung dengan grup.

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, yang dibatasi hingga 30 hari. Panggilan yang berurutan akan menimpa nilai yang disimpan sebelumnya.

Poin penting: Semua URL yang digunakan sebagai parameter untuk metode Protected Audience API harus berasal dari origin yang aman: semua resource harus ditayangkan melalui URL HTTPS. Cara menggunakan HTTPS untuk pengembangan lokal menjelaskan cara melakukannya saat menjalankan Protected Audience API secara lokal. Selain itu, biddingLogicUrl, decisionLogicUrl, dan trustedBiddingSignals memerlukan header respons HTTP X-Allow-FLEDGE: true.

Properti wajib

Satu-satunya properti yang diperlukan 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:

biddingLogicUrl^{1, 2}: Contoh: https://dsp.example/bid/custom-bikes/bid.js; Peran: URL untuk JavaScript bidding berjalan di worklet.
biddingWasmHelperUrl^{1, 2}: Contoh: https://dsp.example/bid/custom-bikes/bid.wasm; Peran: URL untuk kode WebAssembly yang didorong dari biddingLogicUrl.
updateUrl²: Contoh: https://dsp.example/bid/custom-bikes/update; Peran: URL yang menampilkan JSON untuk memperbarui atribut grup minat. (Lihat Memperbarui data audiens dan memuat ulang iklan.)
trustedBiddingSignalsUrl²: Contoh: https://dsp.example/trusted/bidding-signals; Peran: URL dasar untuk permintaan nilai kunci ke layanan Kunci/Nilai tepercaya bidder.
trustedBiddingSignalsKeys: Contoh: ['key1', 'key2' ...]; Peran: Kunci untuk permintaan ke layanan Kunci/Nilai tepercaya dengan nilai kunci.
userBiddingSignals: Contoh: {...}; Peran: Metadata tambahan yang dapat digunakan pemilik selama bidding.
ads¹: 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.

¹ Properti biddingLogicUrl dan ads bersifat opsional, tetapi wajib 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 lainnya pada masa mendatang, atau mereka mungkin telah kehabisan anggaran iklan untuk sementara.

² Dalam implementasi Protected Audience API saat ini, biddingLogicUrl, biddingWasmHelperUrl, updateUrl, dan trustedBiddingSignalsUrl harus memiliki origin yang sama sebagai 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, jika perlu, 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 tersebut.

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. Batasan ini dimaksudkan sebagai pagar pengaman, bukan untuk dimasuki dalam operasi rutin.

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

Sesuai catatan penjelasan publik, karena satu grup minat dapat berisi beberapa kemungkinan iklan yang mungkin ditampilkannya, grup ini akan memiliki peluang untuk mengajukan bid ulang terhadap salah satu iklannya agar bertindak sebagai "iklan penggantian" kapan saja pilihan yang paling disukainya berada di bawah nilai minimum. Artinya, iklan khusus yang berukuran kecil yang masih di bawah nilai minimum k-anonymity masih dapat memilih untuk berpartisipasi dalam lelang, dan grup minatnya dapat kembali menggunakan iklan yang lebih umum hingga iklan yang lebih spesifik memiliki audiens yang cukup besar.

Dari perspektif taktis, Anda dapat mempertimbangkan hal berikut:

Agar iklan baru mulai ditampilkan, cukup mulai ajukan bid dengan iklan tersebut jika Anda ingin iklan tersebut ditampilkan. Anda tidak perlu melakukan tindakan apa pun.
Anda dapat memiliki iklan pengganti yang digunakan saat iklan baru bukan k-anon. Ada beberapa risiko bahwa iklan penggantian itu sendiri tidak k-anon, jadi terkadang Anda dapat mempertimbangkan untuk hanya mengajukan bid dengan iklan penggantian. Mungkin lakukan hal ini 1%, misalnya, jika itu adalah tingkat yang baik untuk memastikan bahwa Anda memperkirakan penggantian akan tetap di atas batas.

Baru-baru ini, telah ada diskusi tentang cara lain agar API dapat berfungsi, jadi jika Anda memiliki beberapa kasus penggunaan yang menimbulkan masalah pada mekanisme ini, teruslah terlibat dalam percakapan publik tentang cara-cara untuk meningkatkan API.

Semua referensi Protected Audience API

以下是 API 参考指南：

Protected Audience API 开发者指南。
有关 Protected Audience 兴趣群体和出价生成的广告买方指南。
Protected Audience 广告竞价广告卖方指南。
关于报告竞价结果的指南
Protected Audience 广告竞价延迟时间方面的最佳实践
对 Protected Audience 进行问题排查

Protected Audience API 说明信息还详细介绍了功能支持和限制条件。