Protected Audience API: panduan developer

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

Bagi yang baru menggunakan Protected Audience API, baca Ringkasan Protected Audience API untuk penjelasan tingkat tinggi tentang API.

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

Status penerapan

To be notified of status changes in the API, join the mailing list for developers.

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 pernah dikunjungi pengguna.

Protected Audience API adalah eksperimen pertama yang diterapkan di Chromium dalam rangkaian proposal 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

Penjelasan tentang deployment Protected Audience API dasar di seluruh situs pengiklan dan penayang tersedia di protected-audience-demo.web.app/.

Tonton deployment end-to-end 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 di iframe atau frame dengan fence

Iklan dapat dirender dalam <iframe> atau <fencedframe>, bergantung pada flag 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 menang/kalah debug sementara.

Fitur yang didukung

Protected Audience API di balik flag fitur di Chromium adalah eksperimen pertama untuk menguji fitur berikut dari Protected Audience API:

  • Grup minat: disimpan oleh browser, dengan metadata terkait untuk mengonfigurasi bidding dan rendering iklan.
  • Penawaran 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 dan metadata lelang dari pembeli.
  • Rendering iklan dalam versi Frame Terpagar yang untuk sementara lebih longgar: dengan akses jaringan dan logging diizinkan untuk rendering iklan.

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

Izin grup minat

Implementasi Protected Audience API saat ini secara default mengizinkan panggilan joinAdInterestGroup() dari mana saja di halaman, bahkan dari iframe lintas domain.

Pada masa mendatang, setelah pemilik situs memiliki waktu untuk memperbarui kebijakan izin iframe lintas domain, rencana kami 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 berbagai cara:

  • Pembeli mungkin ingin menghitung sisa anggaran dalam kampanye iklan.
  • Penjual mungkin diwajibkan untuk memeriksa materi iklan terhadap kebijakan penayang.

Kode layanan nilai/kunci Protected Audience API kini 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 Protected Audience API open source yang berjalan di lingkungan eksekusi tepercaya.

Lihat postingan blog layanan Protected Audience API untuk mengetahui update linimasa. Kami akan memberikan pemberitahuan yang memadai kepada developer untuk mulai menguji dan mengadopsi sebelum transisi ini terjadi.

Mendeteksi dukungan fitur

Sebelum menggunakan API, periksa apakah API tersebut didukung oleh browser dan tersedia di dokumen:

'joinAdInterestGroup' in navigator &&
  document.featurePolicy.allowsFeature('join-ad-interest-group') &&
  document.featurePolicy.allowsFeature('run-ad-auction') ?
  console.log('navigator.joinAdInterestGroup() is supported on this page') :
  console.log('navigator.joinAdInterestGroup() is not supported on this page');

Bagaimana cara kerja Protected Audience API?

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

Fitur Protected Audience API akan ditambahkan dari waktu ke waktu seiring kemajuan pengerjaan implementasi.

1. Pengguna mengunjungi situs pengiklan

Seseorang mengunjungi situs produsen sepeda kustom di browser di laptopnya.

Bayangkan seorang 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

Pengguna membuka browser di laptopnya dan mengunjungi situs. Kode JavaScript untuk bergabung ke 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 browser tersebut ikuti.

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 browsernya merupakan anggota—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 adalah situs berita. Situs 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 bagi ruang iklan yang tersedia.

Lelang iklan kemungkinan akan dijalankan oleh penyedia sisi suplai (SSP) penayang, atau penayang itu sendiri. Tujuan lelang adalah memilih iklan yang paling sesuai untuk satu slot iklan yang tersedia di halaman saat ini. Lelang mempertimbangkan grup minat yang diikuti 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 Key/Value

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

Selama lelang iklan, penjual dapat meminta data real-time tentang materi iklan tertentu dengan membuat permintaan ke layanan Key/Value mereka. Penjual dapat meminta informasi ini selama runAdAuction() berdasarkan properti trustedScoringSignalsUrl, bersama dengan kunci dari properti renderUrl dari semua entri di ads dan kolom adComponents dari semua grup minat dalam lelang.

Pembeli dapat meminta data real-time dari layanan Key/Value mereka 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

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

Promise yang ditampilkan oleh runAdAuction() diselesaikan ke objek konfigurasi frame tertutup (FencedFrameConfig) saat flag resolveToConfig disetel ke true dalam konfigurasi lelang. Konfigurasi frame digunakan oleh frame tertutup untuk mengarahkan frame ke iklan pemenang, tetapi URL iklan tidak terlihat oleh penyemat frame.

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

7. Hasil lelang dilaporkan

Rencana jangka panjangnya adalah mengizinkan browser melaporkan hasil lelang untuk penjual dan pembeli menggunakan Private Aggregation API.

Sebagai mekanisme pelaporan tingkat peristiwa sementara, kode yang menerapkan reportResult() untuk penjual, dan reportWin() untuk bidder yang menang, dapat memanggil fungsi sendReportTo(). Fungsi ini memerlukan satu argumen: string yang merepresentasikan 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 frame yang dibatasi, di situs berita. Data laporan dikirim ke penjual dan pembeli.

Klik pada iklan yang dirender dalam frame tertutup akan dilaporkan. Untuk mempelajari lebih lanjut cara kerjanya, lihat Pelaporan Iklan Frame Terpagar.

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 diterapkan di Chromium dalam rangkaian proposal TURTLEDOVE.

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

Upaya TURTLEDOVE adalah tentang menawarkan API baru untuk menangani kasus penggunaan ini sekaligus menawarkan beberapa peningkatan privasi utama:

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

Protected Audience API dikembangkan dari TURTLEDOVE dan kumpulan proposal terkait untuk modifikasi yang lebih baik bagi developer yang akan menggunakan API:

  • Di SPARROW: Criteo mengusulkan penambahan model layanan ("Gatekeeper") yang berjalan di trusted execution environment (TEE). Protected Audience API mencakup penggunaan TEE yang lebih terbatas, untuk pencarian data real-time dan pelaporan gabungan.
  • Proposal TERN NextRoll dan PARRROT Magnite menjelaskan berbagai peran yang dimiliki pembeli dan penjual dalam lelang di perangkat. Alur bidding/pemberian skor 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 menganonimkan permintaan iklan dan menerapkan properti privasi. Protected Audience API belum mengadopsi model proxy ini. Kami menyelaraskan JavaScript API untuk PARAKEET dan Protected Audience API untuk mendukung upaya mendatang dalam menggabungkan fitur terbaik dari kedua proposal tersebut.

Protected Audience API belum mencegah jaringan iklan situs mempelajari iklan yang dilihat seseorang. Kami berharap dapat memodifikasi API agar menjadi lebih privat seiring 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 yang telah ditambahkan ke grup tersebut di seluruh situs yang telah mereka kunjungi. Seperti teknologi Privacy Sandbox itu sendiri, setelan pengguna dapat berkembang seiring dengan masukan dari pengguna, badan pengatur, dan pihak lainnya.

Kami akan terus memperbarui setelan yang tersedia di Chrome berdasarkan pengujian dan masukan. Pada masa mendatang, kami berencana menawarkan setelan yang lebih terperinci untuk mengelola Protected Audience API dan data terkait.

Pemanggil API tidak dapat mengakses keanggotaan grup saat pengguna menjelajah dalam mode Samaran, dan keanggotaan dihapus saat pengguna menghapus data situs mereka.

Apakah worklet Protected Audience di-cache oleh browser?

Resource yang berisi worklet Protected Audience—worklet pembuatan bid dan pelaporan pembeli, serta worklet pemberian skor dan pelaporan iklan penjual—di-cache oleh browser. Anda dapat menggunakan header Cache-Control untuk mengontrol perilaku caching.

Berinteraksi dan memberikan masukan

Mendapatkan dukungan

Untuk mengajukan pertanyaan dan mendapatkan dukungan terkait penerapan, demo, atau dokumentasi:

Untuk pertanyaan yang lebih umum tentang pemenuhan kebutuhan Anda dengan Protected Audience API, ajukan masalah di repositori API. Anda juga dapat mendiskusikan kasus penggunaan industri di Improving Web Advertising Business Group W3C.

Gunakan formulir masukan Privacy Sandbox untuk menyampaikan 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 individu.

Mendapatkan info terbaru