Pelajari cara menggunakan API, termasuk cara menggunakan flag Chrome untuk pengujian.
Status penerapan
- Topics API telah menyelesaikan fase diskusi publik dan saat ini tersedia untuk 99 persen pengguna, dengan peningkatan skala hingga 100 persen.
- Untuk memberikan masukan tentang Topics API, buat Masalah di Penjelasan topik atau berpartisipasi dalam diskusi di Meningkatkan Grup Bisnis Periklanan Web. Penjelasan memiliki sejumlah pertanyaan terbuka yang masih memerlukan definisi lebih lanjut.
- Linimasa Privacy Sandbox memberikan linimasa penerapan untuk Topics API dan proposal Privacy Sandbox lainnya.
- Topics API: update terbaru menjelaskan perubahan dan peningkatan kualitas Topics API dan implementasinya.
Coba demo
Ada dua demo Topics API yang memungkinkan Anda mencoba Topics sebagai satu pengguna.
- Demo JavaScript API: topics-demo.glitch.me.
- Demo header: topics-fetch-demo.glitch.me
Anda juga dapat menjalankan colab Topics untuk mencoba model pengklasifikasi Topics.
Gunakan JavaScript API untuk mengakses topik dan mencatatnya sebagai diamati
Topics JavaScript API memiliki satu metode: document.browsingTopics()
. Hal ini memiliki dua tujuan:
- Memberi tahu browser untuk mencatat kunjungan halaman saat ini yang telah diamati oleh pemanggil, sehingga nantinya dapat digunakan untuk menghitung topik bagi pengguna (untuk pemanggil).
- Mengakses topik untuk pengguna yang telah diamati oleh pemanggil.
Metode ini menampilkan promise yang di-resolve ke array yang berisi hingga tiga topik, satu untuk masing-masing dari tiga epoch terbaru, dalam urutan acak. Epoch adalah periode waktu yang disetel ke satu minggu dalam implementasi Chrome.
Setiap objek topik dalam array yang ditampilkan oleh document.browsingTopics()
memiliki properti berikut:
configVersion
: string yang mengidentifikasi konfigurasi Topics API saat ini, misalnyachrome.2
modelVersion
: string yang mengidentifikasi pengklasifikasi machine learning yang digunakan untuk menyimpulkan topik untuk situs, misalnya4
taxonomyVersion
: string yang mengidentifikasi kumpulan topik yang digunakan oleh browser, misalnya2
topic
: angka yang mengidentifikasi topik dalam taksonomi, misalnya309
version
: string yang menggabungkanconfigVersion
,taxonomyVersion
, danmodelVersion
, misalnyachrome.2:2:4
Parameter yang dijelaskan dalam panduan ini dan detail API (seperti ukuran taksonomi, jumlah topik yang dihitung per minggu, dan jumlah topik yang ditampilkan per panggilan) dapat berubah seiring kami menyertakan masukan ekosistem dan melakukan iterasi pada API.
Mendeteksi dukungan untuk document.browsingTopics
Sebelum menggunakan API, periksa apakah API tersebut didukung oleh browser dan tersedia dalam dokumen:
'browsingTopics' in document && document.featurePolicy.allowsFeature('browsing-topics') ?
console.log('document.browsingTopics() is supported on this page') :
console.log('document.browsingTopics() is not supported on this page');
Mengakses topik dengan JavaScript API
Berikut adalah contoh dasar dari kemungkinan penggunaan API untuk mengakses topik bagi pengguna saat ini.
try {
// Get the array of top topics for this user.
const topics = await document.browsingTopics();
// Request an ad creative, providing topics information.
const response = await fetch('https://ads.example/get-creative', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify(topics)
})
// Get the JSON from the response.
const creative = await response.json();
// Display ad.
} catch (error) {
// Handle error.
}
Mengakses topik tanpa mengubah status
document.browsingTopics()
menampilkan topik yang diamati oleh pemanggil untuk pengguna saat ini. Secara default, metode ini juga menyebabkan browser mencatat kunjungan halaman yang sedang berlangsung seperti yang diamati oleh pemanggil, sehingga nantinya dapat digunakan dalam penghitungan topik. Mulai Chrome 108, Anda dapat meneruskan argumen opsional ke metode ini untuk melewati perekaman kunjungan halaman: {skipObservation:true}
.
Dengan kata lain, {skipObservation:true}
berarti panggilan metode tidak akan menyebabkan halaman saat ini disertakan dalam penghitungan topik.
Menggunakan header untuk mengakses topik dan menandainya sebagai diamati
Anda dapat mengakses topik, dan juga menandai kunjungan halaman sebagai diamati, dengan bantuan header request dan response.
Penggunaan pendekatan header bisa jauh lebih efektif daripada menggunakan JavaScript API, karena API mengharuskan pembuatan iframe lintas origin dan melakukan panggilan document.browsingTopics()
dari iframe tersebut. (Iframe lintas origin harus digunakan untuk panggilan, karena konteks tempat API dipanggil akan digunakan untuk memastikan browser menampilkan topik yang sesuai dengan pemanggil.) Penjelasan Topics berisi diskusi lebih lanjut: Haruskah ada cara untuk mengirim topik menggunakan Ambil sebagai header permintaan? .
Topik dapat diakses dari header Sec-Browsing-Topics
untuk permintaan fetch()
atau XHR
.
Menyetel header Observe-Browsing-Topics: ?1
pada respons terhadap permintaan
akan menyebabkan browser mencatat kunjungan halaman saat ini seperti yang diamati oleh pemanggil,
sehingga nantinya dapat digunakan dalam penghitungan topik.
Topik dapat diakses dan diamati dengan header HTTP melalui dua cara:
fetch()
: Menambahkan{browsingTopics: true}
ke parameter opsi permintaanfetch()
. Demo header Topics menampilkan contoh sederhana tentang hal ini.- Atribut iframe: Tambahkan atribut
browsingtopics
ke elemen<iframe>
, atau tetapkan properti JavaScript yang setaraiframe.browsingTopics = true
. Domain sumber iframe yang dapat didaftarkan adalah domain pemanggil: misalnya, untuk<iframe src="https://example.com" browsingtopics></iframe>
: pemanggilnya adalahexample.com
.
Beberapa catatan tambahan tentang header:
- Pengalihan akan diikuti, dan topik yang dikirim dalam permintaan pengalihan akan dikhususkan untuk URL pengalihan.
- Header permintaan tidak akan mengubah status pemanggil kecuali jika ada header respons yang sesuai. Artinya, tanpa header respons, kunjungan halaman tidak akan dicatat sebagai diamati, sehingga tidak akan memengaruhi penghitungan topik pengguna untuk epoch berikutnya.
- Header respons hanya diterima jika permintaan yang sesuai menyertakan header topik.
- URL permintaan menyediakan domain yang dapat didaftarkan yang dicatat sebagai domain pemanggil.
Mendebug implementasi API Anda
Halaman chrome://topics-internals
tersedia di Chrome di desktop setelah Anda mengaktifkan Topics API. Ini akan menampilkan topik untuk pengguna saat ini, topik yang disimpulkan untuk nama host, dan informasi teknis tentang implementasi API. Kami melakukan iterasi dan meningkatkan desain halaman berdasarkan masukan developer: tambahkan masukan Anda di bugs.chromium.org.
Melihat topik yang dihitung untuk browser Anda
Pengguna dapat melihat informasi tentang topik yang diamati untuk browser mereka selama epoch saat ini dan sebelumnya dengan melihat chrome://topics-internals
.
Screenshot ini menunjukkan bahwa situs yang baru-baru ini dikunjungi mencakup topics-demo-cats.glitch.me
dan cats-cats-cats-cats.glitch.me
. Hal ini menyebabkan Topics API memilih Pets
dan Cats
sebagai dua topik teratas untuk epoch saat ini. Tiga topik lainnya telah dipilih secara acak, karena histori penjelajahan (pada situs yang mengamati topik) tidak cukup untuk menyediakan lima topik.
Kolom Domain konteks yang diamati (di-hash) memberikan nilai yang di-hash dari nama host yang topiknya diamati.
Lihat topik yang disimpulkan untuk nama host
Anda juga dapat melihat topik yang ditentukan oleh model pengklasifikasi Topics untuk satu atau beberapa nama host di chrome://topics-internals
.
Implementasi Topics API saat ini menyimpulkan topik dari nama host saja, bukan dari bagian URL lainnya.
Hanya gunakan nama host (tanpa protokol atau jalur) untuk melihat topik yang disimpulkan dari Pengklasifikasi chrome://topics-internals
. chrome://topics-internals
akan menampilkan error jika Anda mencoba menyertakan "/" di kolom Host.
Melihat informasi Topics API
Anda dapat menemukan informasi tentang implementasi dan setelan Topics API, seperti versi taksonomi dan durasi epoch, di chrome://topics-internals
. Nilai ini mencerminkan setelan default untuk API atau parameter yang berhasil ditetapkan dari command line. Hal ini dapat membantu untuk memastikan bahwa penanda command line telah berfungsi seperti yang diharapkan.
Dalam contoh, time_period_per_epoch
telah ditetapkan ke 15 detik (default-nya adalah tujuh hari).
Parameter yang ditampilkan di screenshot sesuai dengan tanda yang dapat disetel saat menjalankan Chrome dari command line. Misalnya, demo di topics-fetch-demo.glitch.me merekomendasikan penggunaan tanda berikut:
--enable-features=BrowsingTopics,BrowsingTopicsParameters:time_period_per_epoch/15s/max_epoch_introduction_delay/3s,PrivacySandboxAdsAPIsOverride,PrivacySandboxSettings3,OverridePrivacySandboxSettingsLocalTesting
Daftar berikut menjelaskan setiap parameter, nilai default, dan tujuannya.
Tanda Chrome
BrowsingTopics
- Nilai default: aktif
- Apakah Topics API diaktifkan.
PrivacySandboxAdsAPIsOverride
- Nilai default: aktif
- Mengaktifkan API iklan: Attribution Reporting, Protected Audience, Topics, Fenced Frames.
PrivacySandboxSettings4
- Nilai default: dinonaktifkan
- Mengaktifkan rilis keempat setelan UI Privacy Sandbox.
OverridePrivacySandboxSettingsLocalTesting
- Nilai default: aktif
- Jika diaktifkan, browser tidak perlu lagi mengaktifkan setelan dasar untuk mengaktifkan fitur Privacy Sandbox.
BrowsingTopicsBypassIPIsPubliclyRoutableCheck
- Nilai default: dinonaktifkan
- Jika diaktifkan, pemeriksaan apakah alamat IP dapat dirutekan secara publik akan diabaikan saat menentukan kelayakan halaman untuk disertakan dalam penghitungan topik.
BrowsingTopics:number_of_epochs_to_expose
- Nilai default: 3
- Jumlah epoch dari tempat untuk menghitung topik yang akan diberikan ke konteks permintaan. Browser akan secara internal mengikuti hingga N+1 epoch.
BrowsingTopics:time_period_per_epoch
- Nilai default: 7h-0j-0m-0d
- Durasi setiap epoch. Untuk proses debug, sebaiknya tetapkan ini ke (misalnya) 15 detik, bukan default ke tujuh hari.
BrowsingTopics:number_of_top_topics_per_epoch
- Nilai default: 5
- Jumlah topik yang dihitung per epoch.
BrowsingTopics:use_random_topic_probability_percent
- Nilai default: 5
- Probabilitas bahwa setiap topik dalam satu epoch ditampilkan secara acak dari seluruh taksonomi topik. Keacakan ini melekat pada satu epoch dan situs.
BrowsingTopics:number_of_epochs_of_observation_data_to_use_for_filtering
- Nilai default: 3
- Berapa banyak epoch data penggunaan API (yaitu pengamatan topik) yang akan digunakan untuk memfilter topik untuk konteks panggilan.
BrowsingTopics:max_number_of_api_usage_context_domains_to_keep_per_topic
- Nilai default: 1000
- Jumlah maksimum domain konteks yang diamati menurut yang disimpan untuk setiap topik teratas. Tujuannya adalah membatasi memori yang sedang digunakan.
BrowsingTopics:max_number_of_api_usage_context_entries_to_load_per_epoch
- Nilai default: 100000
- Jumlah entri maksimum yang diizinkan untuk diambil dari database setiap kueri untuk konteks penggunaan API. Kueri akan terjadi sekali per epoch pada waktu penghitungan topik. Tujuannya adalah untuk membatasi puncak penggunaan memori.
BrowsingTopics:max_number_of_api_usage_context_domains_to_store_per_page_load
- Nilai default: 30
- Jumlah maksimum domain konteks penggunaan API yang diizinkan untuk disimpan per pemuatan halaman.
BrowsingTopics:config_version
- Nilai default: 1
- Mengenkode parameter konfigurasi Topics API. Setiap nomor versi hanya boleh
dipetakan ke satu kumpulan konfigurasi. Mengupdate parameter konfigurasi tanpa mengupdate
config_version
biasanya tidak masalah untuk pengujian lokal, tetapi dalam beberapa situasi dapat membuat browser dalam keadaan tidak konsisten dan dapat menyebabkan error browser, misalnya mengupdatenumber_of_top_topics_per_epoch
. BrowsingTopics:taxonomy_version
- Nilai default: 1
- Versi taksonomi yang digunakan oleh API.
Tidak ikut serta dalam situs
Anda dapat memilih tidak menggunakan penghitungan topik untuk halaman tertentu di situs dengan menyertakan header Permissions-Policy: browsing-topics=()
Kebijakan-Izin di halaman guna mencegah penghitungan topik untuk semua pengguna di halaman tersebut saja. Kunjungan berikutnya ke halaman lain di situs Anda tidak akan terpengaruh: jika Anda menetapkan kebijakan untuk memblokir Topics API di satu halaman, hal ini tidak akan memengaruhi halaman lain.
Anda juga dapat mengontrol pihak ketiga mana yang memiliki akses ke topik di halaman Anda menggunakan header Permissions-Policy
untuk mengontrol akses pihak ketiga ke Topics API. Sebagai parameter pada header, gunakan self
dan domain apa pun yang ingin Anda izinkan untuk mengakses API. Misalnya, untuk sepenuhnya menonaktifkan penggunaan Topics API dalam semua konteks penjelajahan kecuali untuk origin Anda sendiri dan https://example.com
, setel header respons HTTP berikut:
Permissions-Policy: browsing-topics=(self "https://example.com")
Langkah berikutnya
- Pelajari lebih lanjut apa yang dimaksud dengan topik dan cara kerjanya.
- Coba demonya.
Cari tahu selengkapnya
Berinteraksi dan berbagi masukan
- GitHub: Membaca penjelasan Topics API, serta mengajukan pertanyaan dan mengikuti diskusi terkait masalah yang ada di repositori API.
- W3C: Diskusikan kasus penggunaan industri dalam Meningkatkan Grup Bisnis Periklanan Web.
- Pengumuman: Bergabung atau melihat milis.
- Dukungan developer Privacy Sandbox: Ajukan pertanyaan dan ikuti diskusi tentang repo Dukungan Developer Privacy Sandbox.
- Chromium: Laporkan bug Chromium untuk mengajukan pertanyaan tentang implementasi yang saat ini tersedia untuk diuji di Chrome.