Panduan developer untuk lelang iklan di perangkat guna menayangkan pemasaran ulang dan audiens kustom, tanpa pelacakan pihak ketiga lintas situs.
Untuk pengguna yang baru menggunakan Protected Audience API, baca ringkasan Protected Audience API untuk mendapatkan penjelasan umum tentang API ini.
Postingan ini ditulis bagi developer sebagai referensi teknis untuk iterasi terbaru Protected Audience API eksperimental. Tersedia demo deployment Protected Audience API dasar, begitu juga referensi API untuk pembeli dan penjual iklan.
Status penerapan
- Proposal Protected Audience API kini dipindahkan ke ketersediaan umum. Ajukan pertanyaan dan ikuti diskusi.
- Detail Status Protected Audience API untuk kemampuan yang tertunda berisi perubahan dan peningkatan kualitas Protected Audience API dan fitur.
- Status kedipan
- Status platform Chrome Protected Audience API: Khusus untuk Protected Audience API di Chrome.
- Status platform Chrome Ads API: Kumpulan API untuk memfasilitasi iklan: Protected Audience API, Topics, Fenced Frames, dan Attribution Reporting.
Agar mendapatkan notifikasi tentang perubahan status di API, bergabunglah ke milis untuk developer.
Apa itu Protected Audience API?
Protected Audience API adalah Privacy Sandbox API yang dirancang untuk menayangkan kasus penggunaan audiens kustom dan pemasaran ulang, yang dirancang agar tidak dapat digunakan oleh pihak ketiga untuk melacak perilaku penjelajahan pengguna di seluruh situs. API ini memungkinkan lelang di perangkat oleh browser, guna memilih iklan yang relevan untuk situs yang sebelumnya dikunjungi pengguna.
Protected Audience API adalah eksperimen pertama yang akan diterapkan di Chromium dalam kelompok proposal TURTLEDOVE.
Coba Protected Audience API
Referensi API yang tersedia
Dokumen ini berfungsi sebagai ringkasan Protected Audience API. Jika Anda mencari metode dan parameter API tertentu:
- Panduan pembeli untuk
joinAdInterestGroup()
dangenerateBid()
. - Panduan penjual untuk Protected Audience API
runAdAuction()
- Panduan pembeli untuk
reportWin()
dan panduan penjual untukreportResult()
- Memecahkan masalah Protected Audience API
Anda juga dapat membaca Praktik terbaik latensi lelang iklan Protected Audience API.
Demo Protected Audience API
Panduan deployment Protected Audience API dasar di seluruh situs pengiklan dan penayang tersedia di protected-audience-demo.web.app/.
Menguji dengan chrome://flags
atau tombol fitur
Anda dapat menguji Protected Audience API untuk satu pengguna di Chrome Beta 101.0.4951.26 dan yang lebih baru di desktop:
- Aktifkan
chrome://flags/#privacy-sandbox-ads-apis
. - Menetapkan tanda dari command line. Daftar lengkap tanda Protected Audience API yang tersedia dapat ditemukan di Penelusuran Kode Chromium.
Render iklan dalam iframe atau frame dengan fence
Iklan dapat dirender dalam <iframe>
atau <fencedframe>
, bergantung pada tanda yang ditetapkan.
Untuk menggunakan <fencedframe>
guna merender iklan:
--enable-features=InterestGroupStorage,AdInterestGroupAPI,Fledge,FencedFrames
Untuk menggunakan <iframe>
guna merender iklan:
--enable-features=InterestGroupStorage,AdInterestGroupAPI,Fledge,AllowURNsInIframes --disable-features=FencedFrames
Sertakan flag BiddingAndScoringDebugReportingAPI
untuk mengaktifkan
metode pelaporan kerugian/menang debug sementara.
Fitur yang didukung
Protected Audience API di belakang tombol fitur di Chromium adalah eksperimen pertama untuk menguji fitur Protected Audience API berikut:
- Grup minat: disimpan oleh browser, dengan metadata terkait untuk mengonfigurasi bidding dan rendering iklan.
- Bidding di perangkat oleh pembeli (DSP atau pengiklan): berdasarkan grup minat yang disimpan dan sinyal dari penjual.
- Pemilihan iklan di perangkat oleh penjual (SSP atau penayang): berdasarkan bid lelang dan metadata dari pembeli.
- Rendering iklan dalam versi Fenced Frames yang santai sementara: dengan akses dan logging jaringan yang diizinkan untuk rendering iklan.
Baca selengkapnya tentang dukungan dan batasan fitur di penjelasan Protected Audience API.
Izin grup minat
Default untuk penerapan Protected Audience API saat ini adalah mengizinkan panggilan
joinAdInterestGroup()
dari mana saja di halaman, bahkan dari iframe lintas domain.
Di masa mendatang, setelah pemilik situs memiliki waktu untuk memperbarui kebijakan izin iframe lintas domain, rencananya adalah melarang panggilan dari iframe lintas domain.
Layanan Kunci/Nilai
Untuk mendukung lelang iklan Protected Audience API, browser dapat mengakses layanan kunci/nilai untuk mengambil informasi real-time yang mendukung lelang iklan Protected Audience API. Informasi ini dapat digunakan dengan beberapa cara:
- Pembeli mungkin ingin menghitung sisa anggaran di kampanye iklan.
- Penjual mungkin diwajibkan untuk memeriksa materi iklan berdasarkan kebijakan penayang.
Kode layanan kunci/nilai Protected Audience API telah tersedia. Lihat postingan blog pengumuman untuk mengetahui pembaruan statusnya.
Untuk pengujian awal, model "Bring Your Own Server" diperkenalkan. Dalam jangka panjang, teknologi iklan harus menggunakan layanan Kunci/Nilai Protected Audience API open source yang berjalan di lingkungan eksekusi yang tepercaya.
Lihat postingan blog layanan Protected Audience API untuk mengetahui info terbaru terkait linimasa. Kami akan memberikan pemberitahuan penting bagi developer untuk memulai pengujian dan adopsi sebelum transisi ini berlangsung.
Mendeteksi dukungan fitur
Sebelum menggunakan API, periksa apakah API tersebut didukung oleh browser dan tersedia di dokumen:
'joinAdInterestGroup' in navigator &&
document.featurePolicy.allowsFeature('join-ad-interest-group') &&
document.featurePolicy.allowsFeature('run-ad-auction') ?
console.log('navigator.joinAdInterestGroup() is supported on this page') :
console.log('navigator.joinAdInterestGroup() is not supported on this page');
Bagaimana cara kerja Protected Audience API?
Dalam contoh ini, pengguna menjelajahi situs produsen sepeda kustom, lalu mengunjungi situs berita dan melihat iklan sepeda baru dari produsen sepeda tersebut.
Fitur Protected Audience API akan ditambahkan seiring waktu seiring progres penerapan.
1. Pengguna mengunjungi situs pengiklan
Bayangkan pengguna mengunjungi situs pembuat sepeda kustom (pengiklan) dalam contoh ini) dan menghabiskan waktu di halaman produk untuk sepeda baja buatan tangan. Tindakan ini memberi peluang pemasaran ulang kepada produsen sepeda.
2. Browser pengguna diminta untuk menambahkan grup minat
Platform sisi permintaan (DSP) pengiklan (atau pengiklan itu sendiri) memanggil
navigator.joinAdInterestGroup()
untuk meminta browser menambahkan grup minat
ke daftar grup tempat browser menjadi anggota.
Dalam contoh ini, grup diberi nama custom-bikes
, dan pemiliknya adalah dsp.example
. Pemilik grup minat (dalam hal ini, DSP) akan menjadi 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.
- Baca penjelasan Protected Audience API: Grup Minat Mencatat Browser.
- Baca panduan API: pembeli dan DSP, pelajari cara
joinAdInterestGroup()
dan menghasilkan bid.
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
}
Bagaimana cara pembeli mengajukan bid?
generateBid()
dipanggil untuk setiap grup minat tempat browser menjadi anggotanya—jika pemilik grup minat diundang untuk melakukan bidding.
Baca dokumentasi developer generatedBid()
.
3. Pengguna mengunjungi situs yang menjual ruang iklan
Kemudian, pengguna mengunjungi situs yang menjual ruang iklan, dalam contoh ini situs berita. Situs memiliki inventaris iklan, yang dijual secara terprogram dengan bidding real-time.
4. Lelang iklan berjalan di browser
Lelang iklan kemungkinan akan dijalankan oleh penyedia sisi suplai (SSP) penayang, atau penayang itu sendiri. Tujuan lelang adalah memilih iklan yang paling sesuai untuk satu slot iklan yang tersedia di halaman saat ini. Lelang ini mempertimbangkan grup minat yang menjadi anggota browser, beserta data dari pembeli dan penjual ruang iklan dari layanan Kunci/Nilai.
- Baca penjelasan Protected Audience API: Penjual Menjalankan Lelang di Perangkat
- Baca panduan API: penjual dapat mempelajari lebih lanjut
runAdAuction()
dan praktik terbaik latensi lelang iklan.
5. Penjual dan pembeli yang berpartisipasi meminta data real-time dari layanan Kunci/Nilai
Selama lelang iklan, penjual dapat meminta data real-time tentang materi iklan
tertentu dengan membuat permintaan ke layanan Kunci/Nilai mereka.
Penjual dapat meminta informasi ini selama
runAdAuction()
oleh properti trustedScoringSignalsUrl
,
beserta kunci dari properti renderUrl
dari semua entri di kolom ads
dan adComponents
dari semua grup minat dalam lelang.
Pembeli dapat meminta data real-time dari layanan Kunci/Nilai menggunakan
properti trustedBiddingSignalsUrl
dan trustedBiddingSignalsKeys
dari
argumen grup minat yang diteruskan ke navigator.joinAdInterestGroup()
.
Saat runAdAuction()
dipanggil, browser akan membuat permintaan ke setiap
server tepercaya pembeli iklan. URL untuk permintaan akan terlihat seperti ini:
https://kv-service.example/getvalues?hostname=publisher.example&keys=key1,key2
- URL dasar berasal dari
trustedBiddingSignalsUrl
. hostname
disediakan oleh browser.- Nilai
keys
diambil daritrustedBiddingSignalsKeys
.
Respons terhadap permintaan ini adalah objek JSON yang memberikan nilai untuk setiap kunci.
- Baca penjelasan Protected Audience API: Mengambil Data Real-Time dari layanan Kunci/Nilai Protected Audience API.
- Baca menjadikan open source layanan Kunci/Nilai Protected Audience API.
6. Iklan pemenang ditampilkan
Promise yang ditampilkan oleh runAdAuction() di-resolve ke objek konfigurasi frame dengan fence (FencedFrameConfig
) saat flag resolveToConfig
ditetapkan ke true
di konfigurasi lelang. Konfigurasi frame digunakan oleh frame dengan fence untuk mengarahkan frame ke iklan pemenang, tetapi URL iklan tidak terlihat oleh penyemat frame.
Objek konfigurasi frame fence tersedia mulai dari M114. Untuk mengetahui informasi selengkapnya tentang objek FencedFrameConfig
, lihat artikel blog Chrome.
- Baca penjelasan Protected Audience API: browser merender iklan pemenang
7. Hasil lelang dilaporkan
Rencana jangka panjangnya adalah memungkinkan browser melaporkan hasil lelang untuk penjual dan pembeli menggunakan Private Aggregation API.
Sebagai mekanisme pelaporan tingkat peristiwa sementara, kode yang menerapkan
reportResult()
untuk penjual, dan reportWin()
untuk bidder yang menang, dapat
memanggil fungsi sendReportTo()
. Proses ini memerlukan satu argumen: string
yang mewakili URL yang diambil setelah lelang selesai, yang mengenkode
informasi tingkat peristiwa yang akan dilaporkan.
- Baca panduan API: pelajari pelaporan penjual dan pembeli
8. Klik iklan dilaporkan
Klik pada iklan yang dirender dalam frame dengan fence dilaporkan. Untuk mempelajari lebih lanjut cara kerjanya, lihat Pelaporan Iklan Frame dengan Fence.
Apa perbedaan antara Protected Audience API dan TURTLEDOVE?
Protected Audience API adalah eksperimen pertama yang akan diterapkan di Chromium dalam kelompok proposal TURTLEDOVE.
Protected Audience API mengikuti prinsip umum TURTLEDOVE. Sebagian iklan online didasarkan untuk menampilkan iklan kepada orang yang berpotensi tertarik dan pernah berinteraksi dengan pengiklan atau jaringan iklan. Secara historis, cara ini telah dilakukan pengiklan untuk mengenali orang tertentu saat menjelajahi situs web, yang merupakan masalah privasi inti pada web saat ini.
Upaya TURTLEDOVE adalah menawarkan API baru untuk mengatasi kasus penggunaan ini sekaligus menawarkan beberapa kemajuan privasi utama:
- Browser, bukan pengiklan, yang menyimpan informasi tentang hal yang menurut pengiklan diminati seseorang.
- Pengiklan dapat menayangkan iklan berdasarkan minat, tetapi tidak dapat menggabungkan minat tersebut dengan informasi lain tentang seseorang—khususnya, siapa mereka atau halaman apa yang mereka kunjungi.
Protected Audience API berkembang dari TURTLEDOVE dan kumpulan proposal terkait untuk modifikasi agar dapat melayani developer yang akan menggunakan API dengan lebih baik:
- Di SPARROW: Criteo mengusulkan penambahan model layanan ("Gatekeeper") yang berjalan di trusted execution environment (TEE). Protected Audience API mencakup penggunaan TEE yang lebih terbatas, untuk pencarian data real-time dan pelaporan gabungan.
- Proposal TERN dan Magnite dari NextRoll PARRROT menjelaskan berbagai peran yang dimiliki pembeli dan penjual dalam lelang di perangkat. Alur bidding/penskoran iklan Protected Audience API didasarkan pada pekerjaan ini.
- Modifikasi TURTLEDOVE Berbasis hasil dan Tingkat produk RTB House meningkatkan kemampuan model anonimitas dan personalisasi lelang di perangkat
- ParaKEET adalah proposal Microsoft untuk layanan iklan mirip TURTLEDOVE yang mengandalkan server proxy yang berjalan di TEE antara browser dan penyedia teknologi iklan, untuk menganonimisasi permintaan iklan dan menerapkan properti privasi. Protected Audience API belum menerapkan model proxy ini. Kami akan menyelaraskan JavaScript API untuk ParaKEET dan Protected Audience API, guna mendukung upaya mendatang untuk lebih menggabungkan fitur terbaik dari kedua proposal tersebut.
Protected Audience API belum mencegah jaringan iklan situs mempelajari iklan mana yang dilihat pengguna. Kami berharap dapat memodifikasi API agar menjadi lebih pribadi dari waktu ke waktu.
Dapatkah Topics API digunakan dengan Protected Audience API?
Ya. Topik yang diamati untuk pengguna saat ini, yang disediakan oleh Topics API, dapat digunakan sebagai informasi kontekstual oleh penjual atau bidder. Topik dapat disertakan dalam properti berikut:
auctionSignals
, properti objek konfigurasi lelang yang diteruskan kenavigator.runAdAuction()
userBiddingSignals
, properti objek konfigurasi grup minat yang diteruskan kenavigator.joinAdInterestGroup()
Konfigurasi browser yang tersedia
Pengguna dapat menyesuaikan partisipasi mereka untuk uji coba Privacy Sandbox di Chrome dengan
mengaktifkan atau menonaktifkan setelan tingkat teratas di
chrome://settings/adPrivacy
.
Selama pengujian awal, pengguna akan dapat menggunakan setelan Privacy Sandbox tingkat tinggi ini untuk memilih tidak menggunakan Protected Audience API. Chrome berencana mengizinkan pengguna untuk melihat dan mengelola daftar grup minat yang telah ditambahkan ke seluruh situs web yang telah mereka kunjungi. Seperti teknologi Privacy Sandbox itu sendiri, setelan pengguna dapat berkembang dengan masukan dari pengguna, badan pengatur, dan lainnya.
Kami akan terus mengupdate setelan yang tersedia di Chrome berdasarkan pengujian dan masukan. Di masa mendatang, kami berencana menawarkan setelan yang lebih terperinci untuk mengelola Protected Audience API dan data terkait.
Pemanggil API tidak dapat mengakses keanggotaan grup saat pengguna menjelajah dalam mode Samaran, dan keanggotaan akan dihapus saat pengguna menghapus data situs mereka.
Apakah worklet Protected Audience di-cache oleh browser?
Resource yang berisi worklet Protected Audience—pembuatan bid dan worklet pelaporan pembeli, serta worklet pelaporan dan skor iklan penjual—di-cache oleh browser. Anda dapat menggunakan header Cache-Control
untuk mengontrol perilaku penyimpanan dalam cache.
Berinteraksi dan memberikan masukan
Mendapatkan dukungan
Untuk mengajukan pertanyaan dan mendapatkan dukungan terkait implementasi Anda, demo, atau dokumentasi:
- GitHub: Baca penjelasan, ajukan pertanyaan, dan ikuti diskusi.
- Demo: Ajukan masalah di repositori kode demo.
- Dukungan developer: Ajukan pertanyaan dan ikuti diskusi di repo Dukungan Developer Privacy Sandbox. Pilih template masalah untuk Protected Audience API.
- Implementasi Chrome: untuk bug atau masalah terkait penerapan Protected Audience API Chrome, Anda dapat melihat masalah yang ada atau melaporkan masalah baru.
Untuk pertanyaan lebih umum tentang memenuhi kebutuhan Anda dengan Protected Audience API, ajukan masalah di repositori API. Anda juga dapat mendiskusikan kasus penggunaan industri dalam Improve Web Advertising Business Group W3C.
Gunakan formulir masukan Privacy Sandbox untuk memberikan masukan secara pribadi dengan tim Chrome di luar forum publik.
Memilih tidak ikut
Ingin memilih tidak menggunakan Protected Audience API? Pelajari cara memblokir akses ke Protected Audience API, sebagai pemilik situs atau pengguna perorangan.
Mendapatkan info terbaru
- Untuk notifikasi perubahan status API, bergabunglah dengan milis untuk developer.
- Untuk mengikuti semua diskusi berkelanjutan tentang API dengan cermat, klik tombol Watch di halaman API di GitHub. Untuk melakukannya, Anda harus memiliki atau membuat akun GitHub.
- Untuk mendapatkan info terbaru secara keseluruhan tentang Privacy Sandbox, berlangganan feed RSS [Progress in the Privacy Sandbox].
- Bergabung ke panggilan terjadwal untuk Protected Audience API (setiap minggu kedua). Siapa saja dapat bergabung—untuk berpartisipasi, pertama-tama pastikan untuk bergabung dengan WICG. Anda dapat berpartisipasi secara aktif, atau sekadar mendengarkan masukan.