Protected Audience API: panduan developer

Panduan developer untuk lelang iklan di perangkat guna menayangkan pemasaran ulang dan audiens kustom, tanpa pelacakan pihak ketiga lintas situs.

Bagi pengguna baru Protected Audience API, baca ringkasan Protected Audience API untuk mendapatkan penjelasan umum tentang API.

Postingan ini ditulis untuk developer sebagai referensi teknis untuk iterasi terbaru dari Protected Audience API eksperimental. Demo deployment Protected Audience API dasar tersedia, begitu juga referensi API untuk pembeli dan penjual iklan.

Status penerapan

Agar mendapatkan notifikasi tentang perubahan status di API, bergabunglah ke milis untuk developer.

Apa yang dimaksud dengan Protected Audience API?

Protected Audience API adalah API Privacy Sandbox yang dirancang 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 API adalah eksperimen pertama yang akan diimplementasikan di Chromium dalam proposal keluarga TURTLEDOVE.

Mencoba Protected Audience API

Referensi API yang tersedia

Dokumen ini berfungsi sebagai ringkasan Protected Audience API. Jika Anda mencari metode dan parameter API tertentu:

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/.

Tonton deployment menyeluruh ini untuk mempelajari cara kerja kode demo Protected Audience API dan cara menggunakan Chrome DevTools untuk proses debug.

Menguji API ini

Anda dapat menguji Protected Audience API untuk satu pengguna di Chrome Beta 101.0.4951.26 dan yang lebih baru di desktop:

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.

Fitur yang didukung

Protected Audience API di balik flag 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 dilonggarkan untuk sementara: dengan akses jaringan dan logging yang diizinkan untuk rendering iklan.

Baca selengkapnya tentang dukungan dan batasan fitur di penjelasan Protected Audience API.

Izin grup minat

Default untuk implementasi Protected Audience API 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 memperbarui kebijakan izin iframe lintas-domain, rencananya adalah melarang panggilan dari iframe lintas-domain.

Layanan Nilai/Kunci

Untuk mendukung lelang iklan Protected Audience API, browser dapat mengakses layanan nilai kunci 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 dalam kampanye iklan.
  • Penjual mungkin diwajibkan untuk memeriksa materi iklan terhadap kebijakan penayang.

Kode layanan kunci/nilai Protected Audience API sekarang tersedia. Lihat postingan blog pengumuman untuk mengetahui pembaruan status.

Untuk pengujian awal, model "Bawa Server Anda Sendiri" diperkenalkan. Dalam jangka panjang, teknologi iklan harus menggunakan layanan Nilai Kunci/Nilai Protected Audience open source yang berjalan di trusted execution environment.

Lihat postingan blog layanan Protected Audience API untuk mengetahui info terbaru terkait linimasa. Kami akan memberikan pemberitahuan yang cukup kepada developer untuk memulai pengujian dan penerapan sebelum transisi ini dilakukan.

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 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.

Fitur Protected Audience API akan ditambahkan dari waktu ke waktu seiring dengan progres penerapan.

1. Pengguna mengunjungi situs pengiklan

Seseorang 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 steel buatan tangan. Hal ini memberi produsen sepeda peluang pemasaran ulang.

2. Browser pengguna diminta untuk menambahkan grup minat

Pengguna membuka browser di laptop dan mengunjungi situs. Kode JavaScript untuk bergabung dengan grup minat iklan berjalan di browser.

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 Protected Audience API. Keanggotaan grup minat disimpan oleh browser, di perangkat pengguna, dan tidak dibagikan kepada vendor browser atau orang lain.

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 yang menjadi anggota browser—jika pemilik grup minat diundang untuk mengajukan bid.

Baca dokumentasi developer generatedBid().

3. Pengguna mengunjungi situs yang menjual ruang iklan

Seseorang 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 dengan bidding real-time.

4. Lelang iklan dijalankan di browser

Seseorang melihat situs berita di browser di laptopnya. Lelang iklan Protected Audience API dijalankan untuk memilih iklan untuk ruang iklan yang tersedia.

Lelang iklan kemungkinan dijalankan oleh penyedia sisi pasokan (SSP) penayang, atau penayang itu sendiri. Tujuan lelang adalah untuk memilih iklan yang paling sesuai untuk satu slot iklan yang tersedia di halaman saat ini. Lelang mempertimbangkan grup minat yang menjadi anggota browser, beserta data dari pembeli ruang iklan dan penjual dari layanan Kunci/Nilai.

5. Penjual dan pembeli yang berpartisipasi meminta data real-time dari layanan Nilai Kunci

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

Selama lelang iklan, penjual dapat meminta data real-time tentang materi iklan tertentu dengan membuat permintaan ke Layanan Nilai Kunci mereka. Penjual dapat meminta informasi ini selama runAdAuction() dengan 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 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

Seseorang melihat situs berita di browser di laptopnya. Iklan diskon 20% untuk sepeda ditampilkan dalam bingkai berpagar yang aman.

Promise yang ditampilkan oleh runAdAuction() di-resolve ke objek konfigurasi frame berpagar (FencedFrameConfig) saat flag resolveToConfig ditetapkan ke true dalam konfigurasi lelang. Konfigurasi frame digunakan oleh frame berpagar untuk menavigasi frame ke iklan pemenang, tetapi URL iklan tidak terlihat oleh penyempan frame.

Objek konfigurasi frame berpagar tersedia mulai dari M114. Untuk mengetahui informasi selengkapnya tentang objek FencedFrameConfig, lihat artikel blog Chrome.

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 pemenang, dapat memanggil fungsi sendReportTo(). Ini memerlukan satu argumen: string yang mewakili URL yang diambil setelah lelang selesai, yang mengenkode informasi tingkat peristiwa yang akan dilaporkan.

8. Klik iklan dilaporkan

Seseorang mengklik iklan sepeda, yang disematkan dengan bingkai berpagar, di situs berita. Data laporan 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.

Ringkasan setiap tahap lelang iklan Protected Audience API
Diagram ini menguraikan setiap tahap lelang Protected Audience API.

Apa perbedaan antara Protected Audience API dan TURTLEDOVE?

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

Protected Audience API mengikuti prinsip tingkat tinggi TURTLEDOVE. Beberapa iklan online telah 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 apa yang dianggap pengiklan menarik bagi seseorang.
  • Pengiklan dapat menayangkan iklan berdasarkan minat, tetapi tidak dapat menggabungkan minat tersebut dengan informasi lain tentang seseorang—terutama, siapa dia atau halaman apa yang dia kunjungi.

Protected Audience API berkembang dari TURTLEDOVE dan kumpulan proposal terkait untuk perubahan guna 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 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 API 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 menjadikan permintaan iklan anonim dan menerapkan properti privasi. Protected Audience API belum mengadopsi model proxy ini. Kami menyelaraskan JavaScript API untuk PARAKEET dan Protected Audience API, untuk mendukung pekerjaan mendatang guna menggabungkan lebih lanjut fitur terbaik dari kedua proposal tersebut.

Protected Audience API belum mencegah jaringan iklan situs mempelajari iklan mana yang dilihat seseorang. Kami berharap dapat mengubah 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 ke navigator.runAdAuction()
  • userBiddingSignals, properti objek konfigurasi grup minat yang diteruskan ke navigator.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 melihat dan mengelola daftar grup minat tempat mereka ditambahkan 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 berdasarkan pengujian dan masukan. Ke depannya, kami berencana menawarkan setelan yang lebih terperinci untuk mengelola Protected Audience API dan data terkait.

Pemanggil API tidak dapat mengakses keanggotaan grup saat pengguna menjelajahi 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—worklet pelaporan dan pembuatan bid pembeli, serta worklet pelaporan dan penskoran 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 penerapan, demo, atau dokumentasi:

Untuk pertanyaan umum lainnya tentang memenuhi kebutuhan Anda dengan Protected Audience API, laporkan masalah di repositori API. Anda juga dapat mendiskusikan kasus penggunaan industri di Improving Web Advertising Business Group W3C.

Gunakan formulir masukan Privacy Sandbox untuk membagikan masukan secara pribadi kepada 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