Panduan integrasi Topics API

Pelajari cara menggunakan Topics API untuk memenuhi kasus penggunaan teknologi iklan tertentu.

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.

Sebelum memulai

Langkah pertama adalah memahami Topics API dan layanan.

1. Tinjau dokumen developer:
   1. Mulailah dengan membaca ringkasan untuk mendapatkan informasi terbaru tentang Topics API dan kemampuannya.
   2. Tonton Panduan demo topik (video).
   3. Coba demo header dan JavaScript API Topics.
   4. Lakukan fork pada demo (keduanya menyediakan link ke kodenya) dan menjalankannya dari situs Anda sendiri.
   5. Baca penjelasan API untuk memahami detailnya lebih lanjut.
2. Periksa status penerapan dan linimasa Topics API.
3. Memahami peran API dalam mendukung relevansi iklan di masa depan tanpa cookie.
4. Untuk mendapatkan notifikasi terkait perubahan status di API, gabung ke milis untuk developer dan nantikan info terbaru tentang Topics.
5. Ikuti terus berita terbaru tentang Topics API.
6. Berkontribusi pada percakapan melalui masalah GitHub atau panggilan W3C.
7. Jika Anda menemukan istilah yang tidak dikenal, tinjau glosarium Privacy Sandbox.
8. Untuk mengetahui informasi selengkapnya tentang konsep Chrome, seperti tanda Chrome, tinjau video singkat dan artikel yang tersedia di goo.gle/cc.

Membuat dan menguji secara lokal

Bagian ini menjelaskan cara mencoba Topics API sebagai developer individu.

1. Pengujian dan deployment lokal (Perkiraan waktu: sekitar 2 hari)
   1. Aktifkan API dengan browser lokal Anda dari command line dengan tombol fitur. Uji demo header dan JavaScript API untuk melihat cara kerja Topics (video panduan).
   2. Jalankan Colab Topics untuk menguji inferensi topik menggunakan model machine learning Topics.

Mengaktifkan Topics di browser

Guna mengaktifkan Topics API di instance Chrome Anda sendiri untuk pengujian lokal, Anda memiliki dua opsi:

1. Buka chrome://flags/#privacy-sandbox-ads-apis dan aktifkan Privacy Sandbox API.
2. (Direkomendasikan) Jalankan Chrome dari command line dengan tanda Chromium menggunakan parameter khusus Topics API untuk dikonfigurasi sesuai kebutuhan.

Mengaktifkan Privacy Sandbox API.

Anda memiliki kontrol yang lebih mendetail atas fitur Topics dengan menjalankan Chrome dari command line. Misalnya, Anda dapat menetapkan epoch Topics (jangka waktu yang digunakan oleh API untuk menghitung minat pengguna) dan mengonfigurasi perilaku API sesuai dengan kebutuhan Anda.

Penting untuk diingat bahwa jika chrome://flags/#privacy-sandbox-ads-apis diaktifkan, setelan ini akan mengganti setelan epoch command line Anda dan mengembalikannya ke nilai default (saat ini satu minggu).

Pratinjau mekanisme Topics API

Anda dapat memperoleh visibilitas ke mekanisme Topics API dasar secara lokal menggunakan alat chrome://topics-internals.

Tab chrome://topics-internals tools Topics State.

Gunakan alat Internal Topics API untuk menguji pengklasifikasi secara lokal berdasarkan situs yang Anda buka.

Dengan alat ini, Anda dapat meninjau:

• Status Topik: Menampilkan topik yang diamati untuk pengguna saat ini.
• Pengklasifikasi: Pratinjau topik yang disimpulkan untuk nama host.
• Fitur dan Parameter: Lihat nilai parameter API untuk memeriksa apakah tombol fitur berfungsi sebagaimana mestinya.

Pelajari cara men-debug Topics dengan alat Internal.

Cara API menampilkan topik

Jika Chrome tidak memiliki cukup topik yang diamati untuk membuat lima topik teratas selama satu epoch (satu minggu), Topics API akan menambahkan topik acak untuk menyelesaikan lima topik teratas. Kolom Topics Internal dengan judul Real or Random menunjukkan apakah topik tertentu didasarkan pada pengamatan nyata atau "padding" acak tambahan untuk melengkapi lima topik teratas. Baca selengkapnya tentang mekanisme ini dalam penjelasan.

Topik yang dipilih untuk setiap epoch dipilih secara acak dari lima topik teratas pengguna selama jangka waktu tersebut. Jika tidak ada cukup topik yang diamati selama epoch, topik tambahan akan dipilih secara acak untuk menghasilkan total lima topik. Topik yang dipilih secara acak ini tunduk pada pemfilteran.

Untuk lebih meningkatkan privasi dan memastikan semua topik dapat diwakili, ada kemungkinan 5% topik yang dipilih untuk satu epoch dipilih secara acak dari semua topik, bukan dipilih dari topik yang diamati. Seperti pada kasus di atas, topik yang diamati secara acak terlalu sedikit ini tidak akan difilter.

Informasi lebih lanjut tentang cara pemilihan topik tersedia di Klasifikasi topik.

Rekomendasi utama

1. Pastikan Anda menutup (dan menghentikan) semua proses Chrome sebelum memulai proses baru menggunakan tanda tersebut.
2. Jika melakukan pengujian di lingkungan lokal, Anda harus menonaktifkan chrome://flags/#privacy-sandbox-ads-apis karena akan menggantikan setelan command line sehingga mengembalikan ke nilai default.
3. Gunakan halaman debug untuk memahami cara kerja Topics secara lokal.
4. Jika ada pertanyaan, lihat Masalah GitHub untuk penjelasannya.
5. Jika API tidak berfungsi seperti yang diharapkan, coba tips pemecahan masalah kami.

Merencanakan deployment MVP

Topics API memberikan akses ke topik minat yang diamati bagi pengguna, tanpa harus berupaya melacak situs yang dikunjungi pengguna, atau mengekspos histori navigasi mereka.

Pemanggil Topics API adalah entity yang memanggil metode JavaScript document.browsingTopics(), atau mengamati dan mengakses topik menggunakan header permintaan HTTP. Dalam hal ini, kode Anda dan eTLD+1 yang menjadi asal panggilan adalah pemanggil. Saat memanggil Topics API, Anda meminta browser pengguna untuk mengamati topik minat saat pengguna mengunjungi situs. Kunjungan ini kemudian dipertimbangkan dalam penghitungan topik untuk epoch berikutnya.

Topics API dirancang untuk memfilter hasil per pemanggil atau per-eTLD+1 dari konteks panggilan. Dengan kata lain, asal iframe (jika menggunakan JavaScript API) atau URL permintaan pengambilan (saat menggunakan header) dianggap sebagai pemanggil, dan topik dihitung sesuai dengan pemanggil tersebut.

Diagram berikut mengilustrasikan pendekatan ini:

Cara API mengamati dan mengakses topik.

Dalam diagram ini:

1. Pengguna membuka Chrome dan mengunjungi beberapa situs (customerA.example, customerB.example.br, dll.) yang menyertakan iframe teknologi iklan Anda (sumber: iframe.adtech.example) atau header penerusan panggilan pengambilan.
   • Chrome akan merekam topik yang diminati pengguna ini.
2. Setelah tujuh hari bernavigasi, dengan topik minat yang diamati oleh Topics API, pengguna yang sama di perangkat yang sama mengunjungi situs target (publisher-e.example). Topics API menampilkan daftar topik dan dalam contoh spesifik ini, satu topik yang dihitung dari pengamatan minggu sebelumnya terhadap pengguna ini akan ditampilkan.
   • Hanya browser pengguna yang mengunjungi situs yang telah diamati oleh adtech.example di Langkah 1 yang akan menampilkan hasil topik di Langkah 2 (kami menyebut pemfilteran pengamatan ini—Anda tidak dapat melihat topik pengguna yang belum pernah Anda lihat sebelumnya).
3. Dengan daftar ini (dari satu topik untuk saat ini), Anda dapat memanggil API back-end (ads.adtech.example/topics-backend) untuk menggunakan data topik sebagai bagian dari set data kontekstual Anda.
4. Bergantung pada kasus penggunaan, Anda dapat membuat pengalaman yang lebih dipersonalisasi untuk pengguna ini dengan mengakses topik minat yang Anda amati selama beberapa minggu terakhir.

Memanggil Topics API

Ada dua cara untuk mengamati dan mengakses topik untuk pengguna. Anda dapat menggunakan

• JavaScript API dari dalam iframe:
  • Menambahkan iframe di situs target (situs penayang) yang berisi kode JavaScript yang memanggil Topics API menggunakan document.browsingTopics().
• Opsi header:
  • Ambil (yang direkomendasikan) atau XHR (tidak direkomendasikan dan hanya tersedia selama uji coba origin yang telah selesai):
    • Anda dapat mengakses topik dari header Sec-Browsing-Topics dalam permintaan ke backend teknologi iklan. Ini adalah opsi berperforma terbaik (latensi rendah untuk mengamati topik dari satu pengguna tertentu).
  • Menggunakan tag iframe dengan atribut browsingtopics:
    • Anda dapat menambahkan iframe dengan atribut browsingtopics dan Chrome akan menyertakan topik (diamati untuk eTLD+1 dari iframe) di header Sec-Browsing-Topics pada permintaan untuk iframe tersebut.

Implementasi dengan JavaScript dan iframe

Sebaiknya lakukan fork dengan demo JavaScript API atau demo header, lalu gunakan salah satu di antaranya sebagai titik awal untuk kode Anda.

Anda dapat menyertakan elemen <iframe> di HTML atau menambahkan iframe secara dinamis dengan JavaScript. Salah satu cara untuk membuat iframe secara dinamis adalah menggunakan JavaScript berikut:

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

Periksa apakah Topics API didukung dan tersedia di perangkat ini melalui deteksi fitur:

'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');

Panggil Topics API dari dalam iframe tersebut:

const topics = await document.browsingTopics();

Anda akan menerima daftar topik yang diamati untuk pengguna ini dari tiga minggu terakhir. Ingat, daftar ini boleh kosong atau dapat mencakup 1, 2, atau 3 topik, hingga tiga minggu terakhir.

Berikut adalah contoh yang ditampilkan API:

[{'configVersion': String, 
  'modelVersion': String, 
  'taxonomyVersion': String, 
  'topic': Number, 
  'version': String}]

• configVersion: string yang mengidentifikasi konfigurasi saat ini.
• modelVersion: string yang mengidentifikasi pengklasifikasi machine learning yang digunakan untuk menyimpulkan topik.
• taxonomyVersion: string yang mengidentifikasi serangkaian topik yang saat ini digunakan oleh browser.
• topic: angka yang mengidentifikasi topik dalam taksonomi.
• version: string yang menggabungkan configVersion dan modelVersion.

Baca selengkapnya tentang penerapan ini.

Implementasi dengan header HTTP

Topik dapat diakses dari header Sec-Browsing-Topics dalam permintaan fetch()/XHR, atau dari permintaan iframe.

Header untuk iframe dan fetch().

Anda dapat menandai topik yang disediakan oleh header permintaan sebagai diamati dengan menyetel header Observe-Browsing-Topics: ?1 pada respons terhadap permintaan. Browser kemudian akan menggunakan topik tersebut untuk menghitung topik yang diminati pengguna.

Jika API menampilkan satu atau beberapa topik, permintaan pengambilan ke eTLD+1 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

Nilai header Sec-Browsing-Topics diberi padding untuk mengurangi risiko penyerang mempelajari jumlah topik yang dicakupkan ke pemanggil berdasarkan panjang header.

Terapkan dengan fetch()

Di halaman penayang, tambahkan kode untuk permintaan pengambilan, dan pastikan untuk menyertakan {browsingTopics: true}.

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

Di browser yang mendukung API, permintaan fetch() akan menyertakan header Sec-Browsing-Topics yang mencantumkan topik yang diamati untuk nama host URL permintaan.

Mengimplementasikan dengan iframe

Demikian pula dengan permintaan fetch(), header Sec-Browsing-Topics akan dikirim saat menggunakan atribut browsingtopics di iframe.

<iframe src="<topics_caller_eTLD+1>" browsingtopics></iframe>

Dalam hal ini, akan menjadi pemanggil, mirip dengan panggilan pengambilan.

Sisi server—identik untuk semua kasus

Agar topik dalam header permintaan Sec-Browsing-Topics ditandai oleh browser sebagai diamati, serta untuk menyertakan kunjungan halaman saat ini dalam penghitungan topik teratas epoch berikutnya pengguna, respons server harus menyertakan Observe-Browsing-Topics: ?1.

Berikut adalah contoh JavaScript yang menggunakan setHeader():

res.setHeader('Observe-Browsing-Topics', '?1');

Implementasi backend topik

Menambahkan backend untuk Topics bersifat opsional. Pilihan Anda bergantung pada cara dan tempat Anda ingin menggunakan topik yang dihitung di perangkat (di browser).

// Use the language/framework/stack of your preference
function processTopicsBackendAPI(topics, user, domain, caller) {
  // Validate inputs
  // If the list is not empty, continue
  // Use topics as an additional contextual signal
}

Menggunakan topik sebagai data kontekstual

Data topik dapat dipertimbangkan bersama sinyal lain seperti URL, kata kunci, dan bahkan tag, sebagai sinyal tambahan tentang audiens Anda.

Seperti yang dijelaskan dalam Memaksimalkan relevansi iklan setelah cookie pihak ketiga, ada beberapa pendekatan dalam memanfaatkan Topics untuk menayangkan iklan yang relevan. Beberapa di antaranya melibatkan penggunaan topik untuk membuat audiens, dan yang lainnya menyarankan penggunaan Topics sebagai salah satu sinyal di antara sinyal lainnya untuk melatih model machine learning yang akan digunakan untuk menyimpulkan minat tambahan audiens atau bahkan untuk mengoptimalkan logika bidding.

Mem-build dan men-deploy

1. Mengumpulkan topik dengan mengamati pengguna dalam produksi—yang belum diskalakan (Perkiraan waktu: sekitar 1 minggu)
   1. Pahami opsi Anda: iframe dan JavaScript atau header HTTP
   2. Tentukan domain iframe.
   3. Buat kode JavaScript, menggunakan aplikasi demo sebagai referensi kode — atau terapkan opsi header.
   4. Deploy Topics ke lingkungan yang Anda kontrol (beberapa situs produksi).
   5. Tambahkan implementasi Topics ke beberapa situs target (saat ini tidak lebih dari lima situs).
   6. Pengujian dan validasi fungsional.
2. [Opsional] Gunakan data Topics sebagai sinyal kontekstual (dengan URL, tag, dll.) (Perkiraan waktu: sekitar 3 hari).
   1. Setelah menerima daftar topik, Anda dapat mengirimkannya ke backend dengan sinyal kontekstual lainnya.

Men-deploy ke beberapa situs target

Setelah Anda memiliki kode, mari kita tambahkan ke beberapa situs target untuk pengujian pertama dan untuk memastikan API stabil dan berfungsi di lingkungan yang terkontrol ini.

Sebaiknya pilih situs target yang:

• Mendapatkan kunjungan bulanan dalam jumlah kecil (kurang dari sekitar 1 juta kunjungan/bulan): Sebaiknya Anda memulai dengan men-deploy API ke audiens kecil terlebih dahulu.
• Anda memiliki dan mengontrol: Jika perlu, Anda dapat dengan cepat menonaktifkan implementasi tanpa persetujuan yang rumit.
• Tidak penting bagi bisnis: Karena penerapan ini dapat mengganggu pengalaman pengguna Anda, mulailah dengan situs target yang berisiko rendah.
• Total tidak lebih dari lima situs: Untuk saat ini, Anda tidak memerlukan traffic atau eksposur sebanyak itu.
• Merepresentasikan berbagai tema: Pilih situs yang mewakili kategori yang berbeda (misalnya, satu tentang olahraga, satu lagi tentang berita, satu lagi dari makanan dan minuman, dll.). Anda dapat menggunakan alat topik internal di Chrome untuk memvalidasi domain dan cara domain tersebut diklasifikasikan oleh pengklasifikasi machine learning Topics. Pelajari proses debug lebih lanjut di panduan developer Topics API.

Pengujian dan validasi fungsional

Saat memanggil Topics API dalam lingkungan terbatas ini, Anda akan mendapatkan:

• Array kosong topik [] jika ini adalah panggilan pertama perangkat ini, untuk situs ini dan penelepon dalam tujuh hari terakhir.
• Daftar yang berisi nol hingga tiga topik, yang mewakili minat pengguna ini.
• Setelah tujuh hari pengamatan, Anda akan menerima:
  • Satu topik yang mewakili minat pengguna tersebut yang dihitung dari histori navigasi pada minggu tersebut.
    • Satu detail penting: jika Anda belum mengamati cukup banyak topik oleh pengguna agar Topics API dapat menghitung lima topik teratas minggu itu, maka Topics akan menambahkan topik acak sebanyak yang diperlukan agar mencapai jumlah total lima topik. Temukan detail selengkapnya tentang API.
• Entri topik baru menggantikan salah satu dari ketiganya jika Anda memanggilnya setelah empat minggu pengamatan.
  • Hal ini terjadi karena Topics API akan stabil selama minggu-minggu berikutnya, tidak mengekspos terlalu banyak minat pengguna. Temukan detail selengkapnya di GitHub.
• Jika Anda belum mengamati topik untuk pengguna selama lebih dari tiga minggu, Topics API akan menampilkan array kosong [] lagi.

Ukur performa dan metrik pengalaman pengguna Anda.

• Waktu proses panggilan JavaScript ke Topics API di dalam iframe lintas origin harus diukur untuk digunakan dalam analisis performa di masa mendatang—pastikan untuk mengumpulkan dan menyimpan data telemetri dengan benar di backend Anda.
  • Waktu yang dibutuhkan untuk membuat iframe dan postMessage() topik, setelah topik diterima, juga merupakan metrik lain yang memungkinkan untuk dihitung.

Pemecahan masalah

Saya memanggil Topics API, tetapi saya menerima null sebagai hasilnya. Apa yang harus saya lakukan?

Jika Anda memanggil Topics API dalam minggu pertama mengamati pengguna, hal ini wajar.

Rekomendasi utama

1. Uji kode front-end Anda untuk memastikan JavaScript berfungsi seperti yang diharapkan.

2. Uji backend Anda untuk menerima hasil topik.

   1. Ingatlah untuk memastikan jenis data dan parameter API back-end dikonfigurasi dengan benar.
   2. Pastikan backend Anda dikonfigurasi untuk melakukan penskalaan dengan tepat.

3. Berdasarkan pengalaman kami, Anda perlu memberikan waktu setidaknya tiga minggu sebelum mulai mendapatkan hasil topik yang lebih relevan.

4. Tidak semua pengguna mengaktifkan Topics:

   1. Pengguna dapat secara eksplisit menonaktifkan Topics API.
   2. Halaman penayang dapat mengontrol kebijakan izin. Lihat (memilih tidak ikut) di panduan developer Topics API.
   3. Buka chromestatus.com untuk mengetahui detail selengkapnya.

5. Tambahkan metrik dan kemampuan observasi ke lingkungan ini: Anda akan membutuhkannya untuk menganalisis hasil pertama. Contoh metrik mencakup:

   1. Latensi panggilan;
   2. Error HTTP pada panggilan topik;

6. Cobalah untuk membatasi perubahan pada penerapan Anda selama tiga minggu awal.

Skalakan ke produksi

Berikut ringkasan langkah demi langkah cara menskalakan ke lingkungan production. Langkah-langkahnya dijelaskan di bawah.

1. Menskalakan implementasi (produksi). Hal ini dijelaskan di bawah.
   1. Tambahkan iframe ke beberapa situs penayang.
2. Proses dan gunakan data topik (Perkiraan waktu: sekitar 4 minggu).
   1. Gabungkan data topik sebagai sinyal tambahan bersama data lainnya.
   2. Dapatkan partner pengujian bidding real-time.
   3. Jalankan pengujian utilitas dengan topik sebagai sinyal tambahan ke data Anda yang lain.

Menskalakan penerapan Anda

Pada tahap ini, Anda seharusnya memiliki data topik yang dikumpulkan dari beberapa situs dalam lingkungan yang terkontrol, dengan tingkat keyakinan yang lebih tinggi tentang keseluruhan solusi.

Sekarang saatnya untuk menskalakan implementasi ini dengan men-deploy kode yang sama ke lebih banyak situs target. Ini akan memungkinkan Anda mengamati lebih banyak pengguna, mengumpulkan lebih banyak data topik, dan memperdalam pemahaman tentang audiens.

Sebaiknya lakukan tindakan berikut:

1. Terapkan secara bertahap di seluruh situs Anda, terutama jika Anda memiliki volume traffic yang besar.
2. Lakukan pengujian beban untuk data topik Anda, sesuai dengan traffic yang diharapkan.
   1. Pastikan backend Anda dapat menangani panggilan dalam volume besar.
   2. Siapkan pengumpulan metrik dan log untuk analisis.
3. Segera setelah men-deploy Topics API, periksa metrik Anda untuk mendeteksi masalah pengguna akhir yang parah. Periksa terus metrik Anda secara rutin.
4. Jika terjadi gangguan atau perilaku tidak terduga, roll back deployment dan analisis log Anda untuk memahami dan memperbaiki masalah tersebut.

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.