Panduan Developer Topics API

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.

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, misalnya chrome.2
  • modelVersion: string yang mengidentifikasi pengklasifikasi machine learning yang digunakan untuk menyimpulkan topik 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 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 permintaan fetch(). Demo header Topics menunjukkan contoh sederhananya.
  • Atribut iframe: Tambahkan atribut browsingtopics ke elemen <iframe>, atau tetapkan JavaScript yang setara properti 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.

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.

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

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.

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

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).

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

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

Cari tahu selengkapnya

Berinteraksi dan berbagi masukan