Mengimplementasikan Topics API

Halaman ini menjelaskan detail penerapan bagi pemanggil Topics API untuk mengamati dan mengakses topik. Sebelum Anda mulai menerapkan solusi, pastikan browser Anda disiapkan dengan benar. Periksa bagian ringkasan untuk mempelajari lebih lanjut cara pemanggil mengamati dan mengakses topik pengguna.

Mengamati dan mengakses Topik

Ada dua cara untuk mengamati dan mengakses topik pengguna: header HTTP dan JavaScript API.

Header HTTP

Menggunakan header HTTP adalah pendekatan yang direkomendasikan untuk mengamati dan mengakses topik pengguna. Pendekatan ini dapat jauh lebih efektif daripada menggunakan JavaScript API. Dengan header HTTP, URL permintaan menyediakan domain yang dapat didaftarkan yang dicatat sebagai domain pemanggil. Ini adalah domain yang terlihat telah mengamati topik pengguna.

Mulai Permintaan

Ada dua cara untuk menggunakan Topik dengan header:

  • Dengan mengakses header permintaan dan respons pada permintaan fetch() yang menyertakan opsi browsingTopics: true.
  • Dengan mengakses header untuk elemen iframe yang menyertakan atribut browsingtopics.
Mulai permintaan dengan pengambilan

Dengan menggunakan pengambilan, pemanggil API membuat permintaan yang menyertakan {browsingTopics: true} dalam parameter opsi. Asal parameter URL permintaan pengambilan adalah asal yang terlihat telah mengamati topik.

   fetch('<topics_caller_eTLD+1>', { browsingTopics: true })
    .then((response) => {
        // Process the response
    });
Memulai permintaan dengan iframe

Tambahkan atribut browsingtopics ke elemen <iframe>. Browser akan menyertakan header Sec-Browsing-Topics dalam permintaan iframe, dengan asal iframe sebagai pemanggil.

   <iframe src="https://adtech.example" browsingtopics></iframe>

Menafsirkan nilai header permintaan

Untuk kedua pendekatan (pengambilan dan iframe), topik yang diamati untuk pengguna dapat diambil di server dari header permintaan Sec-Browsing-Topics. Topics API akan menyertakan topik pengguna di header secara otomatis pada permintaan fetch() atau iframe. Jika API menampilkan satu atau beberapa topik, permintaan pengambilan ke origin tempat topik diamati akan menyertakan header Sec-Browsing-Topics seperti ini:

   (325);v=chrome.1:1:1, ();p=P000000000

Jika tidak ada topik yang ditampilkan oleh API, header akan terlihat seperti ini:

   ();p=P0000000000000000000000000000000

Pengalihan akan diikuti, dan topik yang dikirim dalam permintaan pengalihan akan khusus untuk URL pengalihan. Nilai header Sec-Browsing-Topics diisi, untuk mengurangi risiko penyerang mempelajari jumlah topik yang dicakup ke pemanggil berdasarkan panjang header.

Menangani respons sisi server

Jika respons terhadap permintaan menyertakan header Observe-Browsing-Topics: ?1, hal ini menandakan bahwa browser harus menandai topik dari permintaan yang menyertainya sebagai yang diamati, dan menyertakan kunjungan halaman saat ini dalam penghitungan topik epoch berikutnya pengguna. Sertakan header Observe-Browsing-Topics: ?1 dalam respons di kode sisi server Anda:

   res.setHeader('Observe-Browsing-Topics', '?1');
Header Permintaan dan Respons untuk menyetel dan mengambil topik.
Header untuk iframe dan fetch().

Membagikan topik yang diamati kepada partner

Karena SSP hanya ada di sisi penayang, DSP mungkin ingin membagikan topik yang mereka amati di situs pengiklan kepada SSP partner mereka. Mereka dapat melakukannya dengan membuat permintaan fetch() dengan header topik ke SSP dari konteks tingkat teratas pengiklan.

const response = await fetch("partner-ssp.example", {
 browsingTopics: true
});

Mengamati dan mengakses Topik dengan JavaScript

Metode Topics JavaScript API document.browsingTopics() menyediakan cara untuk mengamati dan mengambil topik minat pengguna dalam lingkungan browser: - Mencatat Pengamatan: Memberi tahu browser bahwa pemanggil telah mengamati pengguna yang mengunjungi halaman saat ini. Pengamatan ini berkontribusi pada penghitungan topik pengguna untuk pemanggil pada epoch mendatang. - Akses Topik: Mengambil topik yang sebelumnya diamati pemanggil untuk pengguna. Metode ini menampilkan array hingga tiga objek topik, satu untuk setiap epoch terbaru, dalam urutan acak.

Sebaiknya Anda membuat fork demo Topics JavaScript API dan menggunakannya sebagai titik awal untuk kode Anda.

Ketersediaan API

Sebelum menggunakan API, pastikan API tersebut didukung dan tersedia:

 if ('browsingTopics' in document && document.featurePolicy.allowsFeature('browsing-topics')) {
    console.log('document.browsingTopics() is supported on this page');
 } else {
    console.log('document.browsingTopics() is not supported on this page');
 }

Menyematkan iframe

Iframe lintas origin harus digunakan untuk panggilan, karena konteks tempat API dipanggil digunakan untuk memastikan browser menampilkan topik yang sesuai untuk pemanggil. Sertakan elemen <iframe> dalam HTML Anda:

<iframe src="https://example.com" browsingtopics></iframe>

Anda juga dapat membuat iframe secara dinamis menggunakan JavaScript:

 const iframe = document.createElement('iframe');
 iframe.setAttribute('src', 'https://adtech.example/');
 document.body.appendChild(iframe);

Panggil API dari dalam iframe

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

Secara default, metode document.browsingTopics() juga menyebabkan browser mencatat kunjungan halaman saat ini seperti yang diamati oleh pemanggil, sehingga nantinya dapat digunakan dalam penghitungan topik. Metode ini dapat meneruskan argumen opsional untuk melewati perekaman kunjungan halaman: {skipObservation:true}.

 // current page won't be included in the calculation of topics:
 const topics = await document.browsingTopics({skipObservation:true});

Memahami respons

Maksimum tiga topik ditampilkan: satu atau nol untuk setiap tiga minggu terakhir, bergantung pada apakah topik diamati atau tidak. Hanya topik yang diamati oleh pemanggil untuk pengguna saat ini yang ditampilkan. Berikut contoh yang ditampilkan API:

 [{
'configVersion': chrome.2,
 'modelVersion': 4,
 'taxonomyVersion': 2,
 'topic': 309,
 'version': chrome.2:2:4
}]
  • configVersion: string yang mengidentifikasi versi konfigurasi algoritma topik browser.
  • modelVersion: string yang mengidentifikasi pengklasifikasi machine learning yang digunakan untuk menyimpulkan topik.
  • taxonomyVersion: string yang mengidentifikasi kumpulan topik yang digunakan oleh browser.
  • topik: angka yang mengidentifikasi topik dalam taksonomi.
  • version: string yang menggabungkan configVersion, taxonomyVersion, dan modelVersion. 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 saat kami menggabungkan masukan ekosistem dan melakukan iterasi pada API.

Lihat halaman Uji & tayangkan untuk mempelajari respons yang diharapkan dan cara menggunakan Topik sebagai sinyal tambahan untuk iklan yang lebih relevan.

Langkah berikutnya

Pelajari cara men-deploy, menguji, dan menskalakan solusi berbasis Topics.
Pelajari alat yang tersedia di Chrome untuk melihat informasi Topics API, memahami cara topik ditetapkan, dan men-debug penerapan Anda.

Lihat juga

Lihat referensi kami untuk lebih memahami Topics API di Web.