Panduan developer FLEDGE API

Untuk siapa artikel ini?

Postingan ini adalah referensi teknis untuk iterasi Protected Audience API eksperimental saat ini.

Apa yang dimaksud dengan 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 akan diterapkan di Chromium dalam proposal dari keluarga TURTLEDOVE.

Diagram di bawah memberikan ringkasan siklus proses FLEDGE:

Ilustrasi yang memberikan ringkasan setiap tahap siklus proses FLEDGE
Siklus proses FLEDGE.

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.

Ikut serta dalam 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 Protected Audience, Topics, dan Attribution Reporting API.

Untuk berpartisipasi, daftar untuk mendapatkan token uji coba origin.

Setelah berhasil mendaftar ke uji coba, Anda dapat mencoba Protected Audience JavaScript API di halaman yang menyediakan token uji coba yang valid: misalnya, untuk meminta browser bergabung dengan satu atau beberapa grup minat, lalu menjalankan lelang iklan untuk memilih dan menampilkan iklan.

Demo Protected Audience memberikan contoh dasar deployment Protected Audience 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 memberikan 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 yang didukung.

Menguji 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 menetapkan flag dari command line.

Merender iklan dalam iframe atau bingkai berpagar

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 kemenangan/kegagalan debug sementara.

Menjalankan Chromium dengan flag menjelaskan cara menetapkan flag 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 flag fitur di Chromium sebagai eksperimen pertama untuk menguji fitur berikut dari proposal Protected Audience:

  • 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 dan sinyal yang disimpan 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 dilonggarkan sementara: dengan akses jaringan dan logging yang diizinkan untuk rendering iklan.

Penjelasan API memberikan detail selengkapnya tentang dukungan dan batasan fitur.

Izin grup minat

Setelan default dalam penerapan Protected Audience saat ini adalah mengizinkan pemanggilan joinAdInterestGroup() dari mana saja di halaman, bahkan dari iframe lintas-domain. Di masa mendatang, setelah pemilik situs memiliki waktu untuk menyesuaikan kebijakan izin iframe lintas-domain, rencananya adalah untuk melarang panggilan dari iframe lintas-domain, seperti yang dijelaskan dalam penjelasan.

Layanan Nilai/Kunci

Sebagai bagian dari lelang iklan Protected Audience, browser dapat mengakses layanan nilai kunci yang menampilkan pasangan nilai kunci sederhana untuk memberikan informasi kepada pembeli iklan, seperti sisa anggaran kampanye. Proposal Protected Audience mewajibkan bahwa server ini "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 mengetahui pembaruan status. Pelajari lebih lanjut layanan Kunci/Nilai Protected Audience dari penjelasan API dan penjelasan model kepercayaan.

Untuk pengujian awal, model "Bawa Server Anda Sendiri" digunakan. Dalam jangka panjang, teknologi iklan harus menggunakan layanan Nilai Kunci Protected Audience open source yang berjalan di trusted execution environment untuk mengambil data real-time.

Untuk memastikan ekosistem memiliki waktu yang cukup untuk melakukan pengujian, kami tidak akan mewajibkan penggunaan layanan Key/Value atau TEE open source hingga beberapa waktu setelah penghentian penggunaan cookie pihak ketiga. Kami akan memberikan pemberitahuan yang cukup kepada developer untuk memulai pengujian dan penerapan sebelum transisi ini terjadi.

Mendeteksi dukungan fitur

Sebelum menggunakan API, periksa apakah API didukung oleh browser dan tersedia dalam 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 untuk tidak menggunakan Protected Audience?

Anda dapat memblokir akses ke Protected Audience API sebagai pemilik situs, atau sebagai pengguna individual.

Bagaimana cara situs 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 pengetahuan situs. Namun, untuk memfasilitasi pengujian selama uji coba origin pertama, persyaratan ini dihapus secara default. Situs yang ingin menonaktifkan fungsi Protected Audience secara eksplisit 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 minat
  • run-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 di 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 dengan menggunakan salah satu mekanisme berikut:

  • Nonaktifkan uji coba Privacy Sandbox di Setelan Chrome: Setelan > Keamanan dan privasi > Privacy Sandbox. 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.
  • Gunakan mode Samaran.

Penjelasan Protected Audience memberikan detail selengkapnya tentang elemen desain API dan menjelaskan cara API 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 Titik Henti Sementara Pemroses Peristiwa di panel Sumber. Awal Fase Bidding Bidder dipilih di bagian Worklet Lelang Iklan.

Saat titik henti sementara dipicu, eksekusi dijeda sebelum pernyataan pertama di tingkat atas skrip worklet. Anda dapat menggunakan titik henti sementara reguler atau perintah langkah untuk membuka fungsi bidding/penskoran/pelaporan itu sendiri.

Skrip worklet live juga akan muncul di panel Thread.

Screenshot DevTools di Chrome Canary, yang menandai panel Thread di panel Sumber, yang menampilkan skrip worklet saat ini yang telah dijeda.

Karena beberapa worklet dapat berjalan secara paralel, beberapa thread mungkin berakhir dalam status "dijeda" di sana; Anda dapat menggunakan daftar thread untuk beralih antar-thread, dan melanjutkan atau memeriksanya lebih cermat sesuai kebutuhan.

Mengamati peristiwa Protected Audience

Dari panel Aplikasi di Chrome DevTools, Anda dapat mengamati grup minat dan peristiwa lelang Protected Audience.

Jika Anda mengunjungi situs belanja demo Protected Audience di browser dengan Protected Audience diaktifkan, DevTools akan menampilkan informasi tentang peristiwa join.

Panel Aplikasi DevTools di Chrome Canary, yang menampilkan informasi tentang peristiwa bergabung grup minat Protected Audience.

Sekarang, jika Anda mengunjungi situs penayang demo Protected Audience di browser dengan Protected Audience diaktifkan, DevTools akan menampilkan informasi tentang peristiwa bid dan win.

Panel Aplikasi DevTools di Chrome Canary, yang menampilkan informasi tentang peristiwa lelang dan kemenangan Protected Audience.

Bagaimana cara kerja Protected Audience API?

Dalam contoh ini, pengguna menjelajahi situs pembuat sepeda kustom, lalu mengunjungi situs berita dan melihat iklan sepeda baru dari pembuat sepeda.

1. Pengguna mengunjungi situs pengiklan

Ilustrasi yang menampilkan seseorang yang mengunjungi situs produsen sepeda kustom di browser di laptopnya.

Bayangkan pengguna mengunjungi situs pembuat 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 yang sedang melihat situs di browser di laptopnya. Kode joinAdInterestGroup() JavaScript sedang berjalan di browser.

Bagian penjelasan: Browser Merekam Grup Minat

Platform sisi permintaan (DSP) pengiklan (atau pengiklan itu sendiri) memanggil navigator.joinAdInterestGroup() untuk meminta browser menambahkan grup minat ke daftar grup yang menjadi anggota browser. 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 yang dijelaskan di 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 dikunjungi

Origin yang sama: Secara default, izin secara implisit diberikan untuk panggilan joinAdInterestGroup() dari origin yang sama dengan situs yang dikunjungi, yaitu dari origin yang sama dengan frame tingkat teratas halaman saat ini. Situs dapat menggunakan perintah join-ad-interest-group header kebijakan izin 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 diberikan secara implisit 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 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 lebih dari 50 kiB. Jika tidak, panggilan akan gagal. Parameter kedua menentukan durasi grup minat, yang dibatasi hingga 30 hari. Panggilan berturut-turut 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 yang dijalankan di worklet.
biddingWasmHelperUrl** Opsional* 'https://dsp.example/bid/custom-bikes/bid.wasm' URL untuk kode WebAssembly yang didorong 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 dirender 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 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 beberapa penggunaan mendatang, atau mereka mungkin 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, yang sesuai dengan objek grup minat yang diteruskan ke navigator.joinAdInterestGroup(). Hal ini memberikan mekanisme bagi pemilik grup untuk memperbarui atribut grup minat secara berkala. Dalam penerapan 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 diperbarui—sedangkan memanggil navigator.joinAdInterestGroup() akan menimpa grup minat yang ada.

Update adalah upaya terbaik, dan dapat gagal dalam kondisi berikut:

  • Waktu tunggu permintaan jaringan (saat ini 30 detik).
  • Kegagalan jaringan lainnya.
  • Kegagalan penguraian JSON.

Update juga dapat dibatalkan jika terlalu banyak waktu berturut-turut yang dihabiskan untuk mengupdate, meskipun hal ini tidak memberlakukan pembatasan kapasitas pada update yang dibatalkan (sisa). Update dibatasi kapasitasnya hingga maksimal 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 melakukan apa pun hingga periode pembatasan kapasitas (saat ini satu hari) berlalu. Batas kapasitas akan direset jika navigator.joinAdInterestGroup() dipanggil lagi untuk grup minat yang sama owner dan name.

Update otomatis

Semua grup minat yang dimuat untuk lelang 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, 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?

Skrip di biddingLogicUrl yang disediakan oleh pemilik grup minat harus menyertakan fungsi generateBid(). Saat penjual ruang iklan memanggil navigator.runAdAuction(), fungsi generatedBid() akan dipanggil satu kali untuk setiap grup minat yang menjadi anggota browser, jika pemilik grup minat diundang untuk mengajukan bid. Dengan kata lain, generateBid() dipanggil sekali untuk setiap iklan kandidat. Penjual menyediakan properti decisionLogicUrl pada 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, beserta bid dan metadata terkait, lalu menetapkan skor keinginan numerik untuk iklan tersebut.

generateBid(interestGroup, auctionSignals, perBuyerSignals,
    trustedBiddingSignals, browserSignals) {
  ...
  return {
    ad: adObject,
    bid: bidValue,
    render: renderUrl,
    adComponents: [adComponentRenderUrl1, ...]
   };
}

generateBid() menggunakan argumen berikut:

  • interestGroup
    Objek yang diteruskan ke joinAdInterestGroup() oleh pembeli iklan. (Grup minat dapat diperbarui melalui dailyUpdateUrl.)

  • auctionSignals
    Properti argumen auction config yang diteruskan ke navigator.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 auctionSignals, properti argumen konfigurasi lelang yang diteruskan ke navigator.runAdAuction() oleh penjual. Hal ini dapat memberikan sinyal kontekstual dari server pembeli tentang halaman, 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 kriptografis sinyal tersebut di dalam generateBid() sebagai perlindungan terhadap modifikasi tidak sah.

  • trustedBiddingSignals
    Objek yang kuncinya adalah trustedBiddingSignalsKeys untuk grup minat, dan nilainya ditampilkan dalam permintaan trustedBiddingSignals.

  • browserSignals
    Objek yang dibuat oleh browser, yang mungkin menyertakan informasi tentang konteks halaman (seperti hostname halaman saat ini, yang dapat dipalsukan oleh penjual) dan data untuk grup minat itu sendiri (seperti catatan waktu grup sebelumnya memenangkan lelang, untuk mengizinkan 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 di 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 tentang bid atau materi iklan ini. Penjual](/resources/glossary#ssp) menggunakan informasi ini dalam lelang dan materi iklan keputusannya. Penjual menggunakan informasi ini dalam logika lelang dan keputusannya.

  • 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 (misalnya "USD per ribu"). Jika bid nol atau negatif, grup minat ini tidak akan berpartisipasi sama sekali dalam lelang penjual. Dengan mekanisme ini, pembeli dapat menerapkan aturan pengiklan untuk tempat iklan mereka dapat atau tidak dapat muncul.

  • render
    URL, atau daftar URL, yang akan digunakan untuk merender materi iklan jika bid ini memenangkan lelang. (Lihat Iklan yang Terdiri dari Beberapa Bagian dalam penjelasan API.) Nilai harus cocok dengan renderUrl dari salah satu iklan yang ditentukan untuk grup minat.

  • adComponents
    Daftar opsional hingga 20 komponen untuk iklan yang terdiri dari beberapa bagian, yang diambil dari properti adComponents dari argumen grup minat yang diteruskan ke navigator.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 grup 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. Kode untuk iklan juga dapat memanggil fungsi ini untuk grup minatnya.

3. Pengguna mengunjungi situs yang menjual ruang iklan

Ilustrasi yang menampilkan seseorang yang mengunjungi situs berita di browser di laptopnya. Situs memiliki slot iklan kosong.

Kemudian, pengguna mengunjungi situs yang menjual ruang iklan, dalam contoh ini situs berita. Situs ini memiliki inventaris iklan, yang dijual secara terprogram menggunakan bidding real-time.

4. Lelang iklan dijalankan di browser

Ilustrasi yang menampilkan seseorang yang sedang melihat situs berita di browser di laptopnya. Lelang iklan menggunakan Protected Audience API sedang berlangsung.

Bagian penjelasan: Penjual Menjalankan Lelang di Perangkat

Lelang iklan kemungkinan dijalankan oleh 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 memperhitungkan grup minat yang diikuti browser, bersama dengan data dari pembeli dan penjual ruang iklan 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 me-resolve ke URN (urn:uuid:<something>) yang mewakili hasil lelang iklan. Ini hanya dapat didekode oleh browser saat diteruskan ke bingkai berpagar untuk rendering: halaman penayang tidak dapat memeriksa iklan pemenang.

Skrip decisionLogicUrl mempertimbangkan setiap iklan, beserta bid dan metadata terkait, satu per satu, lalu menetapkan skor keinginan 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': {...},
  'https://another-buyer.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',
  'decisionLogicUrl': ..., ...},
  ...]		 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 mengonfirmasi kepatuhannya terhadap kebijakan mereka.

** 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 satu kali untuk setiap iklan untuk menentukan keinginannya.

scoreAd(adMetadata, bid, auctionConfig, trustedScoringSignals, browserSignals) {
  ...
  return desirabilityScoreForThisAd;
}

scoreAd() menggunakan argumen berikut:

  • adMetadata
    Metadata arbitrer yang diberikan oleh pembeli.
  • bid
    Nilai bid numerik.
  • auctionConfig
    Objek konfigurasi lelang yang diteruskan ke navigator.runAdAuction().
  • trustedScoringSignals
    Nilai yang diambil pada waktu lelang dari server tepercaya penjual, yang mewakili pendapat penjual tentang iklan.
  • 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 akan 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 real-time dari layanan Nilai Kunci

Ilustrasi yang menampilkan seseorang yang sedang melihat situs berita di browser di laptopnya. Lelang iklan menggunakan Protected Audience API sedang berlangsung, dengan peserta mendapatkan data dari layanan Kunci/Nilai.

Bagian penjelasan: Mengambil Data Real-Time dari layanan Nilai Kunci Protected Audience.

Selama lelang iklan, penjual ruang iklan dapat mendapatkan data real-time tentang materi iklan tertentu dengan membuat permintaan ke layanan Nilai Kunci menggunakan properti trustedScoringSignalsUrl dari argumen konfigurasi lelang yang diteruskan ke navigator.runAdAuction(), beserta 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 Nilai Kunci 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 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 dari trustedBiddingSignalsKeys.

Respons terhadap permintaan ini adalah objek JSON yang memberikan nilai untuk setiap kunci.

6. Iklan pemenang ditampilkan

Ilustrasi yang menampilkan seseorang yang sedang melihat situs berita di browser di laptopnya. Iklan untuk sepeda (diskon 20%) ditampilkan—dengan gembok di atas untuk menunjukkan bahwa iklan ditampilkan dalam bingkai berpagar.

Bagian penjelasan: Browser Merender Iklan Pemenang

Seperti yang dijelaskan sebelumnya: promise yang ditampilkan oleh runAdAuction() di-resolve ke URN yang diteruskan ke bingkai berpagar 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 di 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 ke navigator.runAdAuction().

  • browserSignals
    Objek yang dibuat oleh browser yang memberikan informasi tentang lelang. Misalnya:

    {
  'topWindowHostname': 'publisher.example',
  'interestGroupOwner': 'https://dsp.example',
  'renderUrl': 'https://cdn.example/url-of-winning-creative.wbn',
  'bid:' <bidValue>,
  'desirability': <winningAdScore>
}

Nilai yang ditampilkan fungsi ini digunakan sebagai argumen sellerSignals untuk fungsi reportWin() bidder pemenang.

Hasil laporan bidder pemenang

Bagian penjelasan: Pelaporan Pembeli tentang Peristiwa Render dan Iklan

JavaScript bidder pemenang (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 dan perBuyerSignals
    Nilai yang sama diteruskan ke generateBid() untuk bidder pemenang.
  • sellerSignals
    Nilai yang ditampilkan reportResult(), yang memberi penjual kesempatan untuk meneruskan informasi kepada pembeli.

  • browserSignals
    Objek yang dibuat oleh browser yang memberikan informasi tentang lelang. Misalnya:

    {
  '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 kekalahan/kemenangan sementara

Ada dua metode yang tersedia untuk sementara di Chrome untuk pelaporan lelang:

  • forDebuggingOnly.reportAdAuctionLoss()
  • forDebuggingOnly.reportAdAuctionWin()

Setiap metode ini menggunakan satu argumen: URL yang akan diambil setelah lelang selesai. Fungsi ini dapat dipanggil beberapa kali, baik di scoreAd() maupun generateBid(), dengan argumen URL yang berbeda.

Chrome hanya mengirimkan laporan debug kalah/menang 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 bagian chrome://settings/adPrivacy. Jika menjalankan Chrome dengan flag command line untuk mengaktifkan Protected Audience, Anda harus mengaktifkan metode secara eksplisit dengan menyertakan flag 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 berpagar, di situs berita, dengan data laporan yang dikirim ke penjual dan pembeli.

Klik pada iklan yang dirender dalam bingkai berpagar akan dilaporkan. Untuk mempelajari lebih lanjut cara kerjanya, lihat Pelaporan Iklan Bingkai Pagar.


Diagram di bawah ini menguraikan setiap tahap lelang iklan Protected Audience:

Ilustrasi yang memberikan ringkasan setiap tahap lelang iklan Protected Audience


Apa perbedaan antara Protected Audience dan TURTLEDOVE?

Protected Audience adalah eksperimen pertama yang akan diterapkan di Chromium dalam proposal keluarga TURTLEDOVE.

Protected Audience mengikuti prinsip tingkat tinggi TURTLEDOVE. Beberapa iklan online didasarkan pada penayangan iklan kepada orang yang berpotensi tertarik yang sebelumnya telah berinteraksi dengan pengiklan atau jaringan iklan. Secara historis, hal ini berhasil dilakukan dengan pengiklan mengenali orang tertentu saat mereka menjelajahi situs, yang merupakan masalah privasi inti dengan web saat ini.

Upaya TURTLEDOVE adalah menawarkan API baru untuk mengatasi kasus penggunaan ini sekaligus menawarkan beberapa kemajuan privasi utama:

  • Browser, bukan pengiklan, menyimpan informasi tentang minat seseorang menurut pengiklan.
  • Pengiklan dapat menayangkan iklan berdasarkan minat, tetapi tidak dapat menggabungkan minat tersebut dengan informasi lain tentang seseorang — khususnya, siapa dia atau halaman apa yang dia kunjungi.

Protected Audience berkembang dari TURTLEDOVE dan kumpulan proposal terkait untuk modifikasi agar dapat lebih melayani developer yang akan menggunakan API:

  • Di SPARROW: Criteo mengusulkan penambahan model layanan ("Gatekeeper") yang berjalan di trusted execution environment (TEE). Protected Audience menyertakan 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 pekerjaan ini.
  • Modifikasi TURTLEDOVE Berbasis hasil dan Tingkat produk RTB House meningkatkan 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 mengadopsi model proxy ini. Kami menyelaraskan API JavaScript untuk PARAKEET dan Protected Audience, untuk mendukung pekerjaan mendatang guna menggabungkan lebih lanjut fitur terbaik dari kedua proposal tersebut.

Protected Audience belum mencegah jaringan iklan situs mempelajari iklan mana yang dilihat seseorang. Kami berharap dapat mengubah API agar menjadi lebih pribadi dari waktu ke 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 mengizinkan pengguna melihat dan mengelola daftar grup minat tempat mereka dimasukkan di seluruh situs web yang telah mereka kunjungi. Seperti halnya teknologi Privacy Sandbox itu sendiri, setelan pengguna dapat berkembang dengan masukan dari pengguna, regulator, dan lainnya.

Kami akan terus memperbarui setelan yang tersedia di Chrome seiring progres proposal Protected Audience, berdasarkan pengujian dan masukan. Di masa mendatang, kami berencana untuk 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

Mendapatkan dukungan

Untuk mengajukan pertanyaan tentang penerapan Anda, demo, atau dokumentasi:

Untuk bug dan masalah terkait penerapan Protected Audience API di Chrome: * Lihat masalah yang ada yang dilaporkan untuk API. * Laporkan 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. Untuk melakukannya, Anda harus memiliki atau membuat akun GitHub.
  • Untuk mendapatkan info terbaru secara keseluruhan tentang Privacy Sandbox, berlanggananlah ke feed RSS [Progress in the Privacy Sandbox].

Cari tahu selengkapnya

Foto oleh Ray Hennessy di Unsplash.