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 mendapatkan 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, sesuai dengan daftar pemasaran ulang. Setiap grup minat Protected Audience API memiliki pemilik.
Pemilik grup minat bertindak sebagai pembeli di 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 sedang dikunjungi
- Pemilik grup minat
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 atau lintas origin yang sama. 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 atas halaman saat ini).
Contoh penggunaan
Berikut adalah contoh cara 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.
Properti wajib
Satu-satunya properti yang diperlukan untuk grup minat adalah owner dan name:
| Properti | Contoh | Role |
|---|---|---|
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 JavaScript bidding yang berjalan 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 - Peran: URL yang menampilkan JSON untuk memperbarui atribut grup minat. (Lihat Memperbarui data audiens dan memperbarui iklan.)
trustedBiddingSignalsUrl2- 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 nilai kunci.
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 terdapat 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 mungkin telah kehabisan anggaran iklan untuk sementara.
2 Dalam penerapan Protected Audience API saat ini, biddingLogicUrl, biddingWasmHelperUrl, updateUrl, dan trustedBiddingSignalsUrl harus memiliki asal 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 browser untuk 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. Batasan ini dimaksudkan sebagai pengaman, yang tidak akan tercapai dalam operasi biasa.
Bagaimana cara memaksimalkan iklan grup minat yang memenuhi nilai minimum k-anon?
Seperti yang dijelaskan dalam penjelasan publik, karena satu grup minat dapat menayangkan beberapa kemungkinan iklan yang mungkin ditampilkan, grup tersebut akan memiliki kesempatan untuk mengajukan bid ulang salah satu iklannya untuk bertindak sebagai "iklan penggantian" setiap kali pilihan yang paling disukainya berada di bawah nilai minimum. Ini berarti bahwa iklan kecil khusus yang masih di bawah nilai minimum k-anonymity masih dapat memilih untuk berpartisipasi dalam lelang, dan grup minatnya memiliki cara untuk kembali menjadi 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 ajukan bid dengan iklan tersebut jika Anda ingin menampilkan iklan. Anda tidak perlu melakukan apa pun lagi.
- Anda dapat memiliki iklan penggantian yang digunakan saat iklan baru bukan iklan k-anon. Ada beberapa risiko iklan penggantian itu sendiri tidak menjadi k-anon, jadi sejak awal Anda dapat mempertimbangkan untuk hanya mengajukan bid dengan iklan penggantian. Mungkin lakukan hal ini 1% saja, misalnya, jika ini adalah tingkat yang baik untuk memastikan Anda mengharapkan penggantian tetap melebihi batas.
Baru-baru ini telah ada diskusi tentang cara lain untuk bekerja, jadi jika Anda memiliki beberapa kasus penggunaan yang dapat menimbulkan masalah bagi mekanisme ini, teruslah terlibat dalam diskusi publik tentang cara meningkatkan API.
Semua referensi Protected Audience API
Panduan referensi API tersedia:
- Panduan developer untuk Protected Audience API.
- Panduan pembeli iklan untuk grup minat dan pembuatan bid Protected Audience.
- Panduan penjual iklan untuk lelang iklan Protected Audience.
- Panduan melaporkan hasil lelang
- Praktik terbaik untuk latensi lelang iklan Protected Audience
- Memecahkan Masalah Protected Audience
Penjelasan Protected Audience API juga memberikan detail tentang dukungan dan batasan fitur.