Panduan Memulai Penerapan Penyimpanan Bersama dan Agregasi Pribadi

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

Target Audiens: Teknologi iklan dan penyedia pengukuran.

Shared Storage API

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

Penyimpanan Bersama dibatasi untuk asal konteks (pemanggil sharedStorage).

Penyimpanan Bersama memiliki batas kapasitas per asal, dengan setiap entri dibatasi hingga jumlah karakter maksimum. Jika batas tercapai, tidak ada input lebih lanjut yang 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 Penyimpanan Bersama 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 melakukan fungsi Penyimpanan Bersama tertentu seperti menyetel, 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 Diajukan - Di luar worklet.

  Metode yang digunakan dalam worklet selama operasi dapat ditemukan di Proposed API Surface - In the worklet.

• Menggunakan header respons

  Serupa dengan JavaScript, hanya fungsi tertentu seperti menetapkan, menambahkan, dan menghapus nilai di Shared Storage yang dapat dilakukan menggunakan header respons. Agar dapat menggunakan Penyimpanan Bersama di 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 lebih lanjut dapat ditemukan di Penyimpanan Bersama: Header Respons.

Menulis ke Penyimpanan Bersama

Untuk menulis ke Penyimpanan Bersama, panggil sharedStorage.set() dari dalam atau luar worklet JavaScript. Jika dipanggil dari luar worklet, data akan ditulis ke asal konteks penjelajahan tempat panggilan dilakukan. 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 diperbarui jika sudah ada. Masa berlaku kunci diperpanjang menjadi 30 hari sejak panggilan set() meskipun kunci tidak diperbarui.

Jika Penyimpanan Bersama diakses beberapa kali dalam pemuatan halaman yang sama dengan kunci yang sama, nilai untuk kunci 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 Penyimpanan Bersama menggunakan header respons. Untuk melakukannya, gunakan Shared-Storage-Write di header respons beserta 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 sudah ada menggunakan metode add. Jika kunci tidak ada, memanggil append() akan membuat kunci dan menetapkan nilai. 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 di dalam worklet:

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

• Menggunakan header respons

  Serupa dengan menetapkan nilai di Penyimpanan Bersama, Anda dapat menggunakan Shared-Storage-Write di header respons untuk meneruskan pasangan nilai kunci.

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

Membaca dari Penyimpanan Bersama

Anda hanya dapat membaca dari Penyimpanan Bersama dari dalam worklet.

await sharedStorage.get('mykey');

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

Menghapus dari Penyimpanan Bersama

Anda dapat melakukan penghapusan dari Penyimpanan Bersama menggunakan JavaScript dari dalam atau luar worklet atau dengan menggunakan header respons dengan delete(). Untuk menghapus semua kunci sekaligus, gunakan clear() dari salah satu kunci tersebut.

• 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;
  

Peralihan konteks

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

Saat Anda memuat kode pihak ketiga menggunakan tag <script>, kode akan dijalankan dalam konteks penjelajahan penyempan. Oleh karena itu, saat kode pihak ketiga memanggil sharedStorage.set(), data akan ditulis ke Penyimpanan Bersama penyemat. 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 dibuat 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(), pasangan nilai kunci 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.

Private Aggregation API

Untuk mengukur data agregat yang disimpan di Penyimpanan Bersama, 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 label yang harus diteruskan ke fungsi sebagai BigInt. Nilainya adalah bilangan bulat positif.

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

Browser juga akan membatasi kontribusi yang dapat dilakukan 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 Shared Storage dan Private Aggregation

Anda harus membuat worklet untuk mengakses data dari penyimpanan bersama. Untuk melakukannya, panggil createWorklet() dengan URL worklet. Secara default, saat menggunakan penyimpanan bersama dengan createWorklet(), asal partisi data akan memanggil asal konteks penjelajahan, bukan asal skrip worklet itu sendiri.

Untuk mengubah perilaku default, tetapkan properti dataOrigin saat memanggil createWorklet.

• dataOrigin: "context-origin": (Default) Data disimpan dalam penyimpanan bersama asal konteks penjelajahan yang memanggil.
• dataOrigin: "script-origin": Data disimpan di penyimpanan bersama asal skrip worklet. Perhatikan bahwa Anda harus mengaktifkan mode ini.

sharedStorage.createWorklet(scriptUrl, {dataOrigin: "script-origin"});

Untuk ikut serta, saat menggunakan "script-origin", endpoint skrip harus merespons dengan header Shared-Storage-Cross-Origin-Worklet-Allowed. Perhatikan bahwa CORS harus diaktifkan untuk permintaan lintas-asal.

Shared-Storage-Cross-Origin-Worklet-Allowed : ?1

Menetapkan `dataOrigin` di `createWorklet()` dan membuat worklet lintas origin dengan `addModule()` tersedia di M130.

Menggunakan iframe lintas origin

Iframe diperlukan untuk memanggil worklet penyimpanan bersama.

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

const sharedStorageWorklet = await window.sharedStorage.createWorklet(
  'https://any-origin.example/modules/sharedStorageWorklet.js'
);
await sharedStorageWorklet.run('shared-storage-report', {
  data: { campaignId: '1234' },
});

Dalam skrip worklet, Anda harus membuat class dengan metode run asinkron dan register 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,
      value
    });
  }
}
register('shared-storage-report', SharedStorageReportOperation);

Menggunakan permintaan lintas origin

Penyimpanan Bersama dan Agregasi Pribadi memungkinkan pembuatan worklet lintas origin tanpa memerlukan iframe lintas origin.

Halaman pihak pertama juga dapat memanggil panggilan createWorklet() ke endpoint JavaScript lintas origin. Anda harus menetapkan asal partisi data worklet menjadi asal skrip saat membuat worklet.

async function crossOriginCall() {
  const privateAggregationWorklet = await sharedStorage.createWorklet(
    'https://cross-origin.example/js/worklet.js',
    { dataOrigin: 'script-origin' }
  );
  await privateAggregationWorklet.run('pa-worklet');
}
crossOriginCall();

Endpoint JavaScript lintas asal harus merespons dengan header Shared-Storage-Cross-Origin-Worklet-Allowed dan perhatikan bahwa CORS diaktifkan untuk permintaan.

Shared-Storage-Cross-Origin-Worklet-Allowed : ?1

Worklet yang dibuat menggunakan createWorklet() akan memiliki selectURL dan run(). addModule() tidak tersedia untuk ini.

Catatan: addModule() dapat digunakan untuk membuat worklet lintas origin. Namun, penggunaan createWorklet() lebih disarankan karena memungkinkan pembuatan partisi data lintas origin, dan dapat membuat beberapa worklet, tidak seperti addModule().

class CrossOriginWorklet {
  async run(data){
    // Other code goes here.
    bucket = getBucket(...);
    value = getValue(...);
    privateAggregation.contributeToHistogram({
      bucket,
      value
    });
  }
}

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)
• Private Aggregation Explainer (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 menguji menggunakan alat pengujian lokal atau menyiapkan Trusted Execution Environment for Aggregation Service untuk mendapatkan laporan gabungan.

Beri masukan

Anda dapat membagikan masukan tentang API dan dokumentasi di GitHub.

• Shared Storage
• Agregasi Pribadi