Panduan Developer Topics API

Pelajari cara menggunakan API, termasuk cara menggunakan flag Chrome untuk pengujian.

Poin penting: Uji coba origin Relevansi dan Pengukuran Privacy Sandbox berakhir pada 20 September 2023 dan API kini tersedia untuk 99% pengguna Chrome, dan pendaftaran uji coba origin telah ditutup. Untuk terus mengikuti persentase pengguna yang mengaktifkan setiap API, lihat grafik status Chrome.

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, misalnya chrome.2
• modelVersion: string yang mengidentifikasi pengklasifikasi machine learning yang digunakan untuk menyimpulkan topik untuk situs, misalnya 4
• taxonomyVersion: string yang mengidentifikasi kumpulan topik yang digunakan oleh browser, misalnya 2
• topic: angka yang mengidentifikasi topik dalam taksonomi, misalnya 309
• version: string yang menggabungkan configVersion, taxonomyVersion, dan modelVersion, misalnya chrome.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');

Perhatian: Dukungan fitur pada halaman saat ini tidak menjamin bahwa API dapat digunakan: pengguna mungkin telah menonaktifkan API dari setelan browser, atau mereka mungkin memiliki setelan lain yang mencegah API digunakan. Untuk melindungi privasi pengguna, tidak ada cara untuk memeriksa setelan lain ini secara terprogram.

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. Menggunakan pendekatan header bisa jauh lebih efektif daripada memanggil JavaScript API.

Topik dapat diakses dari header Sec-Browsing-Topics untuk permintaan fetch() atau XHR.

Catatan: Penyertaan header Topics dalam permintaan XHR hanya tersedia untuk sementara, dan dukungan akan dihapus pada masa mendatang.

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 permintaan fetch(). Demo header Topics menampilkan contoh sederhana tentang hal ini.
• Atribut iframe: Tambahkan atribut browsingtopics ke elemen <iframe>, atau tetapkan properti JavaScript yang setara iframe.browsingTopics = true. Domain sumber iframe yang dapat didaftarkan adalah domain pemanggil: misalnya, untuk <iframe src="https://example.com" browsingtopics></iframe>: pemanggilnya adalah example.com.

Poin penting: Perintah CSP dapat melarang eksekusi kode pihak ketiga yang disertakan di halaman, seperti panggilan fetch() dalam skrip teknologi iklan.

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.

Panel Status Topics halaman chrome://topics-internals menampilkan ID topik, penetapan topik acak dan nyata, serta versi taksonomi dan model.

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.

Panel Pengklasifikasi halaman chrome://topics-internals menampilkan topik yang dipilih, host yang dikunjungi, serta versi dan jalur model.

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.

Catatan: Mulai Juni 2023, Topics mulai menggunakan taksonomi yang ditingkatkan, di mana kami menambahkan 280 kategori yang berfokus secara komersial, seperti "Pakaian Atletik", "Kasur", dan "Perjalanan Mewah", sekaligus menghapus 160 kategori termasuk topik seperti "Teknik Sipil" dan "Berkuda". Beberapa contoh di sini menggunakan taksonomi versi 1.

Dalam contoh, time_period_per_epoch telah ditetapkan ke 15 detik (default-nya adalah tujuh hari).

Panel chrome://topics-internals Fitur dan Parameter menampilkan fitur yang diaktifkan, waktu per epoch, jumlah epoch yang digunakan untuk menghitung topik, versi taksonomi, dan setelan lainnya.

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 mengupdate number_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

• Penjelasan teknis Topics API
• Mempelajari Privacy Sandbox

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.