Protected Audience API: panduan developer

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

Bagi pengguna yang baru menggunakan Protected Audience API, baca ringkasan Protected Audience API untuk penjelasan API tingkat tinggi.

Postingan ini ditulis untuk developer sebagai referensi teknis untuk sebagian besar iterasi terbaru dari Protected Audience API eksperimental. Demo model dasar Deployment Protected Audience API tersedia, sebagaimana Referensi API untuk pembeli dan penjual iklan.

Status penerapan

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

Apa itu Protected Audience API?

Protected Audience API adalah Privacy Sandbox API yang dirancang untuk berfungsi pemasaran ulang dan penggunaan audiens kustom yang dirancang agar tidak dapat digunakan oleh pihak ketiga untuk melacak perilaku penjelajahan di seluruh situs. API ini memungkinkan lelang di perangkat dengan browser, untuk memilih iklan relevan untuk situs web yang sebelumnya telah dikunjungi pengguna.

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

Mencoba Protected Audience API

Referensi API yang tersedia

Dokumen ini berfungsi sebagai ringkasan tentang 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 pengiklan dan penayang situs 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.

Uji API ini

Anda dapat menguji Protected Audience API untuk satu pengguna di Chrome Beta 101.0.4951.26 dan yang lebih baru pada {i>desktop<i}:

Merender iklan dalam iframe atau frame dengan fence

Iklan dapat dirender dalam <iframe> atau <fencedframe>, bergantung pada penanda diatur.

Untuk menggunakan <fencedframe> guna merender iklan:

--enable-features=InterestGroupStorage,AdInterestGroupAPI,Fledge,FencedFrames

Untuk menggunakan <iframe> guna merender iklan:

--enable-features=InterestGroupStorage,AdInterestGroupAPI,Fledge,AllowURNsInIframes --disable-features=FencedFrames

Sertakan flag BiddingAndScoringDebugReportingAPI untuk mengaktifkan metode pelaporan kekalahan/kemenangan debug sementara.

Fitur yang didukung

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

  • Grup minat: disimpan oleh browser, dengan metadata terkait untuk mengonfigurasi bidding dan rendering iklan.
  • Bidding di perangkat oleh pembeli (DSP atau pengiklan): berdasarkan aset grup minat dan sinyal dari penjual.
  • Pemilihan iklan di perangkat oleh penjual (SSP atau penayang): berdasarkan metadata dan bid lelang dari pembeli.
  • Rendering iklan di versi Fenced Frames untuk sementara waktu: dengan serta akses dan logging jaringan yang diizinkan untuk rendering iklan.

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

Izin grup minat

Default untuk implementasi Protected Audience API saat ini adalah mengizinkan panggilan joinAdInterestGroup() dari mana saja di halaman, bahkan dari iframe lintas domain.

Di masa mendatang, setelah pemilik situs memiliki waktu untuk memperbarui kebijakan izin iframe, adalah melarang panggilan dari iframe lintas domain.

Layanan Kunci/Nilai

Untuk mendukung lelang iklan Protected Audience API, browser dapat mengakses layanan kunci/nilai untuk mengambil informasi real-time yang mendukung lelang iklan Protected Audience API. Ini informasi dapat digunakan dalam beberapa cara:

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

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

Untuk pengujian awal, "Bring Your Own Server" diperkenalkan. Dalam jangka panjang, teknologi iklan perlu menggunakan Layanan Kunci/Nilai Protected Audience API open source yang berjalan di eksekusi tepercaya lingkungan fleksibel App Engine.

Lihat postingan blog layanan Protected Audience API untuk mengetahui pembaruan linimasa. Kami akan memberikan pemberitahuan penting bagi developer untuk memulai pengujian dan adopsi sebelum transisi ini terjadi.

Dukungan fitur deteksi

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

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

Bagaimana cara kerja Protected Audience API?

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

Fitur Protected Audience API akan ditambahkan seiring waktu seiring berjalannya proses implementasi.

1. Pengguna mengunjungi situs pengiklan

Seseorang yang mengunjungi situs produsen sepeda kustom melalui browser di laptopnya.

Bayangkan pengguna mengunjungi situs produsen sepeda kustom (pengiklan) (dalam contoh ini) dan meluangkan waktu di halaman produk baja buatan tangan sepeda. Dengan begitu, pembuat sepeda memiliki pemasaran ulang.

2. Browser pengguna diminta untuk menambahkan grup minat

Seorang pengguna membuka browser di laptopnya, lalu mengunjungi sebuah situs. JavaScript kode untuk bergabung dengan grup minat iklan berjalan di browser.

Panggilan platform sisi permintaan (DSP) pengiklan (atau pengiklan itu sendiri) 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 Protected Audience API. Keanggotaan grup minat disimpan oleh {i>browser<i}, pada 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 melakukan bid?

generateBid() dipanggil untuk setiap grup minat tempat browser menjadi 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 melalui browser di laptopnya. Situs memiliki slot iklan yang kosong.

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

4. Lelang iklan dijalankan di browser

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

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

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

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

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

Pembeli dapat meminta data real-time dari layanan Kunci/Nilai mereka menggunakan properti trustedBiddingSignalsUrl dan trustedBiddingSignalsKeys dari argumen grup minat yang diteruskan ke navigator.joinAdInterestGroup().

Saat runAdAuction() dipanggil, browser akan membuat permintaan ke setiap iklan server tepercaya pembeli. 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 tombol.

6. Iklan pemenang akan ditampilkan

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

Promise yang ditampilkan oleh runAdAuction() akan di-resolve menjadi objek konfigurasi frame dengan fence (FencedFrameConfig) saat tanda resolveToConfig ditetapkan ke true dalam konfigurasi lelang. Konfigurasi frame digunakan oleh frame dengan fence untuk membuka frame ke iklan pemenang, tetapi URL iklan tidak terlihat oleh sematan 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 API Agregasi Pribadi.

Sebagai mekanisme pelaporan tingkat peristiwa sementara, kode yang menerapkan reportResult() untuk penjual, dan reportWin() untuk bidder yang menang, dapat panggil fungsi sendReportTo(). Ini membutuhkan satu argumen: string 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 rangka berpagar, di situs berita. Data laporan dikirim ke penjual dan pembeli.

Klik pada iklan yang dirender dalam frame dengan fence dilaporkan. Untuk mempelajari lebih lanjut tentang cara kerjanya, lihat Pelaporan Iklan Bingkai Berpagar.

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

Protected Audience API mengikuti prinsip tingkat tinggi TURTLEDOVE. Beberapa iklan {i>online<i} memiliki didasarkan pada penayangan iklan kepada orang yang berpotensi tertarik dan berinteraksi dengan pengiklan atau jaringan iklan. Secara historis, cara ini bekerja dengan pengiklan yang mengenali orang tertentu saat mereka menjelajahi {i>website<i}, yang merupakan inti masalah privasi pada web saat ini.

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

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

Protected Audience API berkembang dari TURTLEDOVE dan sekumpulan proposal terkait untuk modifikasi untuk melayani developer yang akan menggunakan API dengan lebih baik:

  • Di SPARROW: Criteo mengusulkan penambahan dari 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.
  • TERN dan PARRROT dari Magnite proposal menjelaskan berbagai peran yang dimiliki pembeli dan penjual dalam lelang di perangkat. Alur bidding/penskoran iklan Protected Audience API didasarkan pada pekerjaan ini.
  • Berbasis hasil RTB House dan Tingkat produk Modifikasi TURTLEDOVE meningkatkan personalisasi dan model anonimitas kemampuan lelang di perangkat
  • PARAKEET adalah Proposal Microsoft untuk layanan iklan seperti TURTLEDOVE yang mengandalkan proxy server yang berjalan di TEE antara browser dan penyedia teknologi iklan, untuk menganonimkan permintaan iklan dan menerapkan privasi properti baru. Protected Audience API belum menggunakan model proxy ini. Kami menghadirkan JavaScript API untuk ParaKEET dan Protected Audience API agar selaras, dalam mendukung pekerjaan di masa depan untuk menggabungkan lebih lanjut fitur terbaik dari kedua proposal tersebut.

Protected Audience API belum mencegah jaringan iklan situs mempelajari iklan mana yang dilihat seseorang. Kami ingin memodifikasi API agar menjadi lebih pribadi 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. Sebuah topik dapat dimasukkan dalam properti berikut:

  • auctionSignals, properti objek konfigurasi lelang yang diteruskan ke navigator.runAdAuction()
  • userBiddingSignals, properti konfigurasi grup minat objek diteruskan ke navigator.joinAdInterestGroup()

Konfigurasi browser yang tersedia

Pengguna dapat menyesuaikan partisipasi mereka untuk uji coba Privacy Sandbox di Chrome dengan mengaktifkan atau menonaktifkan pengaturan tingkat atas di chrome://settings/adPrivacy.

Selama pengujian awal, pengguna akan dapat menggunakan data privasi tingkat tinggi Setelan sandbox untuk memilih tidak menggunakan Protected Audience API. Chrome berencana agar pengguna dapat melihat dan mengelola daftar grup minat yang telah ditambahi grup minat tersebut di seluruh web situs yang mereka kunjungi. Seperti halnya teknologi Privacy Sandbox, setelan pengguna dapat berkembang dengan masukan dari pengguna, badan pengatur, dan lainnya.

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

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

Apakah worklet Protected Audience di-cache oleh browser?

Resource yang berisi worklet Protected Audience—pembuatan bid dan worklet pelaporan pembeli, serta worklet pelaporan dan 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, melaporkan masalah di repositori API. Anda juga dapat mendiskusikan kasus penggunaan industri di W3C Meningkatkan Grup Bisnis Iklan Web.

Gunakan formulir masukan Privacy Sandbox untuk berbagi masukan secara pribadi dengan tim Chrome di luar forum publik.

Memilih tidak ikut

Ingin memilih tidak menggunakan Protected Audience API? Pelajari cara memblokir akses ke Protected Audience API, sebagai pemilik situs atau pengguna perorangan.

Mendapatkan info terbaru