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 menjalankan fungsi Penyimpanan Bersama tertentu seperti menetapkan, menambahkan, dan menghapus nilai di luar worklet JavaScript. Namun, fungsi seperti membaca Penyimpanan Bersama dan melakukan Agregasi Pribadi harus diselesaikan melalui worklet JavaScript. Metode yang dapat digunakan di luar worklet JavaScript dapat ditemukan di Proposed API Surface - Outside the 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 bekerja dengan Shared Storage 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 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 tambahan. 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 Shared Storage, Anda dapat menggunakan Shared-Storage-Write di header respons untuk meneruskan pasangan nilai kunci.

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

Pembaruan nilai secara batch

Anda dapat memanggil sharedStorage.batchUpdate() dari dalam atau di luar worklet JavaScript dan meneruskan array metode yang diurutkan yang menentukan operasi yang dipilih. Setiap konstruktor metode menerima parameter yang sama dengan metode individual yang sesuai untuk menetapkan, menambahkan, menghapus, dan menghapus.

Anda dapat menyetel kunci menggunakan JavaScript atau header respons:

• Menggunakan JavaScript

  Metode JavaScript yang tersedia dan dapat digunakan dengan batchUpdate() meliputi:

  • SharedStorageSetMethod(): Menulis pasangan nilai kunci ke Penyimpanan Bersama.
  • SharedStorageAppendMethod(): Menambahkan nilai ke kunci yang ada di Penyimpanan Bersama.
  • SharedStorageDeleteMethod(): Menghapus pasangan nilai kunci dari Penyimpanan Bersama.
  • SharedStorageClearMethod(): Menghapus semua kunci di Penyimpanan Bersama.

  sharedStorage.batchUpdate([
  new SharedStorageSetMethod('keyOne', 'valueOne'),
  new SharedStorageAppendMethod('keyTwo', 'valueTwo'),
  new SharedStorageDeleteMethod('keyThree'),
  new SharedStorageClearMethod()
  ]);
  

• Menggunakan header respons

  Shared-Storage-Write : batchUpdate;methods="set;key=keyOne;value=valueOne, append;key=keyTwo;value=valueTwo,delete;key=keyThree,clear"
  

Catatan: Menggunakan opsi withLock dengan batchUpdate() hanya berlaku untuk seluruh batch, withLock pada setiap objek metode dalam batch akan diabaikan.

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.

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

Membaca grup minat Protected Audience dari Shared Storage

Anda dapat membaca grup minat Protected Audience dari worklet Penyimpanan Bersama. Metode interestGroups() menampilkan array objek StorageInterestGroup, termasuk atribut AuctionInterestGroup dan GenerateBidInterestGroup.

Contoh berikut menunjukkan cara membaca grup minat konteks penjelajahan dan beberapa kemungkinan operasi yang dapat dilakukan pada grup minat yang diambil. Dua kemungkinan operasi yang digunakan adalah menemukan jumlah grup minat dan menemukan grup minat dengan jumlah bid tertinggi.

async function analyzeInterestGroups() {
  const interestGroups = await interestGroups();
  numIGs = interestGroups.length;
  maxBidCountIG = interestGroups.reduce((max, cur) => { return cur.bidCount > max.bidCount ? cur : max; }, interestGroups[0]);
  console.log("The IG that bid the most has name " + maxBidCountIG.name);
}

Asal konteks penjelajahan tempat modul worklet dimuat menentukan asal grup minat yang dibaca secara default. Untuk mempelajari lebih lanjut asal worklet default dan cara mengubahnya, tinjau bagian Menjalankan Shared Storage dan Private Aggregation di Panduan Shared Storage API.

Opsi

Semua metode pengubah Shared Storage mendukung objek opsi opsional sebagai argumen terakhir.

withLock

Opsi withLock bersifat opsional. Jika ditentukan, opsi ini akan menginstruksikan metode untuk mendapatkan kunci untuk resource yang ditentukan menggunakan Web Locks API sebelum melanjutkan. Nama kunci diteruskan saat meminta kunci. Nama ini mewakili resource yang penggunaannya dikoordinasikan di beberapa tab, pekerja, atau kode dalam origin.

Opsi withLock dapat digunakan dengan metode pengubah Penyimpanan Bersama berikut:

• set
• append
• hapus
• hapus
• kumpulan update

Anda dapat menyetel kunci menggunakan JavaScript atau header respons:

• Menggunakan JavaScript

  sharedStorage.set('myKey', 'myValue', { withLock: 'myResource' });
  

• Menggunakan header respons

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

Kunci Penyimpanan Bersama dipartisi menurut asal data. Kunci ini tidak bergantung pada kunci apa pun yang diperoleh menggunakan metode request() LockManager, terlepas dari apakah kunci tersebut berada dalam konteks window atau worker. Namun, keduanya memiliki cakupan yang sama dengan kunci yang diperoleh menggunakan request() dalam konteks SharedStorageWorklet.

Meskipun metode request() memungkinkan berbagai opsi konfigurasi, kunci yang diperoleh dalam Penyimpanan Bersama selalu mematuhi setelan default berikut:

• mode: "exclusive": Tidak ada kunci lain dengan nama yang sama yang dapat ditahan secara serentak.
• steal: false: Kunci yang ada dengan nama yang sama tidak akan dirilis untuk mengakomodasi permintaan lain.
• ifAvailable: false: Permintaan menunggu tanpa batas waktu hingga kunci tersedia.

Kapan menggunakan withLock

Kunci berguna dalam skenario saat mungkin ada beberapa worklet yang berjalan secara bersamaan (misalnya, beberapa worklet di halaman, atau beberapa worklet di tab yang berbeda) yang masing-masing melihat data yang sama. Dalam skenario tersebut, sebaiknya gabungkan kode worklet yang relevan dengan kunci untuk memastikan bahwa hanya satu worklet yang memproses laporan dalam satu waktu.

Situasi lain yang berguna untuk kunci adalah jika ada beberapa kunci yang perlu dibaca bersama dalam worklet, dan statusnya harus disinkronkan. Dalam hal ini, Anda harus menggabungkan panggilan get dengan kunci, dan pastikan untuk mendapatkan kunci yang sama saat menulis ke kunci tersebut.

Urutan kunci

Karena sifat kunci web, metode pengubah mungkin tidak dieksekusi dalam urutan yang Anda tentukan. Jika operasi pertama memerlukan kunci dan tertunda, operasi kedua dapat dimulai sebelum operasi pertama selesai.

Misalnya:

// This line might pause until the lock is available.
sharedStorage.set('keyOne', 'valueOne', { withLock: 'resource-lock' });

// This line will run right away, even if the first one is still waiting.
sharedStorage.set('keyOne', 'valueTwo');

Contoh mengubah beberapa kunci

Contoh ini menggunakan kunci untuk memastikan bahwa operasi baca dan hapus dalam worklet terjadi secara bersamaan, sehingga mencegah gangguan dari luar worklet.

Contoh modify-multiple-keys.js berikut menetapkan nilai baru untuk keyOne dan keyTwo dengan modify-lock, lalu menjalankan operasi modify-multiple-keys dari worklet:

// modify-multiple-keys.js
sharedStorage.batchUpdate([
    new SharedStorageSetMethod('keyOne', calculateValueFor('keyOne')),
    new SharedStorageSetMethod('keyTwo', calculateValueFor('keyTwo'))
], { withLock: 'modify-lock' });

const modifyWorklet = await sharedStorage.createWorklet('modify-multiple-keys-worklet.js');
await modifyWorklet.run('modify-multiple-keys');

Kemudian, dalam modify-multiple-keys-worklet.js, Anda dapat meminta kunci menggunakan navigator.locks.request() untuk membaca dan mengubah kunci sesuai kebutuhan

// modify-multiple-keys-worklet.js
class ModifyMultipleKeysOperation {
  async run(data) {
    await navigator.locks.request('modify-lock', async (lock) => {
      const value1 = await sharedStorage.get('keyOne');
      const value2 = await sharedStorage.get('keyTwo');

      // Do something with `value1` and `value2` here.

      await sharedStorage.delete('keyOne');
      await sharedStorage.delete('keyTwo');
    });
  }
}
register('modify-multiple-keys', ModifyMultipleKeysOperation);

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 Shared Storage 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 Shared Storage, Anda dapat menggunakan Private Aggregation API.

Untuk membuat laporan, panggil contributeToHistogram() di dalam worklet dengan bucket dan nilai. Bucket diwakili oleh bilangan bulat 128-bit tanpa tanda 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 periode 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 menjadi 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 umum 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 API Agregasi Pribadi dan Penyimpanan Bersama.

• Pengantar Penyimpanan Bersama (Chrome Developer)
• Kasus Penggunaan Penyimpanan Bersama (Chrome Developer)
• Pengantar Agregasi Pribadi (Chrome Developer)
• Penjelasan Penyimpanan Bersama (GitHub)
• Penjelasan Agregasi Pribadi (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