Panduan developer Token Status Pribadi

Sebelumnya, cookie pihak ketiga telah digunakan untuk menyimpan dan menyampaikan informasi tentang status pengguna, seperti status login mereka, informasi tentang perangkat yang mereka gunakan, atau apakah mereka dikenal dan tepercaya. Misalnya, apakah pengguna telah login dengan SSO, apakah pengguna memiliki jenis perangkat kompatibel tertentu, atau apakah pengguna dikenal dan tepercaya. Dengan penghentian dukungan cookie pihak ketiga, banyak kasus penggunaan ini harus didukung dengan cara lain.

Token Status Pribadi menawarkan cara untuk membagikan informasi di seluruh web, tetapi dengan cara yang menjaga privasi melalui kontrol jumlah data yang benar-benar dapat dibagikan.

Token Status Pribadi (sebelumnya dikenal sebagai Token Kepercayaan) memungkinkan kepercayaan pada keaslian pengguna disampaikan dari satu konteks ke konteks lain sekaligus membantu situs memberantas penipuan dan membedakan bot dengan manusia sungguhan—tanpa pelacakan pasif.

Dokumen ini menguraikan detail teknis untuk menerapkan Token Status Pribadi (PST). Untuk mengetahui ringkasan yang lebih umum, lihat ringkasan PST.

Bagaimana cara kerja Token Status Pribadi?

Hubungan utama yang perlu dipahami dalam PST adalah antara penerbit dan penukaran. Penerbit dan penukaran dapat berada dalam perusahaan yang sama.

• Penerbit - Entitas ini memiliki beberapa sinyal tentang pengguna (misalnya, apakah pengguna tersebut adalah bot atau bukan) dan menyematkan sinyal tersebut ke dalam token yang disimpan di perangkat pengguna (detail selengkapnya di bagian berikutnya).
• Penebus - Entitas ini mungkin tidak memiliki sinyal tentang pengguna, tetapi perlu mengetahui sesuatu tentang mereka (misalnya, apakah pengguna tersebut adalah bot atau bukan) dan meminta untuk menukarkan token dari penerbit untuk memahami kepercayaan pengguna tersebut.

Setiap interaksi PST mengharuskan penerbit dan penukaran bekerja sama untuk berbagi sinyal di seluruh web. Sinyal tersebut adalah nilai kasar yang tidak cukup detail untuk mengidentifikasi individu.

Apakah Token Status Pribadi cocok untuk saya?

Perusahaan yang membuat keputusan kepercayaan dan ingin informasi tersebut tersedia di berbagai konteks dapat memanfaatkan PST. Untuk mengetahui informasi selengkapnya tentang potensi kasus penggunaan PST, lihat dokumentasi kami tentang kasus penggunaan PST.

Menerbitkan dan menukarkan token

Penerapan PST dilakukan dalam tiga fase:

1. Menerbitkan token
2. Menukarkan token
3. Penerusan data penukaran

Pada fase pertama, token dikeluarkan ke browser (biasanya setelah beberapa jenis validasi). Pada fase kedua, entitas lain akan membuat permintaan untuk menukarkan token yang telah diterbitkan untuk membaca nilai dalam token tersebut. Pada fase akhir, pihak penukaran menerima data penukaran (RR) dengan nilai yang terdapat dalam token. Pihak penukaran tersebut kemudian dapat menggunakan data tersebut sebagai pernyataan pengguna tersebut untuk berbagai tujuan.

Menentukan strategi token

Untuk menentukan strategi token, Anda perlu memahami konsep utama PST (token dan data penukaran), variabel, perilaku, dan batasan agar dapat memikirkan potensi penggunaannya untuk kasus penggunaan Anda.

Token dan data penukaran: apa hubungan di antara keduanya?

Setiap perangkat dapat menyimpan hingga 500 token per situs dan penerbit tingkat teratas. Selain itu, setiap token memiliki metadata yang menginformasikan kunci yang digunakan penerbit untuk menerbitkannya. Informasi tersebut dapat digunakan untuk memutuskan apakah akan menukarkan atau tidak token selama proses penukaran. Data PST disimpan secara internal oleh browser di perangkat pengguna dan hanya dapat diakses oleh PST API.

Saat token ditukarkan, Data Penukaran (RR) akan disimpan di perangkat. Penyimpanan ini berfungsi sebagai cache untuk penukaran di masa mendatang. Ada batas dua penukaran token setiap 48 jam, per perangkat, halaman, dan penerbit. Panggilan penukaran baru akan menggunakan RR yang di-cache jika memungkinkan, bukan menyebabkan permintaan ke penerbit.

1. Token baru akan diterbitkan (maks. 500 per penerbit, situs, dan perangkat).
2. Semua token disimpan di penyimpanan token perangkat (mirip dengan penyimpanan cookie).
3. Jika tidak ada RR aktif yang ditemukan, RR baru dapat dibuat setelah penerbitan (maksimum 2 setiap 48 jam).
4. RR dianggap aktif hingga masa berlaku habis dan akan digunakan sebagai cache lokal.
5. Panggilan penukaran baru akan masuk ke cache lokal (tidak ada RR baru yang dibuat).

Setelah menentukan kasus penggunaan, Anda harus menentukan masa aktif RR dengan cermat karena hal ini akan menentukan berapa kali Anda dapat menggunakannya dalam kasus Anda.

Pastikan Anda memahami perilaku dan variabel penting berikut sebelum menentukan strategi:

Contoh skenario

Skenario #1: Masa berlaku RR kurang dari 24 jam (t=t) dan penukaran dilakukan beberapa kali selama periode 48 jam.

Skenario #2: Masa berlaku RR adalah 24 jam dan penukaran dilakukan beberapa kali selama periode 48 jam.

Skenario #3: Masa berlaku RR adalah 48 jam dan penukaran dilakukan beberapa kali selama periode 48 jam.

Menjalankan demo

Sebelum mengadopsi PST, sebaiknya siapkan demo terlebih dahulu. Untuk mencoba demo PST , Anda harus menjalankan Chrome dengan flag untuk mengaktifkan komitmen kunci penerbit demo (ikuti petunjuk yang tersedia di halaman demo).

Dengan menjalankan demo ini, browser Anda menggunakan server penerbit dan redeemer demo untuk menyediakan dan menggunakan token.

Pertimbangan teknis

Demo akan berjalan dengan optimal jika Anda menerapkan langkah-langkah berikut:

• Pastikan Anda menghentikan semua instance Chrome sebelum menjalankan Chrome dengan flag.
• Jika Anda menjalankannya di komputer Windows, lihat panduan ini tentang cara meneruskan parameter ke biner yang dapat dieksekusi Chrome.
• Buka Chrome DevTools di bagian Applications > Storage > Private State Tokens saat menggunakan aplikasi demo untuk melihat token yang diterbitkan/ditukarkan oleh penerbit demo.

Menyiapkan untuk penerapan

Menjadi penerbit

Penerbit memainkan peran penting dalam PST. Fungsi ini menetapkan nilai ke token untuk menentukan apakah pengguna adalah bot atau bukan. Jika ingin memulai PST sebagai penerbit, Anda harus mendaftar dengan menyelesaikan Proses pendaftaran penerbit.

Untuk mengajukan permohonan menjadi penerbit, operator situs penerbit harus membuka masalah baru di repositori GitHub menggunakan template "Penerbit PST Baru". Ikuti panduan di repositori untuk mengisi masalah. Setelah diverifikasi, endpoint akan digabungkan ke repositori ini dan infrastruktur sisi server Chrome akan mulai mengambil kunci tersebut.

Server penerbit

Penerbit dan penukaran adalah aktor utama untuk PST; server dan token adalah alat utama untuk PST. Meskipun kami telah memberikan beberapa detail tentang token dan dalam dokumentasi GitHub, kami ingin menawarkan detail selengkapnya tentang server PST. Untuk menyiapkan sebagai penerbit PST, Anda harus menyiapkan server penerbit terlebih dahulu.

Men-deploy lingkungan: server penerbit

Untuk mengimplementasikan server penerbit token, Anda harus mem-build aplikasi sisi server Anda sendiri yang mengekspos endpoint HTTP.

Komponen penerbit terdiri dari dua modul utama: (1) server penerbit dan (2) penerbit token.

Seperti semua aplikasi yang ditampilkan di web, sebaiknya gunakan lapisan perlindungan tambahan ke server penerbit Anda.

1. Server penerbit: Dalam contoh implementasi, server penerbit kami adalah server Node.js yang menggunakan framework Express untuk menghosting endpoint HTTP Penerbit. Anda dapat melihat contoh kode di GitHub.

2. Penerbit token: Komponen kriptografi penerbit tidak memerlukan bahasa tertentu, tetapi karena persyaratan performa komponen ini, kami menyediakan implementasi C sebagai contoh, yang menggunakan library Boring SSL untuk mengelola token. Anda dapat menemukan contoh kode penerbit dan informasi selengkapnya tentang penginstalan di GitHub

3. Kunci: Komponen penerbit token menggunakan kunci EC kustom untuk mengenkripsi token. Kunci ini harus dilindungi dan disimpan di penyimpanan yang aman.

Persyaratan teknis untuk server penerbit

Sesuai dengan protokol, Anda harus menerapkan minimal dua endpoint HTTP di server penerbit:

• Key-commitment (misalnya, /.well-known/private-state-token/key-commitment): Endpoint ini adalah tempat detail kunci publik enkripsi Anda akan tersedia untuk browser guna mengonfirmasi bahwa server Anda sah.
  • Kode contoh
• Penerbitan token (misalnya, /.well-known/private-state-token/issuance): Endpoint penerbitan token tempat semua permintaan token akan ditangani. Endpoint ini akan menjadi titik integrasi untuk komponen penerbit token.
  • Kode contoh

Seperti yang disebutkan sebelumnya, karena traffic yang tinggi yang diperkirakan akan ditangani server ini, sebaiknya deploy server menggunakan infrastruktur yang skalabel (misalnya, di lingkungan cloud) agar dapat menyesuaikan backend berdasarkan permintaan variabel.

Mengirim panggilan ke server penerbit

Terapkan panggilan pengambilan situs ke stack penerbit Anda untuk menerbitkan token baru.

 // issuer request
    await fetch("/.well-known/private-state-token/issuance", {
      method: "POST",
      privateToken: {
        version: 1,
        operation: "token-request"
      }
    });

Lihat contoh kode.

Server redeemer

Anda harus menerapkan layanan penukaran token dengan mem-build aplikasi sisi server Anda sendiri. Tindakan ini akan memungkinkan Anda membaca token yang dikirim penerbit. Langkah-langkah berikut menguraikan cara menukarkan token serta cara membaca data penukaran yang terkait dengan token tersebut.

Anda dapat memilih untuk menjalankan penerbit dan penukaran di server yang sama (atau grup server).

Persyaratan teknis untuk server penukaran

Sesuai dengan protokol, Anda harus mengimplementasikan minimal dua endpoint HTTP untuk server penukaran:

• /.well-known/private-state-token/redemption: endpoint tempat semua penukaran token akan ditangani. Endpoint ini akan menjadi tempat komponen penebus token akan diintegrasikan
  • Kode contoh

Mengirim panggilan ke server penebus

Untuk menukarkan token, Anda harus menerapkan panggilan pengambilan situs ke stack penukaran untuk menukarkan token yang dikeluarkan sebelumnya.

    // redemption request
    await fetch("/.well-known/private-state-token/redemption", {
      method: "POST",
      privateToken: {
        version: 1,
        operation: "token-redemption",
        refreshPolicy: "none"
      }
    });

Lihat contoh kode.

Setelah menukarkan token, Anda dapat mengirim data penukaran (RR) dengan melakukan panggilan pengambilan lain:

    // attach redemption records from the issuers to the request
    await fetch("<DESTINATION_RESOURCE>", {
      method: "POST",
      privateToken: {
        version: 1,
        operation: "send-redemption-record",
        issuers: [<ISSUER_DOMAIN>]
      }
    });

Lihat contoh kode.

Men-deploy implementasi

Untuk menguji penerapan Anda, buka halaman web tempat panggilan penerbitan dilakukan terlebih dahulu dan pastikan token dibuat sesuai logika Anda. Verifikasi di backend Anda bahwa panggilan dilakukan sesuai dengan spesifikasi. Kemudian, buka halaman web tempat panggilan penukaran dilakukan dan pastikan bahwa RR dibuat, mengikuti logika Anda.

Deployment di dunia nyata

Sebaiknya pilih situs target yang merupakan bagian dari kasus penggunaan tertentu:

• Jumlah kunjungan bulanan yang sedikit (~ <1 juta kunjungan/bulan): Anda harus memulai dengan men-deploy API ke audiens kecil terlebih dahulu
• Anda memiliki dan mengontrolnya: Jika perlu, Anda dapat menonaktifkan penerapan dengan cepat tanpa persetujuan yang rumit
• Tidak lebih dari satu penerbit: Untuk membatasi jumlah token guna menyederhanakan pengujian.
• Tidak lebih dari dua penukaran: Anda perlu menyederhanakan pemecahan masalah jika terjadi masalah.

Kebijakan izin

Agar berfungsi dengan baik, PST API harus tersedia untuk halaman tingkat atas dan sub-resource apa pun yang menggunakan API.

Operasi permintaan token dikontrol oleh perintah private-state-token-issuance. Operasi token-redemption dan send-redemption-record dikontrol oleh perintah private-state-token-redemption. Di Chrome 132 dan yang lebih baru, daftar yang diizinkan untuk perintah ini ditetapkan ke * (semua origin) secara default. Artinya, fitur ini tersedia untuk halaman tingkat atas, iframe dengan origin yang sama, dan iframe lintas origin tanpa delegasi eksplisit.

Anda dapat memilih untuk tidak menggunakan penerbitan atau penukaran token PST untuk halaman tertentu di situs Anda dengan menyertakan private-state-token-issuance=() dan private-state-token-redemption=() di header Permissions-Policy untuk setiap halaman.

Anda juga dapat menggunakan header Permissions-Policy untuk mengontrol akses pihak ketiga ke PST. Sebagai parameter ke daftar origin header, gunakan self dan origin apa pun yang ingin Anda izinkan aksesnya ke API. Misalnya, untuk sepenuhnya menonaktifkan penggunaan PST dalam semua konteks penjelajahan kecuali untuk origin dan https://example.com Anda sendiri, tetapkan header respons HTTP berikut:

Permissions-Policy:private-state-token-issuance=(self "https://example.com"),private-state-token-redemption=(self "https://example.com")

Untuk mengaktifkan API bagi semua resource lintas-asal, tetapkan daftar origin ke *.

Pelajari cara mengontrol fitur Privacy Sandbox dengan Kebijakan Izin atau pelajari lebih lanjut Kebijakan Izin.

Pemecahan masalah

Anda dapat memeriksa PST dari tab Jaringan dan Aplikasi Chrome DevTools.

Di tab Jaringan:

Di tab Aplikasi:

Baca selengkapnya tentang integrasi DevTools ini.

Praktik terbaik klien

Jika fungsi penting situs Anda bergantung pada penerbit token tertentu, prioritaskan fungsi tersebut. Panggil hasPrivateToken(issuer) untuk penerbit pilihan ini sebelum memuat skrip lainnya. Hal ini sangat penting untuk mencegah kemungkinan kegagalan penukaran.

Jumlah penerbit per tingkat teratas dibatasi hingga dua, dan skrip pihak ketiga juga dapat mencoba memanggil hasPrivateToken(issuer) untuk memprioritaskan penerbit pilihan mereka sendiri. Jadi, amankan penerbit penting Anda terlebih dahulu untuk memastikan situs Anda beroperasi seperti yang diharapkan.

  // Prioritize your critical token issuer.
  document.hasPrivateToken('https://critical-issuer.example')
    .then(hasToken => {
      if (hasToken) {
        // Use the token or perform actions based on its availability.
      } else {
        // Handle the case where the token is not available.
      }
    });

  // Load third-party scripts or secure another token issuer (up to two in total).

Praktik terbaik dan pemecahan masalah server

Agar server penerbit dan penukaran Anda beroperasi secara efektif, sebaiknya terapkan praktik terbaik berikut untuk memastikan Anda tidak mengalami tantangan akses, keamanan, logging, atau traffic untuk PST.

• Endpoint Anda harus menerapkan kriptografi yang kuat dengan menggunakan TLS 1.3 atau 1.2.
• Infrastruktur Anda harus siap menangani volume traffic yang bervariasi (termasuk lonjakan).
• Pastikan kunci Anda dilindungi dan aman, selaras dengan Kebijakan Kontrol Akses, Strategi Pengelolaan Kunci, dan Rencana Kelangsungan Bisnis Anda.
• Tambahkan metrik visibilitas ke stack untuk memastikan Anda akan memiliki visibilitas untuk memahami penggunaan, bottleneck, dan masalah performa setelah melakukan produksi.

Informasi selengkapnya

1. Tinjau dokumen developer:
   1. Mulailah dengan membaca ringkasan untuk memahami PST dan kemampuannya.
   2. Tonton video pengantar PST.
   3. Coba demo PST.
   4. Baca juga penjelasan API untuk memahami detail selengkapnya tentang API tersebut.
   5. Baca selengkapnya tentang spesifikasi saat ini API.
2. Berkontribusilah pada percakapan melalui masalah GitHub atau panggilan W3C.
3. Untuk lebih memahami terminologi apa pun, tinjau glosarium Privacy Sandbox.
4. Untuk mempelajari konsep Chrome lebih lanjut, seperti 'uji coba origin' atau 'flag Chrome', tonton video singkat dan baca artikel yang tersedia di goo.gle/cc.