Dasar-dasar Agregasi Pribadi API

Konsep utama Private Aggregation API

Untuk siapa dokumen ini?

Private Aggregation API memungkinkan pengumpulan data gabungan dari worklet dengan akses ke data lintas situs. Konsep yang dibagikan di sini penting bagi developer yang membangun fungsi pelaporan dalam Shared Storage dan Protected Audience API.

• Jika Anda adalah developer yang membuat sistem pelaporan untuk pengukuran lintas situs.
• Jika Anda seorang pemasar, ilmuwan data, atau pengguna laporan ringkasan lainnya, memahami mekanisme ini akan membantu Anda membuat keputusan desain untuk mengambil laporan ringkasan yang dioptimalkan.

Istilah utama

Sebelum membaca dokumen ini, sebaiknya Anda memahami istilah dan konsep utama. Setiap istilah ini akan dijelaskan secara mendalam di sini.

• Kunci agregasi (juga dikenal sebagai bucket) adalah kumpulan titik data yang telah ditentukan sebelumnya. Misalnya, Anda mungkin ingin mengumpulkan bucket data lokasi tempat browser melaporkan nama negara. Kunci penggabungan dapat berisi lebih dari satu dimensi (misalnya, negara dan ID widget konten Anda).
• Nilai yang dapat diagregasi adalah titik data individual yang dikumpulkan ke dalam kunci agregasi. Jika Anda ingin mengukur jumlah pengguna dari Prancis yang telah melihat konten Anda, maka France adalah dimensi dalam kunci agregasi, dan viewCount dari 1 adalah nilai yang dapat diagregasi.
• Laporan yang dapat diagregasi dibuat dan dienkripsi dalam browser. Untuk Private Aggregation API, parameter ini berisi data tentang satu peristiwa.
• Layanan Agregasi memproses data dari laporan gabungan untuk membuat laporan ringkasan.
• Laporan ringkasan adalah output akhir Layanan Agregasi, dan berisi data pengguna gabungan yang telah diberi derau dan data konversi mendetail.
• Worklet adalah bagian dari infrastruktur yang memungkinkan Anda menjalankan fungsi JavaScript tertentu dan mengembalikan informasi ke pemohon. Dalam worklet, Anda dapat mengeksekusi JavaScript, tetapi Anda tidak dapat berinteraksi atau berkomunikasi dengan halaman di luar.

Alur kerja Agregasi Pribadi

Saat Anda memanggil Private Aggregation API dengan kunci agregasi dan nilai yang dapat diagregasi, browser akan membuat laporan yang dapat diagregasi. Laporan dikirim ke server Anda yang mengelompokkan laporan. Laporan yang di-batch akan diproses nanti oleh Layanan Agregasi, dan laporan ringkasan akan dibuat.

1. Saat Anda memanggil Private Aggregation API, klien (browser) akan membuat dan mengirim laporan yang dapat diagregasi ke server Anda untuk dikumpulkan.
2. Server Anda mengumpulkan laporan dari klien dan mengelompokkannya untuk dikirim ke Layanan Agregasi.
3. Setelah mengumpulkan cukup banyak laporan, Anda akan mengelompokkan dan mengirimkannya ke Layanan Agregasi, yang berjalan di lingkungan eksekusi tepercaya, untuk membuat laporan ringkasan.

Alur kerja yang dijelaskan di bagian ini mirip dengan Attribution Reporting API. Namun, Pelaporan Atribusi mengaitkan data yang dikumpulkan dari peristiwa tayangan iklan dan peristiwa konversi, yang terjadi pada waktu yang berbeda. Agregasi Pribadi mengukur satu peristiwa lintas situs.

Kunci agregasi

Kunci agregasi ("kunci" untuk singkatnya) merepresentasikan bucket tempat nilai yang dapat diagregasi akan dikumpulkan. Satu atau beberapa dimensi dapat dienkode ke dalam kunci. Dimensi mewakili beberapa aspek yang ingin Anda pahami lebih lanjut, seperti kelompok usia pengguna atau jumlah tayangan kampanye iklan.

Misalnya, Anda mungkin memiliki widget yang disematkan di beberapa situs dan ingin menganalisis negara pengguna yang telah melihat widget Anda. Anda ingin menjawab pertanyaan seperti "Berapa banyak pengguna yang telah melihat widget saya yang berasal dari Negara X?" Untuk melaporkan pertanyaan ini, Anda dapat menyiapkan kunci agregasi yang mengenkode dua dimensi: ID widget dan ID negara.

Kunci yang diberikan ke Private Aggregation API adalah BigInt, yang terdiri dari beberapa dimensi. Dalam contoh ini, dimensinya adalah ID widget dan ID negara. Misalnya, ID widget dapat memiliki panjang hingga 4 digit, seperti 1234, dan setiap negara dipetakan ke angka dalam urutan abjad, seperti Afghanistan adalah 1, Prancis adalah 61, dan Zimbabwe adalah 195. Oleh karena itu, kunci yang dapat diagregasi akan memiliki panjang 7 digit, dengan 4 karakter pertama dicadangkan untuk WidgetID dan 3 karakter terakhir dicadangkan untuk CountryID.

Misalnya, kunci mewakili jumlah pengguna dari Prancis (ID negara 061) yang telah melihat ID widget 3276, Kunci agregasinya adalah 3276061.

Kunci agregasi juga dapat dibuat dengan mekanisme hashing, seperti SHA-256. Misalnya, string {"WidgetId":3276,"CountryID":67} dapat di-hash lalu dikonversi menjadi nilai BigInt 42943797454801331377966796057547478208888578253058197330928948081739249096287n. Jika nilai hash memiliki lebih dari 128 bit, Anda dapat memotongnya untuk memastikan nilai tersebut tidak melebihi nilai bucket maksimum yang diizinkan, yaitu 2^128−1.

Dalam worklet Shared Storage, Anda dapat mengakses modul crypto dan TextEncoder yang dapat membantu Anda membuat hash. Untuk mempelajari lebih lanjut cara membuat hash, lihat SubtleCrypto.digest() di MDN.

Contoh berikut menjelaskan cara membuat kunci bucket dari nilai yang di-hash:

async function convertToBucket(data) {
  // Encode as UTF-8 Uint8Array
  const encodedData = new TextEncoder().encode(data);

  // Generate SHA-256 hash
  const hashBuffer = await crypto.subtle.digest('SHA-256', encodedData);

  // Truncate the hash
  const truncatedHash = Array.from(new Uint8Array(hashBuffer, 0, 16));

  // Convert the byte sequence to a decimal
  return truncatedHash.reduce((acc, curr) => acc * 256n + BigInt(curr), 0n);
}

const data = {
  WidgetId: 3276,
  CountryID: 67
};

const dataString = JSON.stringify(data);
const bucket = await convertToBucket(dataString);

console.log(bucket); // 126200478277438733997751102134640640264n

Nilai yang dapat diagregasi

Nilai yang dapat diagregasi dijumlahkan per kunci di banyak pengguna untuk menghasilkan insight gabungan dalam bentuk nilai ringkasan dalam laporan ringkasan.

Sekarang, kembali ke contoh pertanyaan yang diajukan sebelumnya: "Berapa banyak pengguna yang telah melihat widget saya yang berasal dari Prancis?" Jawaban atas pertanyaan ini akan terlihat seperti "Sekitar 4.881 pengguna yang telah melihat ID Widget 3276 saya berasal dari Prancis". Nilai yang dapat diagregasi adalah 1 untuk setiap pengguna, dan "4881 pengguna" adalah nilai yang diagregasi yang merupakan jumlah semua nilai yang dapat diagregasi untuk kunci agregasi tersebut.

Untuk contoh ini, kita menaikkan nilai sebesar 1 untuk setiap pengguna yang melihat widget. Dalam praktiknya, nilai yang dapat diagregasi dapat diskalakan untuk meningkatkan rasio sinyal terhadap derau.

Anggaran kontribusi

Setiap panggilan ke Private Aggregation API disebut kontribusi. Untuk melindungi privasi pengguna, jumlah kontribusi yang dapat dikumpulkan dari individu dibatasi.

Saat Anda menjumlahkan semua nilai yang dapat diagregasi di semua kunci agregasi, jumlahnya harus kurang dari anggaran kontribusi. Anggaran ditentukan berdasarkan cakupan per-worklet origin, per hari, dan terpisah untuk worklet Protected Audience API dan Shared Storage. Periode berjalan sekitar 24 jam terakhir digunakan untuk hari tersebut. Jika laporan yang dapat diagregasi baru akan menyebabkan anggaran terlampaui, laporan tidak dibuat.

Anggaran kontribusi diwakili oleh parameter L₁, dan ditetapkan ke 2¹⁶ (65.536) per sepuluh menit per hari dengan batas 2²⁰ (1.048.576). Lihat penjelasan untuk mempelajari parameter ini lebih lanjut.

Nilai anggaran kontribusi bersifat arbitrer, tetapi derau diskalakan ke anggaran tersebut. Anda dapat menggunakan anggaran ini untuk memaksimalkan rasio sinyal terhadap derau pada nilai ringkasan (dibahas lebih lanjut di bagian Derau dan penskalaan).

Untuk mempelajari lebih lanjut anggaran kontribusi, lihat penjelasan. Selain itu, lihat Anggaran Kontribusi untuk mendapatkan panduan selengkapnya.

Batas kontribusi per laporan

Bergantung pada pemanggil, batas kontribusi dapat berbeda dan, untuk Shared Storage, batas ini adalah default yang dapat diganti. Saat ini, laporan yang dibuat untuk pemanggil Shared Storage API dibatasi hingga 20 kontribusi per laporan. Di sisi lain, pemanggil Protected Audience API dibatasi hingga 100 kontribusi per laporan. Batas ini dipilih untuk menyeimbangkan jumlah kontribusi yang dapat disematkan dengan ukuran payload.

Untuk Shared Storage, kontribusi yang dilakukan dalam satu operasi run() atau selectURL() digabungkan ke dalam satu laporan. Untuk Protected Audience, kontribusi yang dilakukan oleh satu origin dalam lelang dikelompokkan bersama.

Kontribusi dengan padding

Kontribusi selanjutnya dimodifikasi dengan fitur padding. Tindakan menambahkan padding payload mengamankan informasi tentang jumlah kontribusi sebenarnya yang disematkan dalam laporan yang dapat diagregasi. Padding menambah payload dengan kontribusi null (yaitu dengan nilai 0) untuk mencapai panjang tetap.

Laporan agregat

Setelah pengguna memanggil Private Aggregation API, browser akan membuat laporan yang dapat diagregasi untuk diproses oleh Layanan Agregasi di lain waktu untuk membuat laporan ringkasan. Laporan yang dapat diagregasi berformat JSON dan berisi daftar kontribusi terenkripsi, dengan setiap kontribusi berupa pasangan {aggregation key, aggregatable value}. Laporan agregat dikirim dengan penundaan acak hingga satu jam.

Kontribusi dienkripsi dan tidak dapat dibaca di luar Layanan Agregasi. Layanan Agregasi mendekripsi laporan dan membuat laporan ringkasan. Kunci enkripsi untuk browser dan kunci dekripsi untuk Aggregation Service dikeluarkan oleh koordinator, yang bertindak sebagai layanan pengelolaan kunci. Koordinator menyimpan daftar hash biner image layanan untuk memverifikasi bahwa pemanggil diizinkan untuk menerima kunci dekripsi.

Contoh laporan yang dapat diagregasi dengan mode debug diaktifkan:

  "aggregation_service_payloads": [
    {
      "debug_cleartext_payload": "omRkYXRhgaJldmFsdWVEAAAAgGZidWNrZXRQAAAAAAAAAAAAAAAAAAAE0mlvcGVyYXRpb25paGlzdG9ncmFt",
      "key_id": "2cc72b6a-b92f-4b78-b929-e3048294f4d6",
      "payload": "a9Mk3XxvnfX70FsKrzcLNZPy+00kWYnoXF23ZpNXPz/Htv1KCzl/exzplqVlM/wvXdKUXCCtiGrDEL7BQ6MCbQp1NxbWzdXfdsZHGkZaLS2eF+vXw2UmLFH+BUg/zYMu13CxHtlNSFcZQQTwnCHb"
    }
  ],
  "debug_key": "777",
  "shared_info": "{\"api\":\"shared-storage\",\"debug_mode\":\"enabled\",\"report_id\":\"5bc74ea5-7656-43da-9d76-5ea3ebb5fca5\",\"reporting_origin\":\"https://localhost:4437\",\"scheduled_report_time\":\"1664907229\",\"version\":\"0.1\"}"

Laporan gabungan dapat diperiksa dari halaman chrome://private-aggregation-internals:

Untuk tujuan pengujian, tombol "Kirim Laporan yang Dipilih" dapat digunakan untuk mengirim laporan ke server secara langsung.

Mengumpulkan dan mengelompokkan laporan agregat

Browser mengirimkan laporan yang dapat diagregasi ke origin worklet yang berisi panggilan ke Private Aggregation API, menggunakan jalur terkenal yang tercantum:

• Untuk Shared Storage: /.well-known/private-aggregation/report-shared-storage
• Untuk Protected Audience: /.well-known/private-aggregation/report-protected-audience

Di endpoint ini, Anda harus mengoperasikan server — yang bertindak sebagai pengumpul — yang menerima laporan yang dapat digabungkan yang dikirim dari klien.

Kemudian, server harus mengelompokkan laporan dan mengirimkan batch ke Layanan Agregasi. Buat batch berdasarkan informasi yang tersedia dalam payload laporan gabungan yang tidak dienkripsi, seperti kolom shared_info. Idealnya, batch harus berisi 100 laporan atau lebih per batch.

Anda dapat memutuskan untuk mengelompokkan data setiap hari atau setiap minggu. Strategi ini fleksibel, dan Anda dapat mengubah strategi pengelompokan untuk acara tertentu yang diperkirakan akan menghasilkan lebih banyak volume—misalnya, hari-hari dalam setahun saat lebih banyak tayangan iklan diperkirakan akan terjadi. Batch harus menyertakan laporan dari versi API, asal pelaporan, dan waktu laporan terjadwal yang sama.

ID Filter

Private Aggregation API & Aggregation Service memungkinkan penggunaan ID pemfilteran untuk memproses pengukuran pada tingkat yang lebih terperinci seperti per kampanye iklan, bukan memproses hasil dalam kueri yang lebih besar.

Untuk mulai menggunakannya hari ini, berikut beberapa langkah kasar yang dapat diterapkan pada penerapan saat ini.

Langkah-langkah Shared Storage

Jika Anda menggunakan Shared Storage API dalam alur Anda:

1. Tentukan tempat Anda akan mendeklarasikan dan menjalankan modul Shared Storage baru. Dalam contoh berikut, kita telah memberi nama file modul filtering-worklet.js, yang terdaftar di filtering-example.

   (async function runFilteringIdsExample () {
   await window.sharedStorage.worklet.addModule('filtering-worklet.js');
   await window.sharedStorage.run('filtering-example', {
     keepAlive: true,
     privateAggregationConfig: {
       contextId: 'example-id',
       filteringIdMaxBytes: 8 // optional
     }
   }});
   })();
   

   Perhatikan bahwa filteringIdMaxBytes dapat dikonfigurasi per laporan dan, jika tidak ditetapkan, akan ditetapkan secara default ke 1. Nilai default ini adalah untuk mencegah peningkatan ukuran payload yang tidak perlu, sehingga mencegah peningkatan biaya penyimpanan dan pemrosesan. Baca selengkapnya di penjelasan kontribusi fleksibel.

2. Di filtering-worklet.js, saat Anda meneruskan kontribusi ke privateAggregation.contributeToHistogram(...) dalam worklet Shared Storage, Anda dapat menentukan ID pemfilteran.

   // Within  filtering-worklet.js
   class FilterOperation {
     async run() {
       let contributions = [{
         bucket: 1234n,
         value: 56,
         filteringId: 3n // defaults to 0n if not assigned, type bigint
       }];
   
       for (const c of contributions) {
         privateAggregation.contributeToHistogram(c);
       }
       …
   }
   });
   
   register('filtering-example', FilterOperation);
   

3. Laporan gabungan akan dikirim ke tempat Anda telah menentukan endpoint /.well-known/private-aggregation/report-shared-storage. Lanjutkan ke panduan memfilter ID untuk mempelajari perubahan yang diperlukan dalam parameter tugas Layanan Agregasi.

Setelah pembuatan batch selesai dan dikirim ke Layanan Agregasi yang di-deploy, hasil yang difilter akan tercermin dalam laporan ringkasan akhir Anda.

Langkah-langkah Protected Audience

Jika Anda menggunakan Protected Audience API dalam alur Anda:

1. Dalam penerapan Protected Audience saat ini, Anda dapat menyetel berikut untuk terhubung ke Private Aggregation. Tidak seperti Shared Storage, ukuran maksimum ID pemfilteran belum dapat dikonfigurasi. Secara default, ukuran maksimum ID pemfilteran adalah 1 byte dan akan ditetapkan ke 0n. Perlu diingat bahwa nilai ini akan ditetapkan di fungsi pelaporan Protected Audience (misalnya reportResult() atau generateBid()).

   const contribution = {
     ...
     filteringId: 0n
   };
   
   privateAggregation.contributeToHistogram(contribution);
   

2. Laporan gabungan akan dikirim ke tempat Anda telah menentukan endpoint /.well-known/private-aggregation/report-protected-audience. Setelah pembuatan batch selesai dan dikirim ke Layanan Agregasi yang di-deploy, hasil yang difilter akan ditampilkan dalam laporan ringkasan akhir. Berikut penjelasan tentang Attribution Reporting API dan Private Aggregation API yang tersedia, serta proposal awal.

Lanjutkan ke panduan ID pemfilterandi Layanan Agregasi atau buka bagian Attribution Reporting API untuk membaca penjelasan yang lebih mendetail.

Layanan Agregasi

Layanan Agregasi menerima laporan agregasi terenkripsi dari pengumpul dan membuat laporan ringkasan. Untuk mengetahui strategi lebih lanjut tentang cara mengelompokkan laporan yang dapat diagregasi di pengumpul, lihat panduan pengelompokan kami.

Layanan ini berjalan di trusted execution environment (TEE), yang memberikan tingkat jaminan untuk integritas data, kerahasiaan data, dan integritas kode. Jika Anda ingin melihat lebih dekat cara koordinator digunakan bersama TEE, baca selengkapnya tentang peran dan tujuannya.

Laporan ringkasan

Laporan ringkasan memungkinkan Anda melihat data yang telah dikumpulkan dengan menambahkan derau. Anda dapat meminta laporan ringkasan untuk kumpulan kunci tertentu.

Laporan ringkasan berisi kumpulan pasangan nilai-kunci gaya kamus JSON. Setiap pasangan berisi:

• bucket: kunci agregasi sebagai string angka biner. Jika kunci agregasi yang digunakan adalah "123", maka bucketnya adalah "1111011".
• value: nilai ringkasan untuk sasaran pengukuran tertentu, yang dijumlahkan dari semua laporan yang dapat diagregasi yang tersedia dengan noise yang ditambahkan.

Contoh:

[
  {"bucket":` `"111001001",` `"value":` `"2558500"},
  {"bucket":` `"111101001",` `"value":` `"3256211"},
  {"bucket":` `"111101001",` `"value":` `"6536542"},
]

Derau dan penskalaan

Untuk menjaga privasi pengguna, Layanan Agregasi menambahkan derau satu kali ke setiap nilai ringkasan setiap kali laporan ringkasan diminta. Nilai derau diambil secara acak dari distribusi probabilitas Laplace. Meskipun Anda tidak dapat mengontrol secara langsung cara derau ditambahkan, Anda dapat memengaruhi dampak derau pada data pengukurannya.

Distribusi derau sama terlepas dari jumlah semua nilai yang dapat diagregasi. Oleh karena itu, makin tinggi nilai yang dapat diagregasi, makin kecil kemungkinan dampak derau.

Misalnya, distribusi derau memiliki standar deviasi 100 dan berpusat di nol. Jika nilai laporan yang dapat diagregasi yang dikumpulkan (atau "nilai yang dapat diagregasi") hanya 200, maka simpangan baku derau adalah 50% dari nilai yang diagregasi. Namun, jika nilai yang dapat diagregasi adalah 20.000,maka standar deviasi derau hanya akan menjadi 0, 5% dari nilai yang diagregasi. Jadi, nilai yang dapat diagregasi sebesar 20.000 akan memiliki rasio sinyal terhadap derau yang jauh lebih tinggi.

Oleh karena itu, mengalikan nilai yang dapat diagregasi dengan faktor penskalaan dapat membantu mengurangi derau. Faktor penskalaan menunjukkan seberapa besar Anda ingin menskalakan nilai yang dapat diagregasi tertentu.

Menskalakan nilai dengan memilih faktor penskalaan yang lebih besar akan mengurangi derau relatif. Namun, hal ini juga menyebabkan jumlah semua kontribusi di semua bucket mencapai batas anggaran kontribusi lebih cepat. Menskalakan nilai ke bawah dengan memilih konstanta faktor penskalaan yang lebih kecil akan meningkatkan derau relatif, tetapi mengurangi risiko mencapai batas anggaran.

Untuk menghitung faktor penskalaan yang sesuai, bagi anggaran kontribusi dengan jumlah maksimum nilai yang dapat diagregasi di semua kunci.

Lihat dokumentasi Anggaran kontribusi untuk mempelajari lebih lanjut.

Berinteraksi dan memberikan masukan

Private Aggregation API sedang dalam tahap pembahasan aktif dan dapat berubah sewaktu-waktu pada masa mendatang. Jika Anda mencoba API ini dan memiliki masukan, kami ingin mendengarnya.

• GitHub: Baca penjelasan, ajukan pertanyaan, dan berpartisipasilah dalam diskusi.
  • Dukungan developer: Ajukan pertanyaan dan bergabunglah dalam diskusi di repo Dukungan Developer Privacy Sandbox.
• Bergabunglah ke grup Shared Storage API dan grup Protected Audience API untuk mendapatkan pengumuman terbaru terkait Private Aggregation.