Kepada siapa artikel ini?
Postingan ini merupakan referensi teknis untuk iterasi terkini Protected Audience API eksperimental.
Protected Audience API merupakan ringkasan proposal yang tidak terlalu teknis, dan juga memiliki glosarium.
Demo Protected Audience memberikan panduan deployment FLEDGE dasar.
Video demo Protected Audience menjelaskan cara kerja kode demo, dan menunjukkan cara menggunakan Chrome DevTools untuk proses debug Protected Audience.
Apa itu Protected Audience?
Protected Audience API adalah proposal Privacy Sandbox untuk menayangkan kasus penggunaan pemasaran ulang dan audiens kustom, 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, untuk memilih iklan yang relevan untuk situs yang sebelumnya telah dikunjungi pengguna.
Protected Audience adalah eksperimen pertama yang diterapkan di Chromium dalam kelompok TURTLEDOVE.
Diagram di bawah memberikan ringkasan siklus proses FLEDGE:
![Ilustrasi yang memberikan ringkasan setiap tahap siklus proses FLEDGE](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/blog/fledgeblog1.png?authuser=7&hl=id)
Bagaimana cara mencoba Protected Audience?
Demo Protected Audience
Panduan deployment Protected Audience dasar di seluruh situs pengiklan dan penayang tersedia di protected-audience-demo.web.app.
Video demo menjelaskan cara kerja kode demo, dan menunjukkan cara menggunakan Chrome DevTools untuk proses debug Protected Audience.
Ikuti uji coba origin Protected Audience
Uji coba origin Relevansi dan Pengukuran Privacy Sandbox telah tersedia di Chrome Beta 101.0.4951.26 dan yang lebih baru di desktop untuk API Protected Audience, Topics, dan Attribution Reporting.
Untuk berpartisipasi, daftar untuk token uji coba origin.
Setelah berhasil mendaftar dalam uji coba, Anda dapat mencoba Protected Audience JavaScript API di halaman yang menyediakan token uji coba yang valid: misalnya, untuk meminta browser bergabung ke satu atau beberapa grup minat, lalu menjalankan lelang iklan agar dapat memilih dan menampilkan iklan.
Demo Protected Audience memberikan contoh dasar deployment Protected Audience secara menyeluruh.
Berikan token uji coba untuk setiap halaman tempat Anda ingin menjalankan kode Protected Audience API:
Sebagai tag meta di <head>:
<meta http-equiv="origin-trial" content="TOKEN_GOES_HERE">
Sebagai header HTTP:
Origin-Trial: TOKEN_GOES_HERE
Dengan menyediakan token secara terprogram:
const otMeta = document.createElement('meta'); otMeta.httpEquiv = 'origin-trial'; otMeta.content = 'TOKEN_GOES_HERE'; document.head.append(otMeta);
iframe yang menjalankan kode Protected Audience—seperti panggilan navigator.joinAdInterestGroup()
oleh pemilik grup minat—harus memberikan token yang cocok dengan asalnya.
Detail Uji Coba Origin Protected Audience Pertama yang Diusulkan memberikan detail selengkapnya tentang sasaran uji coba pertama dan menjelaskan fitur apa saja yang didukung.
Uji API ini
Anda dapat menguji Protected Audience untuk satu pengguna di Chrome Beta 101.0.4951.26 dan yang lebih baru di desktop:
- Dengan mengaktifkan semua API privasi iklan di bagian
chrome://settings/adPrivacy
- Dengan mengatur flag dari command line.
Merender 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 tanda BiddingAndScoringDebugReportingAPI
untuk mengaktifkan metode pelaporan kalah/menang debug sementara.
Menjalankan Chromium dengan tanda menjelaskan cara menyetel tanda saat menjalankan Chrome dan browser berbasis Chromium lainnya dari command line. Daftar lengkap tanda Protected Audience tersedia dari Chromium Code Search.
Fitur apa yang didukung di Chrome versi terbaru?
Protected Audience tersedia di balik tombol fitur di Chromium sebagai eksperimen pertama untuk menguji fitur proposal Protected Audience 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 untuk sementara waktu: dengan akses jaringan dan logging yang diizinkan untuk rendering iklan.
Penjelasan API memberikan detail selengkapnya tentang dukungan dan batasan fitur.
Izin grup minat
Default dalam penerapan Protected Audience saat ini adalah mengizinkan panggilan joinAdInterestGroup()
dari
mana saja dalam halaman, bahkan dari iframe lintas domain. Di masa mendatang, setelah pemilik situs memiliki waktu untuk menyesuaikan kebijakan izin iframe lintas domain, rencananya adalah melarang panggilan dari iframe lintas-domain, seperti yang dijelaskan dalam penjelasan.
Layanan Kunci/Nilai
Sebagai bagian dari lelang iklan Protected Audience, browser dapat mengakses layanan kunci/nilai yang menampilkan key-value pair sederhana untuk memberikan informasi kepada pembeli iklan, seperti sisa anggaran kampanye. Proposal Protected Audience mewajibkan server ini agar "tidak melakukan logging tingkat peristiwa dan tidak memiliki efek samping lain berdasarkan permintaan ini".
Kode layanan Kunci/Nilai Protected Audience kini tersedia di repositori GitHub Privacy Sandbox. Layanan ini dapat digunakan oleh developer Chrome dan Android. Lihat postingan blog pengumuman untuk pembaruan status. Pelajari layanan Kunci/Nilai Protected Audience lebih lanjut dari penjelasan API dan penjelasan model kepercayaan.
Untuk pengujian awal, model "Bring Your Own Server" digunakan. Dalam jangka panjang, teknologi iklan harus menggunakan layanan Kunci/Nilai Protected Audience open source yang berjalan di lingkungan eksekusi tepercaya untuk mengambil data real-time.
Untuk memastikan ekosistem memiliki waktu yang cukup untuk melakukan pengujian, kami tidak mengharapkan penggunaan layanan Kunci/Nilai atau TEE open source sampai beberapa saat setelah penggunaan cookie pihak ketiga tidak digunakan lagi. Kami akan memberikan pemberitahuan penting bagi developer untuk memulai pengujian dan penerapan sebelum transisi ini dilakukan.
Dukungan fitur deteksi
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 memilih tidak menggunakan Protected Audience?
Anda dapat memblokir akses ke Protected Audience API sebagai pemilik situs atau sebagai pengguna perorangan.
Bagaimana situs dapat mengontrol akses?
Protected Audience pada akhirnya akan mewajibkan situs untuk menetapkan Kebijakan Izin agar fungsi Protected Audience tersedia. Hal ini akan membantu memastikan bahwa pihak ketiga arbitrer tidak dapat menggunakan API tanpa sepengetahuan situs. Namun, untuk memfasilitasi pengujian selama uji coba origin pertama, persyaratan ini dibebaskan secara default. Situs yang ingin secara eksplisit menonaktifkan fungsi Protected Audience selama periode pengujian dapat menggunakan Kebijakan Izin yang relevan untuk memblokir akses.
Ada dua kebijakan izin Protected Audience yang dapat ditetapkan secara terpisah:
join-ad-interest-group
mengaktifkan/menonaktifkan fungsi untuk menambahkan browser ke grup minatrun-ad-auction
mengaktifkan/menonaktifkan fungsi untuk menjalankan lelang di perangkat
Akses ke Protected Audience API dapat dinonaktifkan sepenuhnya dalam konteks pihak pertama dengan menentukan kebijakan izin berikut di header respons HTTP:
Permissions-Policy: join-ad-interest-group=(), run-ad-auction=()
Anda dapat menonaktifkan penggunaan API dalam iframe dengan menambahkan atribut allow
berikut ke elemen iframe:
<iframe src="https://example.com" allow="join-ad-interest-group 'none'; run-ad-auction 'none'"></iframe>
Bagian Kebijakan Izin Uji Coba Origin Protected Audience Pertama yang Diusulkan memberikan detail selengkapnya.
Pilihan tidak ikut dari pengguna
Pengguna dapat memblokir akses ke Protected Audience API dan fitur Privacy Sandbox lainnya menggunakan salah satu mekanisme berikut:
- Nonaktifkan uji coba Privacy Sandbox di Setelan Chrome: Setelan >
Keamanan dan privasi > Privacy Sandbox. Aplikasi ini juga dapat diakses di
chrome://settings/adPrivacy
. - Nonaktifkan cookie pihak ketiga di Setelan Chrome: Setelan > Keamanan dan privasi.
- Tetapkan Cookie dan data situs lainnya ke "Blokir cookie pihak ketiga" atau "Blokir semua cookie"
dari
chrome://settings/cookies
. - Menggunakan mode Samaran.
Penjelasan Protected Audience memberikan detail selengkapnya tentang elemen desain API dan menjelaskan cara API tersebut berupaya memenuhi sasaran privasi.
Men-debug worklet Protected Audience
Mulai Chrome Canary 98.0.4718.0, Anda dapat men-debug worklet Protected Audience dalam Chrome DevTools.
Langkah pertama adalah menetapkan titik henti sementara melalui kategori baru di panel Titik henti sementara Pemroses Peristiwa di panel Sumber.
![Screenshot
DevTools di Chrome Canary, yang menandai panel Event Listener Breakpoints di panel Sources.
Awal Fase Bidding Bidder dipilih di bagian Worklet Lelang Iklan.](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/blog/screenshot-devtools-f272e7a201571.png?authuser=7&hl=id)
Saat titik henti sementara terpicu, eksekusi akan dijeda sebelum pernyataan pertama di level atas skrip worklet. Anda dapat menggunakan titik henti sementara atau perintah langkah reguler untuk membuka fungsi bidding/skor/pelaporan itu sendiri.
Skrip worklet aktif juga akan muncul di panel Threads.
![Screenshot
DevTools di Chrome Canary, yang menandai panel Threads di panel Source, yang menampilkan skrip worklet
saat ini yang telah dijeda.](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/blog/screenshot-devtools-chr-49c6b80c72f4a.png?authuser=7&hl=id)
Karena beberapa worklet dapat berjalan secara paralel, beberapa thread dapat berakhir dalam status "dijeda" di sana; Anda dapat menggunakan daftar thread untuk beralih antar-thread, dan melanjutkan atau memeriksanya lebih dekat sesuai dengan kebutuhan.
Mengamati peristiwa Protected Audience
Dari panel Application di Chrome DevTools, Anda dapat mengamati grup minat Protected Audience dan peristiwa lelang.
Jika Anda mengunjungi situs belanja demo Protected Audience
di browser yang mengaktifkan Protected Audience, DevTools akan menampilkan informasi tentang peristiwa join
.
![Panel Aplikasi DevTools di Chrome Canary, yang menampilkan informasi tentang peristiwa bergabung grup minat Protected Audience.](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/blog/the-devtools-applicati-c7168a6021513.png?authuser=7&hl=id)
Sekarang, jika Anda mengunjungi situs penayang demo Protected Audience
di browser yang mengaktifkan Protected Audience, DevTools akan menampilkan informasi tentang peristiwa bid
dan win
.
![Panel
Aplikasi DevTools di Chrome Canary, menunjukkan informasi tentang bid lelang Protected Audience dan
peristiwa menang.](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/blog/the-devtools-applicati-33f68c41ad519.png?authuser=7&hl=id)
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.
1. Pengguna mengunjungi situs pengiklan
![Ilustrasi yang menampilkan
seseorang yang mengunjungi situs produsen sepeda kustom melalui browser di laptopnya.](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/blog/illustration-showing-p-7cef347843604.png?authuser=7&hl=id)
Bayangkan pengguna mengunjungi situs produsen sepeda kustom (pengiklan dalam contoh ini) dan menghabiskan waktu di halaman produk untuk sepeda baja buatan tangan. Hal ini memberikan peluang pemasaran ulang kepada produsen sepeda.
2. Browser pengguna diminta untuk menambahkan grup minat
![Ilustrasi yang menampilkan seseorang melihat situs di browser di laptopnya. Kode JavaScript joinAdInterestGroup() berjalan di browser.](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/blog/illustration-showing-per-8856a700d6569.png?authuser=7&hl=id)
Bagian penjelasan: Grup Minat Data Browser
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 kasus ini, DSP) akan menjadi
pembeli dalam lelang iklan yang dijelaskan pada langkah 4.
Keanggotaan grup minat disimpan oleh browser, di perangkat pengguna, dan tidak dibagikan kepada
vendor browser atau orang lain.
joinAdInterestGroup()
memerlukan izin dari:
- Situs yang dikunjungi
- Pemilik grup minat
Misalnya: malicious.example
tidak boleh memanggil
joinAdInterestGroup()
dengan dsp.example
sebagai pemilik tanpa izin
dsp.example
.
Izin dari situs yang sedang dikunjungi
Asal yang sama: Secara default, izin diberikan secara implisit untuk panggilan joinAdInterestGroup()
dari asal yang sama dengan situs yang dikunjungi, yaitu dari asal yang sama dengan frame tingkat atas halaman saat ini. Situs dapat menggunakan header kebijakan izin
join-ad-interest-group
Protected Audience untuk menonaktifkan panggilan joinAdInterestGroup()
.
Lintas origin: Memanggil joinAdInterestGroup()
dari origin yang berbeda dengan halaman
saat ini hanya dapat berhasil jika situs yang dikunjungi telah menetapkan kebijakan izin yang mengizinkan panggilan ke
joinAdInterestGroup()
dari iframe lintas origin.
Izin dari pemilik grup minat
Izin pemilik grup minat secara implisit diberikan dengan memanggil joinAdInterestGroup()
dari iframe dengan asal yang sama dengan pemilik grup minat. Misalnya, iframe dsp.example
dapat memanggil joinAdInterestGroup()
untuk grup minat yang dimiliki oleh dsp.example
.
Proposalnya adalah agar joinAdInterestGroup()
dapat berjalan di halaman atau iframe di domain pemilik, atau
didelegasikan ke domain lain yang disediakan menggunakan daftar di URL .well-known
.
Menggunakan navigator.joinAdInterestGroup()
Berikut adalah contoh penggunaan API:
const interestGroup = {
owner: 'https://dsp.example',
name: 'custom-bikes',
biddingLogicUrl: ...,
biddingWasmHelperUrl: ...,
dailyUpdateUrl: ...,
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 pada 30
hari. Panggilan yang berurutan akan menimpa nilai yang disimpan sebelumnya.
Properti grup minat
Properti | Wajib | Contoh | Peran |
---|---|---|---|
owner |
Wajib | 'https://dsp.example' |
Asal pemilik grup minat. |
name |
Wajib | 'custom-bikes' |
Nama grup minat. |
biddingLogicUrl ** |
Opsional* | 'https://dsp.example/bid/custom-bikes/bid.js' |
URL untuk JavaScript bidding berjalan di worklet. |
biddingWasmHelperUrl ** |
Opsional* | 'https://dsp.example/bid/custom-bikes/bid.wasm' |
URL untuk kode WebAssembly yang dijalankan dari biddingLogicUrl . |
dailyUpdateUrl ** |
Opsional | 'https://dsp.example/bid/custom-bikes/update' |
URL yang menampilkan JSON untuk memperbarui atribut grup minat. (Lihat Memperbarui grup minat.) |
trustedBiddingSignalsUrl ** |
Opsional | 'https://dsp.example/trusted/bidding-signals' |
URL dasar untuk permintaan nilai kunci ke server tepercaya bidder. |
trustedBiddingSignalsKeys |
Opsional | ['key1', 'key2' ...] |
Kunci untuk permintaan ke server tepercaya nilai kunci. |
userBiddingSignals |
Opsional | {...} |
Metadata tambahan yang dapat digunakan pemilik selama bidding. |
ads |
Opsional* | [bikeAd1, bikeAd2, bikeAd3] |
Iklan yang mungkin ditampilkan untuk grup minat ini. |
adComponents |
Opsional | [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2] |
Komponen untuk iklan yang terdiri dari beberapa bagian. |
* Semua properti bersifat opsional kecuali owner
dan name
. 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 beberapa
penggunaan lainnya pada masa mendatang, atau mereka mungkin telah kehabisan anggaran iklan untuk sementara.
** URL biddingLogicUrl
, biddingWasmHelperUrl
, dailyUpdateUrl
, dan trustedBiddingSignalsUrl
harus memiliki asal yang sama dengan pemilik. URL ads
dan adComponents
tidak memiliki batasan tersebut.
Memperbarui atribut grup minat
dailyUpdateUrl
menentukan server web yang menampilkan JSON yang menentukan properti grup minat,
sesuai dengan objek grup minat yang diteruskan ke navigator.joinAdInterestGroup()
. Tindakan ini
menyediakan mekanisme bagi pemilik grup untuk memperbarui atribut
grup minat secara berkala. Dalam implementasi saat ini,
atribut berikut dapat diubah:
biddingLogicUrl
biddingWasmHelperUrl
trustedBiddingSignalsUrl
trustedBiddingSignalsKeys
ads
priority
Setiap kolom yang tidak ditentukan dalam JSON tidak akan ditimpa—hanya kolom yang ditentukan dalam JSON yang akan diperbarui—sedangkan memanggil navigator.joinAdInterestGroup()
akan menimpa grup minat yang ada.
Update adalah upaya terbaik, dan bisa gagal dalam kondisi berikut:
- Waktu tunggu permintaan jaringan habis (saat ini 30 detik).
- Kegagalan jaringan lainnya.
- Kegagalan penguraian JSON.
Update juga dapat dibatalkan jika terlalu banyak waktu yang berdampingan dihabiskan untuk mengupdate, meskipun hal ini tidak memaksakan pembatasan kapasitas pada update yang dibatalkan (sisanya). Update dibatasi kapasitasnya hingga satu per hari. Update yang gagal karena error jaringan akan dicoba lagi setelah satu jam, dan update yang gagal karena koneksi internet terputus akan segera dicoba lagi saat terhubung kembali.
Pembaruan manual
Pembaruan pada grup minat yang dimiliki oleh asal frame saat ini dapat dipicu secara manual melalui
navigator.updateAdInterestGroups()
. Pembatasan kapasitas mencegah update terjadi terlalu sering:
panggilan berulang ke navigator.updateAdInterestGroups()
tidak akan melakukan apa pun hingga periode
batas kapasitas (saat ini satu hari) telah berlalu. Batas kapasitas akan direset jika
navigator.joinAdInterestGroup()
dipanggil lagi untuk owner
dan name
grup minat yang sama.
Update otomatis
Semua grup minat yang dimuat untuk lelang akan diperbarui secara otomatis setelah lelang selesai,
tunduk pada batas kapasitas yang sama seperti pembaruan manual. Untuk setiap pemilik dengan setidaknya satu grup minat
yang berpartisipasi dalam lelang, seolah-olah navigator.updateAdInterestGroups()
dipanggil dari
iframe yang asalnya cocok dengan pemilik 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
}
Bagaimana cara pembeli melakukan bid?
Skrip di biddingLogicUrl
yang disediakan oleh pemilik grup minat harus menyertakan fungsi
generateBid()
. Saat penjual ruang iklan memanggil navigator.runAdAuction()
, fungsi generatedBid()
dipanggil sekali untuk setiap grup minat yang menjadi anggota browser, jika pemilik grup
minat diundang untuk mengajukan bid. Dengan kata lain, generateBid()
dipanggil satu kali untuk setiap iklan
kandidat. Penjual menyediakan properti decisionLogicUrl
di parameter konfigurasi lelang yang diteruskan
ke navigator.runAdAuction()
. Kode di URL ini harus menyertakan fungsi scoreAd()
, yang
dijalankan untuk setiap bidder dalam lelang, untuk menilai setiap bid yang ditampilkan oleh generateBid()
.
Skrip di biddingLogicUrl
yang disediakan oleh pembeli ruang iklan harus menyertakan fungsi generateBid()
.
Fungsi ini dipanggil satu kali untuk setiap iklan kandidat. runAdAuction()
memeriksa setiap iklan satu per satu, bersama dengan bid dan metadata terkait, lalu menetapkan
skor keinginan numerik pada iklan.
generateBid(interestGroup, auctionSignals, perBuyerSignals,
trustedBiddingSignals, browserSignals) {
...
return {
ad: adObject,
bid: bidValue,
render: renderUrl,
adComponents: [adComponentRenderUrl1, ...]
};
}
generateBid()
menggunakan argumen berikut:
interestGroup
Objek yang diteruskan kejoinAdInterestGroup()
oleh pembeli iklan. (Grup minat dapat diperbarui melaluidailyUpdateUrl
.)auctionSignals
Properti argumen konfigurasi lelang yang diteruskan kenavigator.runAdAuction()
oleh penjual ruang iklan. Hal ini memberikan informasi tentang konteks halaman (seperti ukuran iklan dan ID penayang), jenis lelang (harga pertama atau harga kedua), dan metadata lainnya.perBuyerSignals
Seperti halnyaauctionSignals
, properti argumen konfigurasi lelang yang diteruskan kenavigator.runAdAuction()
oleh penjual. Tindakan ini dapat memberikan sinyal kontekstual dari server pembeli tentang halaman tersebut, jika penjual adalah SSP yang melakukan panggilan bidding real-time ke server pembeli dan menyalurkan respons kembali, atau jika halaman penayang menghubungi server pembeli secara langsung. Jika demikian, pembeli dapat memeriksa tanda tangan kriptografi dari sinyal tersebut di dalam generateBid() sebagai perlindungan terhadap modifikasi tidak sah.trustedBiddingSignals
Objek yang kuncinya adalahtrustedBiddingSignalsKeys
untuk grup minat, dan yang nilainya ditampilkan dalam permintaantrustedBiddingSignals
.browserSignals
Objek yang dibuat oleh browser, yang mungkin mencakup informasi tentang konteks halaman (sepertihostname
halaman saat ini, yang dapat dipalsukan oleh penjual) dan data untuk grup minat itu sendiri (seperti data saat grup tersebut sebelumnya memenangkan lelang, untuk memungkinkan pembatasan frekuensi di perangkat).
Objek browserSignals
memiliki properti berikut:
{
topWindowHostname: 'publisher.example',
seller: 'https://ssp.example',
joinCount: 3,
bidCount: 17,
prevWins: [[time1,ad1],[time2,ad2],...],
wasmHelper: ... /* WebAssembly.Module object based on interest group's biddingWasmHelperUrl. */
dataVersion: 1, /* Data-Version value from the buyer's Key/Value service response(s). */
}
Untuk menghitung nilai bid
, kode dalam generateBid()
dapat menggunakan properti parameter fungsi. Contoh:
function generateBid(interestGroup, auctionSignals, perBuyerSignals,
trustedBiddingSignals, browserSignals) {
return {
...
bid: auctionSignals.is_above_the_fold ? perBuyerSignals.atf_value : perBuyerSignals.btf_value,
...
}
}
generateBid()
menampilkan objek dengan empat properti:
ad
Metadata arbitrer tentang iklan, seperti informasi yang diharapkan penjual untuk mengetahui bid atau materi iklan ini. Penjual](/privacy-sandbox/resources/glosarium#ssp) menggunakan informasi ini dalam materi iklan keputusan dan lelangnya. Penjual menggunakan informasi ini dalam logika keputusannya dan lelang.bid
Bid numerik yang akan memasuki lelang. Penjual harus dapat membandingkan bid dari pembeli yang berbeda, sehingga bid harus dalam beberapa unit yang dipilih penjual (mis., "USD per seribu"). Jika bid nol atau negatif, grup minat ini tidak akan berpartisipasi dalam lelang penjual sama sekali. Dengan mekanisme ini, pembeli dapat menerapkan aturan pengiklan terkait tempat iklan mereka dapat atau tidak dapat ditampilkan.render
URL, atau daftar URL, yang akan digunakan untuk merender materi iklan jika bid ini memenangkan lelang. (Lihat Iklan yang Dibuat dari Beberapa Bagian di penjelasan API.) Nilai harus cocok denganrenderUrl
salah satu iklan yang ditentukan untuk grup minat.adComponents
Daftar opsional hingga 20 komponen untuk iklan yang terdiri dari beberapa bagian, yang diambil dari propertiadComponents
argumen grup minat yang diteruskan kenavigator.joinAdInterestGroup()
.
Meminta browser untuk keluar dari grup minat
Pemilik grup minat dapat meminta agar browser dihapus dari grup minat. Dengan kata lain, browser diminta untuk menghapus grup minat dari daftar yang menjadi anggotanya.
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.
3. Pengguna mengunjungi situs yang menjual ruang iklan
![Ilustrasi yang menampilkan seseorang mengunjungi situs berita melalui browser di laptopnya. Situs
memiliki slot iklan yang kosong.](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/blog/illustration-showing-per-113f3bd8c69da.png?authuser=7&hl=id)
Kemudian, pengguna mengunjungi situs yang menjual ruang iklan, dalam contoh ini situs berita. Situs tersebut memiliki inventaris iklan, yang dijual secara terprogram menggunakan bidding real-time.
4. Lelang iklan dijalankan di browser
![Ilustrasi yang menampilkan seseorang melihat situs berita di browser pada laptopnya. Lelang
iklan menggunakan Protected Audience API sedang berlangsung.](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/blog/illustration-showing-per-43194d760936b.png?authuser=7&hl=id)
Bagian penjelasan: Penjual Menjalankan Lelang di Perangkat
Lelang iklan kemungkinan akan dijalankan oleh SSP penayang atau penayang itu sendiri. Tujuan lelang ini adalah memilih iklan yang paling sesuai untuk satu slot iklan yang tersedia di halaman saat ini. Lelang ini memperhitungkan grup minat yang menjadi anggota browser, beserta data dari pembeli ruang iklan dan penjual dari Layanan Kunci/Nilai.
Penjual ruang iklan membuat permintaan ke browser pengguna untuk memulai lelang iklan dengan memanggil
navigator.runAdAuction()
.
Contoh:
const auctionConfig = {
seller: 'https://ssp.example',
decisionLogicUrl: ...,
trustedScoringSignalsUrl: ...,
interestGroupBuyers: ['https://dsp.example', 'https://buyer2.example', ...],
auctionSignals: {...},
sellerSignals: {...},
sellerTimeout: 100,
perBuyerSignals: {
'https://dsp.example': {...},
'https://another-buyer.example': {...},
...
},
perBuyerTimeouts: {
'https://dsp.example': 50,
'https://another-buyer.example': 200,
'*': 150,
...
},
componentAuctions: [
{
'seller': 'https://some-other-ssp.example',
'decisionLogicUrl': ...,
...
},
...
]
};
const auctionResultPromise = navigator.runAdAuction(auctionConfig);
runAdAuction()
menampilkan promise yang di-resolve ke URN (urn:uuid:<something>
) yang mewakili
hasil lelang iklan. Nilai ini hanya dapat didekode oleh browser saat diteruskan ke frame dengan fence
untuk rendering: halaman penayang tidak dapat memeriksa iklan pemenang.
Skrip decisionLogicUrl
mempertimbangkan setiap iklan, beserta bid dan
metadata terkaitnya, satu per satu, lalu menetapkan skor yang diinginkan secara numerik.
auctionConfig
properti
Properti | Wajib | Contoh | Peran |
---|---|---|---|
seller |
Wajib | 'https://ssp.example' |
Asal penjual. |
decisionLogicUrl |
Wajib | 'https://ssp.example/auction-decision-logic.js' |
URL untuk JavaScript worklet lelang. |
trustedScoringSignalsUrl |
Opsional | 'https://ssp.example/scoring-signals' |
URL server tepercaya penjual. |
interestGroupBuyers* |
Wajib | ['https://dsp.example', 'https://buyer2.example', ...] |
Asal semua pemilik grup minat yang diminta untuk mengajukan bid dalam lelang. |
auctionSignals |
Opsional | {...} |
Informasi penjual tentang konteks halaman, jenis lelang, dll. |
sellerSignals |
Opsional | {...} |
Informasi berdasarkan setelan penayang, membuat permintaan iklan kontekstual, dll. |
sellerTimeout |
Opsional | 100 |
Runtime maksimum (md) skrip scoreAd() penjual. |
perBuyerSignals |
Opsional | {'https://dsp.example': {...}, |
Sinyal kontekstual tentang halaman untuk setiap pembeli tertentu, dari server mereka. |
perBuyerTimeouts |
Opsional | 50 |
Runtime maksimum (md) skrip generateBid() pembeli tertentu. |
componentAuctions |
Opsional | [{'seller': 'https://www.some-other-ssp.com', |
Konfigurasi tambahan untuk lelang komponen. |
* Penjual dapat menentukan interestGroupBuyers: '*'
untuk mengizinkan semua grup minat mengajukan bid.
Iklan kemudian diterima atau ditolak berdasarkan kriteria selain penyertaan pemilik grup minat.
Misalnya, penjual dapat meninjau materi iklan untuk memastikan kepatuhannya terhadap kebijakannya.
** additionalBids
tidak didukung dalam penerapan Protected Audience saat ini. Baca bagian Peserta
Lelang dalam
penjelasan Protected Audience untuk mengetahui informasi selengkapnya.
Bagaimana iklan dipilih?
Kode di decisionLogicUrl
(properti objek konfigurasi lelang yang diteruskan ke
runAdAuction()
) harus menyertakan fungsi scoreAd()
. Ini dijalankan sekali untuk setiap iklan
guna menentukan keinginannya.
scoreAd(adMetadata, bid, auctionConfig, trustedScoringSignals, browserSignals) {
...
return desirabilityScoreForThisAd;
}
scoreAd()
menggunakan argumen berikut:
adMetadata
Metadata arbitrer yang disediakan oleh pembeli.bid
Nilai bid numerik.auctionConfig
Objek konfigurasi lelang yang diteruskan kenavigator.runAdAuction()
.trustedScoringSignals
Nilai yang diambil pada waktu lelang dari server tepercaya penjual, yang mewakili pendapat penjual tentang iklan tersebut.browserSignals
Objek yang dibuat oleh browser, termasuk informasi yang diketahui browser dan yang mungkin ingin diverifikasi oleh skrip lelang penjual:
{
topWindowHostname: 'publisher.example',
interestGroupOwner: 'https://dsp.example',
renderUrl: 'https://cdn.example/render',
adComponents: ['https://cdn.com/ad-component-1', ...],
biddingDurationMsec: 12,
dataVersion: 1 /* Data-Version value from the seller's Key/Value service response. */
}
Sebelum lelang dimulai, penjual menemukan iklan kontekstual terbaik untuk slot iklan yang tersedia. Bagian dari
logika scoreAd()
-nya adalah menolak iklan apa pun yang tidak dapat mengalahkan pemenang kontekstual.
5. Penjual dan pembeli yang berpartisipasi menerima data realtime dari layanan Kunci/Nilai
![Ilustrasi yang menampilkan seseorang melihat situs berita di browser pada laptopnya. Lelang
iklan yang menggunakan Protected Audience API sedang berlangsung, dengan peserta yang mendapatkan data dari layanan Kunci/Nilai.](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/blog/illustration-showing-per-d80920d3014fe.png?authuser=7&hl=id)
Bagian penjelasan: Mengambil Data Real-Time dari layanan Kunci/Nilai Protected Audience.
Selama lelang iklan, penjual ruang iklan dapat memperoleh data real time tentang materi iklan tertentu dengan
membuat permintaan ke layanan Kunci/Nilai menggunakan properti trustedScoringSignalsUrl
dari
argumen konfigurasi lelang yang diteruskan ke navigator.runAdAuction()
, bersama dengan kunci
dari properti renderUrl
dari semua entri di kolom ads
dan adComponents
dari semua
grup minat dalam lelang.
Demikian pula, pembeli ruang iklan 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 server tepercaya setiap pembeli iklan. URL
untuk permintaan tersebut mungkin 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.
6. Iklan pemenang akan ditampilkan
![Ilustrasi yang menampilkan seseorang melihat situs berita di browser pada laptopnya. Iklan
sepeda (diskon 20%) ditampilkan—dengan kunci di atasnya untuk menunjukkan bahwa iklan tersebut ditampilkan dalam
frame dengan fence.](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/blog/illustration-showing-per-54028ccec709f.png?authuser=7&hl=id)
Bagian penjelasan: Browser Render Iklan Pemenang
Seperti yang dijelaskan sebelumnya: promise yang ditampilkan oleh runAdAuction()
di-resolve menjadi URN
yang diteruskan ke frame dengan fence untuk rendering, dan situs menampilkan
iklan pemenang.
7. Hasil lelang dilaporkan
Bagian penjelasan: Pelaporan Tingkat Peristiwa (untuk saat ini)
Hasil laporan penjual
Bagian penjelasan: Pelaporan Penjual tentang Render
JavaScript penjual yang disediakan di decisionLogicUrl
(yang juga menyediakan scoreAd()
) dapat
menyertakan fungsi reportResult()
untuk melaporkan hasil lelang.
reportResult(auctionConfig, browserSignals) {
...
return signalsForWinner;
}
Argumen yang diteruskan ke fungsi ini adalah:
auctionConfig
Objek konfigurasi lelang yang diteruskan kenavigator.runAdAuction()
.browserSignals
Objek yang dibuat oleh browser yang memberikan informasi tentang lelang. Contoh:{ 'topWindowHostname': 'publisher.example', 'interestGroupOwner': 'https://dsp.example', 'renderUrl': 'https://cdn.example/url-of-winning-creative.wbn', 'bid:' <bidValue>, 'desirability': <winningAdScore> }
Nilai hasil fungsi ini digunakan sebagai argumen sellerSignals
untuk fungsi
reportWin()
bidder yang menang.
Hasil laporan bidder pemenang
Bagian penjelasan: Pelaporan Pembeli tentang Peristiwa Render dan Iklan
JavaScript bidder yang menang (yang juga menyediakan generateBid()
) dapat menyertakan
fungsi reportWin()
untuk melaporkan hasil lelang.
reportWin(auctionSignals, perBuyerSignals, sellerSignals, browserSignals) {
...
}
Argumen yang diteruskan ke fungsi ini adalah:
auctionSignals
danperBuyerSignals
Nilai yang sama diteruskan kegenerateBid()
untuk bidder pemenang.sellerSignals
Nilai hasilreportResult()
, yang memberi penjual kesempatan untuk meneruskan informasi kepada pembeli.browserSignals
Objek yang dibuat oleh browser yang memberikan informasi tentang lelang. Contoh:{ 'topWindowHostname': 'publisher.example', 'seller': 'https://ssp.example', 'interestGroupOwner': 'https://dsp.example', 'interestGroupName': 'custom-bikes', 'renderUrl': 'https://cdn.example/winning-creative.wbn', 'bid:' <bidValue> }
Penerapan pelaporan kalah/kemenangan sementara
Ada dua metode yang tersedia sementara di Chrome untuk pelaporan lelang:
forDebuggingOnly.reportAdAuctionLoss()
forDebuggingOnly.reportAdAuctionWin()
Masing-masing metode ini mengambil satu argumen: URL yang akan diambil setelah lelang selesai. Metode ini dapat
dipanggil beberapa kali, di scoreAd()
dan generateBid()
, dengan argumen URL yang berbeda.
Chrome hanya mengirim laporan kekalahan/kemenangan debug saat lelang berjalan hingga selesai. Jika lelang dibatalkan (misalnya, karena navigasi baru), tidak ada laporan yang akan dibuat.
Metode ini tersedia secara default di Chrome. Agar dapat menguji metode, aktifkan semua API privasi iklan di chrome://settings/adPrivacy
. Jika Anda menjalankan Chrome dengan tanda command line untuk mengaktifkan Protected Audience, Anda harus
mengaktifkan metode tersebut secara eksplisit dengan menyertakan tanda BiddingAndScoringDebugReportingAPI
. Jika flag tidak diaktifkan, metode akan tetap tersedia tetapi tidak melakukan apa pun.
8. Klik iklan dilaporkan
![Ilustrasi yang menampilkan
seseorang mengklik iklan sepeda, di dalam bingkai dengan pagar, di situs berita, dengan data
laporan yang diterima oleh penjual dan pembeli.](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/blog/illustration-showing-p-0332a635e2724.png?authuser=7&hl=id)
Klik pada iklan yang dirender dalam frame dengan fence dilaporkan. Untuk mempelajari cara kerjanya lebih lanjut, lihat Pelaporan Iklan Fenced Frames.
Diagram di bawah menguraikan setiap tahap lelang iklan Protected Audience:
![Ilustrasi yang memberikan ringkasan setiap tahap lelang iklan Protected Audience](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/blog/illustration-providing-fda431ab192ee.png?authuser=7&hl=id)
Apa perbedaan antara Protected Audience dan TURTLEDOVE?
Protected Audience adalah eksperimen pertama yang diterapkan di Chromium dalam kelompok proposal TURTLEDOVE.
Protected Audience mengikuti prinsip tingkat tinggi TURTLEDOVE. Sebagian iklan online didasarkan pada penayangan iklan kepada orang yang mungkin berminat dan pernah berinteraksi dengan pengiklan atau jaringan iklan. Sebelumnya, cara ini dilakukan karena pengiklan mengenali orang tertentu saat menjelajahi situs, yang merupakan masalah privasi inti dengan web saat ini.
Upaya TURTLEDOVE 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 menarik bagi 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 berkembang dari TURTLEDOVE dan sekumpulan proposal terkait untuk modifikasi guna memberikan layanan yang lebih baik kepada developer yang akan menggunakan API:
- Di SPARROW: Criteo mengusulkan penambahan model layanan ("Gatekeeper") yang berjalan di trusted execution environment (TEE). Protected Audience mencakup penggunaan TEE yang lebih terbatas untuk pencarian data real-time dan pelaporan gabungan.
- Proposal TERN NextRoll dan PARRROT Magnite menjelaskan berbagai peran yang dimiliki pembeli dan penjual dalam lelang di perangkat. Alur bidding/penskoran iklan Protected Audience didasarkan pada tugas ini.
- Modifikasi TURTLEDOVE Berbasis hasil dan Tingkat produk dari RTB House meningkatkan kualitas model anonimitas dan kemampuan personalisasi lelang di perangkat
- ParaKEET adalah proposal Microsoft untuk layanan iklan seperti TURTLEDOVE yang mengandalkan server proxy yang berjalan di TEE antara browser dan penyedia teknologi iklan, untuk menganonimkan permintaan iklan dan menerapkan properti privasi. Protected Audience belum menggunakan model proxy ini. Kami menyelaraskan JavaScript API untuk ParaKEET dan Protected Audience, guna mendukung upaya mendatang untuk lebih lanjut menggabungkan fitur terbaik dari kedua proposal tersebut.
Protected Audience belum mencegah jaringan iklan situs mempelajari iklan mana yang dilihat seseorang. Kami ingin memodifikasi API agar menjadi lebih pribadi seiring waktu.
Konfigurasi browser apa 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. Chrome berencana memungkinkan
pengguna melihat dan mengelola daftar grup minat yang telah mereka tambahkan di berbagai situs
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 memperbarui setelan yang tersedia di Chrome seiring dengan progres proposal Protected Audience, berdasarkan pengujian dan masukan. Di masa mendatang, kami berencana menawarkan setelan yang lebih terperinci untuk mengelola Protected Audience 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.
Berinteraksi dan memberikan masukan
- GitHub: Baca proposal, ajukan pertanyaan, dan ikuti diskusi.
- W3C: Diskusikan kasus penggunaan industri di Grup Bisnis Iklan Web Meningkatkan.
- Dukungan developer: Ajukan pertanyaan dan ikuti diskusi di repo Dukungan Developer Privacy Sandbox.
- Milis FLEDGE: fledge-api-announce memberikan pengumuman dan info terbaru tentang API.
- Gabung ke panggilan terjadwal untuk Protected Audience (setiap minggu kedua). Semua orang dapat bergabung. Untuk berpartisipasi, pastikan terlebih dahulu untuk bergabung dengan WICG. Anda bisa berpartisipasi secara aktif atau hanya mendengarkan saja!
- Gunakan formulir masukan Privacy Sandbox untuk memberikan masukan secara pribadi kepada tim Chrome di luar forum publik.
Dapatkan dukungan
Untuk mengajukan pertanyaan tentang penerapan Anda, tentang demo, atau tentang dokumentasi:
- Buka masalah baru di repositori privacy-sandbox-dev-support. Pastikan Anda memilih template masalah untuk Protected Audience.
- Ajukan masalah tentang repo kode demo di GitHub.
- Untuk pertanyaan yang lebih umum tentang cara memenuhi kasus penggunaan Anda dengan API, ajukan masalah pada repositori proposal.
Untuk bug dan masalah terkait penerapan Protected Audience API di Chrome: * Lihat masalah yang ada yang dilaporkan untuk API. * Sampaikan masalah baru di crbug.com/new.
Mendapatkan info terbaru
- Untuk mendapatkan notifikasi tentang perubahan status di API, bergabunglah ke milis untuk developer.
- Untuk mengikuti semua diskusi yang sedang berlangsung tentang API, klik tombol Tonton di halaman proposal di GitHub. Langkah ini mengharuskan Anda memiliki atau membuat akun GitHub.
- Untuk mendapatkan update keseluruhan di Privacy Sandbox, berlanggananlah feed RSS [Progress in the Privacy Sandbox].
Cari tahu selengkapnya
- Protected Audience API: ringkasan teknis proposal yang lebih sedikit.
- Demo Protected Audience: panduan deployment dasar Protected Audience.
- Video demo Protected Audience: menjelaskan kode demo dan menunjukkan cara menggunakan Chrome DevTools untuk proses debug Protected Audience.
- Penjelasan teknis Protected Audience API
- Memahami Privacy Sandbox
- Niat untuk membuat prototipe
Foto oleh Ray Hennessy di Unsplash.