Panduan Memulai Penerapan Penyimpanan Bersama dan Agregasi Pribadi

Dokumen ini adalah panduan memulai untuk menggunakan Penyimpanan Bersama dan Agregasi Pribadi. Anda akan memerlukan pemahaman tentang kedua API karena Shared Storage menyimpan nilai dan Agregasi Pribadi membuat laporan agregat.

Target Audiens: Penyedia teknologi iklan dan pengukuran.

Coba demo

Coba demo langsung. Ikuti langkah-langkah dalam petunjuk demo untuk mengaktifkan Privacy Sandbox API. Membuka Chrome DevTools membantu Anda memvisualisasikan hasil berbagai kasus penggunaan. Kasus penggunaan yang tersedia dalam demo:

• Agregasi Pribadi
  • Pengukuran Jangkauan Unik
  • Pengukuran demografi
  • Pengukuran frekuensi K+
• Penggunaan Umum
  • Mengukur peristiwa pengarahan kursor di dalam frame dengan fence
  • Navigasi tingkat atas
  • Mengontrol tempat pihak ketiga dapat menulis

Cara melihat Penyimpanan Bersama

Untuk melihat apa yang disimpan di Penyimpanan Bersama, gunakan Chrome DevTools. Data yang disimpan dapat ditemukan di Application -> Shared Storage.

Melihat laporan untuk Agregasi Pribadi

Untuk melihat laporan gabungan yang dikirim, buka chrome://private-aggregation-internals. Jika mode debug diaktifkan, laporan akan segera dikirim (tanpa penundaan) ke [[YOUR_ORIGIN]]/.well-known/private-aggregation/debug/report-shared-storage beserta laporan penundaan waktu yang akan dikirim ke [[YOUR_ORIGIN]]/.well-known/private-aggregation/report-shared-storage.

Untuk mengaktifkan proses debug, ikuti petunjuk di bagian proses debug.

API Penyimpanan Bersama

Untuk mencegah pelacakan lintas situs, browser mulai mempartisi semua bentuk penyimpanan, termasuk penyimpanan lokal, cookie, dan sebagainya. Namun, ada kasus penggunaan yang diperlukan untuk penyimpanan tanpa partisi. Shared Storage API memberikan akses tulis tanpa batas di berbagai situs tingkat teratas dengan akses baca yang menjaga privasi.

Shared Storage dibatasi pada asal konteks (pemanggil sharedStorage).

Shared Storage memiliki batas kapasitas per origin, dengan setiap entri dibatasi hingga jumlah karakter maksimum. Jika batas ini tercapai, input lebih lanjut tidak akan disimpan. Batas penyimpanan data diuraikan dalam penjelasan Penyimpanan Bersama.

Memanggil Penyimpanan Bersama

Teknologi iklan dapat menulis ke Penyimpanan Bersama menggunakan JavaScript atau header respons. Pembacaan dari Shared Storage hanya terjadi dalam lingkungan JavaScript terisolasi yang disebut worklet.

Dengan worklet, Anda dapat menjalankan fungsi JavaScript tertentu dan menampilkan informasi kembali ke pemohon. Dalam worklet, Anda dapat menjalankan JavaScript, tetapi tidak dapat berinteraksi atau berkomunikasi dengan halaman di luar.

Worklet digunakan untuk menyimpan dan mengekstrak data dengan Shared Storage API.

• Menggunakan JavaScript Teknologi iklan dapat menjalankan fungsi Penyimpanan Bersama tertentu seperti menetapkan, menambahkan, dan menghapus nilai di luar worklet JavaScript. Namun, fungsi seperti membaca Shared Storage dan melakukan Agregasi Pribadi harus diselesaikan melalui worklet JavaScript. Metode yang dapat digunakan di luar worklet JavaScript dapat ditemukan di Platform API yang Diusulkan - Di luar worklet.

  Metode yang digunakan dalam worklet selama operasi dapat ditemukan di Permukaan API yang Diusulkan - Di worklet.

• Menggunakan header respons

  Fitur ini tersedia di M119.

  Mirip dengan JavaScript, hanya fungsi tertentu seperti menyetel, menambahkan, dan menghapus nilai di Penyimpanan Bersama yang dapat dilakukan menggunakan header respons. Agar dapat menggunakan Shared Storage dalam header respons, Shared-Storage-Writable: ?1 harus disertakan dalam header permintaan.

  Untuk memulai permintaan dari klien, jalankan kode berikut, bergantung pada metode yang Anda pilih:

  • Menggunakan fetch()

    fetch("https://a.example/path/for/updates", {sharedStorageWritable: true});
    

  • Menggunakan tag iframe atau img

    <iframe src="https://a.example/path/for/updates" sharedstoragewritable></iframe>
    

  • Menggunakan atribut IDL dengan tag iframe atau img

    let iframe = document.getElementById("my-iframe");
    iframe.sharedStorageWritable = true;
    iframe.src = "https://a.example/path/for/updates";
    

Informasi selengkapnya dapat ditemukan di Penyimpanan Bersama: Header Respons.

Menulis ke Penyimpanan Bersama

Untuk menulis ke Shared Storage, panggil sharedStorage.set() dari dalam atau luar worklet JavaScript. Jika dipanggil dari luar worklet, data akan ditulis ke asal konteks penjelajahan tempat panggilan dibuat. Jika dipanggil dari dalam worklet, data akan ditulis ke asal konteks penjelajahan yang memuat worklet. Kunci yang ditetapkan memiliki tanggal habis masa berlaku 30 hari sejak pembaruan terakhir.

Kolom ignoreIfPresent bersifat opsional. Jika ada dan ditetapkan ke true, kunci tidak akan diupdate jika sudah ada. Masa berlaku kunci diperpanjang menjadi 30 hari dari panggilan set() meskipun kunci tidak diperbarui.

Jika Shared Storage diakses beberapa kali dalam pemuatan halaman yang sama dengan kunci yang sama, nilai untuk kunci tersebut akan ditimpa. Sebaiknya gunakan sharedStorage.append() jika kunci perlu mempertahankan nilai sebelumnya.

• Menggunakan JavaScript

  Di luar worklet:

  window.sharedStorage.set('myKey', 'myValue1', { ignoreIfPresent: true });
  // Shared Storage: {'myKey': 'myValue1'}
  window.sharedStorage.set('myKey', 'myValue2', { ignoreIfPresent: true });
  // Shared Storage: {'myKey': 'myValue1'}
  window.sharedStorage.set('myKey', 'myValue2', { ignoreIfPresent: false });
  // Shared Storage: {'myKey': 'myValue2'}
  

  Demikian pula, di dalam worklet:

  sharedStorage.set('myKey', 'myValue1', { ignoreIfPresent: true });
  

• Menggunakan header respons

  Anda juga dapat menulis ke Shared Storage menggunakan header respons. Untuk melakukannya, gunakan Shared-Storage-Write di header respons bersama dengan perintah berikut:

  Shared-Storage-Write : set;key="myKey";value="myValue";ignore_if_present
  

  Shared-Storage-Write : set;key="myKey";value="myValue";ignore_if_present=?0
  

  Beberapa item dapat dipisahkan koma dan dapat menggabungkan set, append, delete, dan clear.

  Shared-Storage-Write : 
  set;key="hello";value="world";ignore_if_present, set;key="good";value="bye"
  

Menambahkan nilai

Anda dapat menambahkan nilai ke kunci yang ada menggunakan metode penambahan. Jika kunci tidak ada, memanggil append() akan membuat kunci dan menetapkan nilainya. Hal ini dapat dilakukan menggunakan JavaScript atau header respons.

• Menggunakan JavaScript

  Untuk memperbarui nilai kunci yang ada, gunakan sharedStorage.append() dari dalam atau luar worklet.

  window.sharedStorage.append('myKey', 'myValue1');
  // Shared Storage: {'myKey': 'myValue1'}
  window.sharedStorage.append('myKey', 'myValue2');
  // Shared Storage: {'myKey': 'myValue1myValue2'}
  window.sharedStorage.append('anotherKey', 'hello');
  // Shared Storage: {'myKey': 'myValue1myValue2', 'anotherKey': 'hello'}
  

  Untuk menambahkan ke dalam worklet:

  sharedStorage.append('myKey', 'myValue1');
  

• Menggunakan header respons

  Serupa dengan menetapkan nilai di Shared Storage, Anda dapat menggunakan Shared-Storage-Write di header respons untuk meneruskan key-value pair.

  Shared-Storage-Write : append;key="myKey";value="myValue2"
  

Membaca dari Penyimpanan Bersama

Anda dapat membaca dari Penyimpanan Bersama hanya dari dalam worklet.

await sharedStorage.get('mykey');

Asal konteks penjelajahan tempat modul worklet dimuat akan menentukan penyimpanan Bersama yang dibaca.

Menghapus dari Penyimpanan Bersama

Anda dapat menghapus dari Shared Storage menggunakan JavaScript, baik dari dalam atau luar worklet atau dengan menggunakan header respons dengan delete(). Untuk menghapus semua kunci sekaligus, gunakan clear() dari salah satu kunci.

• Menggunakan JavaScript

  Untuk menghapus dari Penyimpanan Bersama dari luar worklet:

  window.sharedStorage.delete('myKey');
  

  Untuk menghapus dari Penyimpanan Bersama dari dalam worklet:

  sharedStorage.delete('myKey');
  

  Untuk menghapus semua kunci sekaligus dari luar worklet:

  window.sharedStorage.clear();
  

  Untuk menghapus semua kunci sekaligus dari dalam worklet:

  sharedStorage.clear();
  

• Menggunakan header respons

  Untuk menghapus nilai menggunakan header respons, Anda juga dapat menggunakan Shared-Storage-Write di header respons untuk meneruskan kunci yang akan dihapus.

  delete;key="myKey"
  

  Untuk menghapus semua kunci menggunakan header respons:

  clear;
  

Pengalihan konteks

Data Penyimpanan Bersama ditulis ke origin (misalnya, https://example.adtech.com) dalam konteks penjelajahan tempat panggilan berasal.

Saat Anda memuat kode pihak ketiga menggunakan tag <script>, kode akan dieksekusi dalam konteks penjelajahan penyemat. Oleh karena itu, saat kode pihak ketiga memanggil sharedStorage.set(), data akan ditulis ke Penyimpanan Bersama embeddings. Saat Anda memuat kode pihak ketiga dalam iframe, kode tersebut akan menerima konteks penjelajahan baru, dan asalnya adalah asal iframe. Oleh karena itu, panggilan sharedStorage.set() yang dilakukan dari iframe menyimpan data ke dalam Penyimpanan Bersama asal iframe.

Konteks pihak pertama

Jika halaman pihak pertama telah menyematkan kode JavaScript pihak ketiga yang memanggil sharedStorage.set() atau sharedStorage.delete(), key-value pair akan disimpan dalam konteks pihak pertama.

Konteks pihak ketiga

Pasangan nilai kunci dapat disimpan dalam konteks teknologi iklan atau pihak ketiga dengan membuat iframe dan memanggil set() atau delete() dalam kode JavaScript dari dalam iframe.

API Agregasi Pribadi

Untuk mengukur data gabungan yang disimpan di Shared Storage, Anda dapat menggunakan Private Aggregation API.

Untuk membuat laporan, panggil contributeToHistogram() di dalam worklet dengan bucket dan nilai. Bucket direpresentasikan oleh bilangan bulat 128-bit tanpa tanda tangan, yang harus diteruskan ke fungsi sebagai BigInt. Nilainya adalah bilangan bulat positif.

Untuk melindungi privasi, payload laporan, yang berisi bucket dan nilai, dienkripsi saat dalam pengiriman, dan hanya dapat didekripsi dan digabungkan menggunakan Layanan Agregasi.

Browser juga akan membatasi kontribusi yang dapat dibuat situs ke kueri output. Secara khusus, anggaran kontribusi membatasi total semua laporan dari satu situs untuk browser tertentu dalam jangka waktu tertentu di semua bucket. Jika anggaran saat ini terlampaui, laporan tidak akan dibuat.

privateAggregation.contributeToHistogram({
  bucket: BigInt(myBucket),
  value: parseInt(myBucketValue)
});

Menjalankan Penyimpanan Bersama dan Agregasi Pribadi

Di iframe iklan, muat modul worklet dengan memanggil addModule(). Untuk menjalankan metode yang terdaftar dalam file worklet sharedStorageWorklet.js, dalam JavaScript iframe iklan yang sama, panggil sharedStorage.run().

await window.sharedStorage.worklet.addModule('modules/sharedStorageWorklet.js');
await window.sharedStorage.worklet.run('shared-storage-report', {
  data: { campaignId: '1234' },
});

Dalam skrip worklet, Anda harus membuat class dengan metode run asinkron. Dan register class ini untuk dijalankan di iframe iklan. Di dalam sharedStorageWorklet.js:

class SharedStorageReportOperation {
  async run(data) {
    // Other code goes here.
    bucket = getBucket(...);
    value = getValue(...);
    privateAggregation.contributeToHistogram({
      bucket: bucket,
      value: value
    });
  }
}
register('shared-storage-report',
  SharedStorageReportOperation);

Proses debug

Untuk mengaktifkan proses debug, panggil metode JavaScript enableDebugMode() dalam konteks yang sama tempat Shared Storage dan Agregasi Pribadi digunakan. Hal ini akan diterapkan untuk laporan mendatang dalam konteks yang sama.

privateAggregation.enableDebugMode();

Untuk mengaitkan laporan dengan konteks yang memicunya, Anda dapat menyetel kunci debug bilangan bulat tanpa tanda tangan 64-bit yang diteruskan ke panggilan JavaScript. debugKey adalah BigInt.

privateAggregation.enableDebugMode({debugKey: 1234});

Men-debug Penyimpanan Bersama

Penyimpanan Bersama menampilkan pesan error umum:

Promise is rejected without and explicit error message

Anda dapat men-debug Penyimpanan Bersama dengan menggabungkan panggilan dengan blok try-catch.

try {
  privateAggregation.contributeToHistogram({bucket, value});
} catch (e){
  console.log(e);
}

Men-debug Agregasi Pribadi

Laporan dikirim ke /.well-known/private-aggregation/report-shared-storage dan /.well-known/private-aggregation/debug/report-shared-storage. Laporan debug menerima payload yang mirip dengan JSON berikut. Payload ini menentukan kolom api sebagai "penyimpanan bersama".

{
   "aggregation_coordinator_identifier": "aws-cloud",
   "aggregation_service_payloads": [ {
      "debug_cleartext_payload": "omRkYXRhgaJldmFsdWVEAAAAgGZidWNrZXRQAAAAAAAAAAAAAAEfV32BFWlvcGVyYXRpb25paGlzdG9ncmFt",
      "key_id": "9bc4afa7-2934-4779-99ff-999d91b137ec",
      "payload": "bqOFO/cHCdwefU2W4FjMYRMSLoGHPWwZbgVF4aa/ji2YtwFz+jb6v2XCwQUdmvYcZSRPKosGRpKELJ0xAFv+VBYvCiv3FXP6jjAHQD+XAJUz17A39aXijk6JnEAu86+DfTSbXYn1fWhGzIG9xH/Y"
   } ],
   "debug_key": "1234",
   "shared_info": "{\"api\":\"shared-storage\",\"debug_mode\":\"enabled\",\"report_id\":\"93f86829-cdf7-4ecd-b16d-4e415a3ee063\",\"reporting_origin\":\"https://small-free-wealth.glitch.me\",\"scheduled_report_time\":\"1681319668\",\"version\":\"0.1\"}"
}

Men-debug payload cleartext

debug_cleartext_payload dienkode Base64 CBOR. Anda dapat melihat bucket dan nilai menggunakan dekoder atau menggunakan kode JavaScript yang ada di dekoder Shared Storage.

Langkah berikutnya

Halaman berikut menjelaskan aspek penting dari Shared Storage dan Private Aggregation API.

• Pengantar Penyimpanan Bersama (Chrome Developer)
• Kasus Penggunaan Penyimpanan Bersama (Chrome Developer)
• Pengantar Agregasi Pribadi (Chrome Developer)
• Penjelasan Penyimpanan Bersama (GitHub)
• Penjelasan Private Aggregation (GitHub)
• Demo Penyimpanan Bersama dan Agregasi Pribadi

Setelah memahami API, Anda dapat mulai mengumpulkan laporan, yang dikirim sebagai permintaan POST ke endpoint berikut sebagai JSON dalam isi permintaan.

• Laporan Debug - context-origin/.well-known/private-aggregation/debug/report-shared-storage
• Laporan - context-origin/.well-known/private-aggregation/report-shared-storage

Setelah laporan dikumpulkan, Anda dapat mengujinya menggunakan alat pengujian lokal atau menyiapkan Trusted Execution Environment untuk Layanan Agregasi untuk mendapatkan laporan gabungan.

Bagikan masukan

Anda dapat memberikan masukan tentang API dan dokumentasi di GitHub.

• Penyimpanan Bersama
• Agregasi Pribadi