Pelajari cara menggunakan API, termasuk cara menggunakan tanda 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 seperti yang diamati
Topics JavaScript API memiliki satu metode: document.browsingTopics()
. Hal ini memiliki dua tujuan:
- Memberi tahu browser untuk mencatat kunjungan halaman saat ini sebagai telah diamati oleh pemanggil, sehingga kunjungan tersebut dapat digunakan nanti 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 hingga tiga topik, satu untuk masing-masing dari tiga epoch terbaru, dalam urutan acak. Satu epoch adalah jangka waktu yang ditetapkan 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 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 sewaktu-waktu 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 di 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 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.
}
Akses 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 saat ini seperti yang diamati oleh pemanggil, sehingga metode ini dapat digunakan nanti dalam penghitungan topik. Mulai Chrome 108, metode ini dapat menerima argumen opsional agar kunjungan halaman tidak dicatat: {skipObservation:true}
.
Dengan kata lain, {skipObservation:true}
berarti panggilan metode tidak akan menyebabkan halaman saat ini disertakan dalam penghitungan topik.
Gunakan header untuk mengakses topik dan menandainya sebagai diamati
Anda dapat mengakses topik, dan juga menandai kunjungan halaman sebagai diamati, dengan bantuan request dan header response.
Penggunaan pendekatan header bisa jauh lebih berperforma tinggi daripada menggunakan JavaScript API, karena API memerlukan pembuatan iframe lintas origin dan membuat panggilan document.browsingTopics()
darinya. (Iframe lintas origin harus digunakan untuk panggilan, karena konteks dari mana API dipanggil digunakan untuk memastikan browser menampilkan topik yang sesuai dengan pemanggil.) Penjelasan Topik memiliki diskusi lebih lanjut: Apakah ada cara untuk mengirim topik menggunakan Ambil sebagai header permintaan? .
Topik dapat diakses dari header Sec-Browsing-Topics
permintaan fetch()
atau XHR
.
Menetapkan header Observe-Browsing-Topics: ?1
pada respons terhadap permintaan
menyebabkan browser merekam kunjungan halaman saat ini seperti yang diamati oleh pemanggil,
sehingga nantinya dapat digunakan dalam penghitungan topik.
Topik dapat diakses dan diamati dengan header HTTP dengan dua cara:
fetch()
: Tambahkan{browsingTopics: true}
ke parameter opsi permintaanfetch()
. Demo header Topics menunjukkan contoh sederhananya.- Atribut iframe: Tambahkan atribut
browsingtopics
ke elemen<iframe>
, atau tetapkan JavaScript yang setara propertiiframe.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 {i>header<i}:
- Pengalihan akan diikuti, dan topik yang dikirim dalam permintaan pengalihan akan dikhususkan untuk URL alihan.
- Header permintaan tidak akan mengubah status untuk 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 akan diterima jika permintaan yang sesuai menyertakan header topik.
- URL permintaan menyediakan domain yang dapat didaftarkan yang dicatat sebagai domain pemanggil.
Men-debug implementasi API Anda
Halaman chrome://topics-internals
tersedia di Chrome di desktop setelah Anda mengaktifkan Topics API. Bagian ini 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 menyertakan 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 tidak cukup (di situs yang mengamati topik) untuk menyediakan lima topik.
Kolom Domain konteks yang diamati (di-hash) memberikan nilai yang di-hash dari nama host yang topiknya diamati.
Melihat topik yang disimpulkan untuk nama host
Anda juga dapat melihat topik yang disimpulkan oleh model pengklasifikasi Topics untuk satu atau beberapa nama host di chrome://topics-internals
.
Implementasi Topics API saat ini menyimpulkan topik hanya dari nama host; bukan dari bagian lain mana pun dari URL.
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 {i>Host<i}.
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. Ini mungkin membantu untuk memastikan bahwa tanda baris perintah telah bekerja seperti yang diharapkan.
Dalam contoh, time_period_per_epoch
telah ditetapkan ke 15 detik (defaultnya adalah tujuh hari).
Parameter yang ditampilkan dalam screenshot sesuai dengan tanda yang dapat disetel saat menjalankan Chrome dari command line. Misalnya, demo di topics-fetch-demo.glitch.me merekomendasikan penggunaan flag berikut:
--enable-features=BrowsingTopics,BrowsingTopicsParameters:time_period_per_epoch/15s/max_epoch_introduction_delay/3s,PrivacySandboxAdsAPIsOverride,PrivacySandboxSettings3,OverridePrivacySandboxSettingsLocalTesting
Daftar berikut ini menjelaskan setiap parameter, nilai default-nya, dan tujuannya.
Tanda Chrome
BrowsingTopics
- Nilai default: diaktifkan
- Apakah Topics API diaktifkan.
PrivacySandboxAdsAPIsOverride
- Nilai default: diaktifkan
- Mengaktifkan Ads API: Attribution Reporting, Protected Audience, Topics, Fenced Frames.
PrivacySandboxSettings4
- Nilai default: dinonaktifkan
- Mengaktifkan rilis keempat setelan UI Privacy Sandbox.
OverridePrivacySandboxSettingsLocalTesting
- Nilai default: diaktifkan
- Jika diaktifkan, browser tidak lagi mengharuskan pengaktifan 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 suatu halaman untuk disertakan dalam topik kalkulasi.
BrowsingTopics:number_of_epochs_to_expose
- Nilai default: 3
- Jumlah epoch yang digunakan untuk menghitung topik yang akan diberikan ke permintaan konteks tambahan. Browser akan menyimpan hingga N+1 epoch secara internal.
BrowsingTopics:time_period_per_epoch
- Nilai default: 7d-0h-0m-0s
- Durasi setiap epoch. Untuk proses debug, sebaiknya tetapkan ini ke (misalnya) 15 detik, bukan default 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 suatu topik dalam satu epoch adalah satu topik yang ditampilkan secara acak dari seluruh taksonomi topik. Keacakan melekat pada epoch dan situs.
BrowsingTopics:number_of_epochs_of_observation_data_to_use_for_filtering
- Nilai default: 3
- Berapa 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 oleh domain yang dapat disimpan untuk setiap topik teratas. Niat adalah untuk membatasi memori yang sedang digunakan.
BrowsingTopics:max_number_of_api_usage_context_entries_to_load_per_epoch
- Nilai default: 100000
- Jumlah maksimum entri yang boleh diambil dari database untuk setiap kueri untuk konteks penggunaan API. Kueri akan terjadi sekali per epoch pada penghitungan topik baik. Tujuannya adalah untuk membatasi penggunaan memori puncak.
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 set konfigurasi. Memperbarui parameter konfigurasi tanpa memperbarui
config_version
akan biasanya tidak masalah untuk pengujian lokal, tetapi dalam beberapa situasi dapat meninggalkan browser dalam tidak konsisten dan dapat mengakibatkan error browser, misalnya memperbaruinumber_of_top_topics_per_epoch
. BrowsingTopics:taxonomy_version
- Nilai default: 1
- Taksonomi versi yang digunakan oleh API.
Memilih untuk tidak menyertakan situs Anda
Anda dapat memilih tidak ikut dalam penghitungan topik untuk halaman tertentu di situs Anda dengan menyertakan header Permissions-Policy Permissions-Policy: browsing-topics=()
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 lainnya.
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 untuk header, gunakan self
dan domain apa pun yang Anda izinkan untuk mengakses API. Misalnya, untuk sepenuhnya menonaktifkan penggunaan Topics API di semua konteks penjelajahan kecuali untuk asal 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 demo.
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.