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 Penyimpanan Bersama dan Protected Audience API.

• Jika Anda adalah developer yang membuat sistem pelaporan untuk pengukuran lintas situs.
• Jika Anda adalah pemasar, data scientist, atau konsumen 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 persyaratan ini akan dijelaskan secara mendalam di sini.

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

Alur kerja Agregasi Pribadi

Saat Anda memanggil Private Aggregation API dengan kunci agregasi dan nilai agregat, browser akan menghasilkan laporan gabungan. Laporan tersebut dikirim ke server Anda yang mengelompokkan laporan. Laporan batch diproses nanti oleh Layanan Agregasi, dan laporan ringkasan akan dibuat.

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

Istilah penting: lingkungan eksekusi tepercaya adalah konfigurasi khusus hardware dan software komputer yang memungkinkan pihak eksternal memverifikasi versi software yang tepat yang berjalan di komputer. TEE memungkinkan pihak eksternal memverifikasi bahwa software melakukan persis seperti yang diklaim produsen software—tidak lebih atau kurang.

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

Kunci agregasi

Kunci agregasi (singkatan "kunci") mewakili bucket tempat nilai agregat akan diakumulasi. Satu atau beberapa dimensi dapat dienkode ke kunci. Dimensi mewakili beberapa aspek yang ingin Anda dapatkan lebih banyak wawasan, seperti kelompok usia pengguna atau jumlah tayangan iklan untuk 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, panjang ID widget adalah 4 digit, misalnya 1234, dan setiap negara dipetakan ke angka sesuai urutan abjad seperti Afganistan adalah 1, Prancis adalah 61, dan Zimbabwe adalah '195'. Oleh karena itu, panjang kunci gabungan akan memiliki panjang 7 digit, dengan 4 karakter pertama dicadangkan untuk WidgetID dan 3 karakter terakhir akan dicadangkan untuk CountryID.

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

Kunci agregasi
ID Widget	ID Negara
3276	061

Contoh: Jika dimensi memiliki ruang kunci yang tersedia untuk beberapa digit, tetapi nilainya lebih sedikit, tambahkan angka nol di awal. Misalnya, jika ID negara mengizinkan 3 digit, ID negara untuk Aljazair adalah 003.

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 dari 42943797454801331377966796057547478208888578253058197330928948081739249096287n. Jika nilai hash lebih dari 128 bit, Anda dapat memotongnya untuk memastikan nilai tersebut tidak akan melampaui 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

Catatan: Meskipun konsepnya mirip, kunci dibuat secara berbeda untuk Private Aggregation API dibandingkan Attribution Reporting API. Untuk Agregasi Pribadi, kunci lengkap ditentukan secara bersamaan dalam panggilan JavaScript.

Nilai agregat

Nilai agregat dijumlahkan per kunci dari 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 gabungan adalah 1 untuk setiap pengguna, dan "4881 pengguna" adalah nilai gabungan yang merupakan jumlah dari semua nilai agregat untuk kunci agregasi tersebut.

Kunci agregasi		Nilai agregat
ID Widget	ID Negara	Jumlah Penayangan
3276	061	1

Untuk contoh ini, kami menambah nilai dengan 1 untuk setiap pengguna yang melihat widget. Dalam praktiknya, nilai gabungan dapat diskalakan untuk meningkatkan rasio sinyal ke derau.

Anggaran kontribusi

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

Jika Anda menjumlahkan semua nilai gabungan di semua kunci agregasi, jumlahnya harus kurang dari anggaran kontribusi. Anggaran dicakupkan per origin worklet, per hari, dan terpisah untuk worklet Protected Audience API dan Shared Storage. Periode berputar kira-kira selama 24 jam terakhir digunakan untuk satu hari. Jika laporan gabungan baru akan menyebabkan anggaran terlampaui, laporan tidak akan dibuat.

Anggaran kontribusi diwakili oleh parameter L₁, dan ditetapkan ke 2¹⁶ (65.536) per sepuluh menit per hari dengan backstop 2²⁰

(1.048.576). Lihat penjelasan untuk mempelajari parameter ini lebih lanjut.

Nilai anggaran kontribusi bersifat tidak tentu, tetapi derau diskalakan untuk 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 anggaran kontribusi lebih lanjut, lihat penjelasan. Selain itu, lihat Anggaran Kontribusi untuk panduan selengkapnya.

Laporan agregat

Setelah pengguna memanggil Private Aggregation API, browser menghasilkan laporan agregat untuk diproses oleh Layanan Agregasi di lain waktu untuk membuat laporan ringkasan. Laporan gabungan berformat JSON dan berisi daftar kontribusi terenkripsi, yang masing-masing 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 Layanan Agregasi diterbitkan oleh koordinator, yang bertindak sebagai key management service. Koordinator menyimpan daftar hash biner image layanan untuk memverifikasi bahwa pemanggil diizinkan untuk menerima kunci dekripsi.

Contoh laporan agregat dengan mode debug yang 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 segera mengirim laporan ke server.

Mengumpulkan dan mengelompokkan laporan agregat

Browser mengirim laporan agregat ke asal worklet yang berisi panggilan ke Private Aggregation API, menggunakan jalur populer yang tercantum:

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

Di endpoint ini, Anda harus mengoperasikan server — bertindak sebagai kolektor — yang menerima laporan gabungan yang dikirim dari klien.

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

Anda dapat memutuskan untuk mengelompokkan secara harian atau mingguan. Strategi ini fleksibel, dan Anda dapat mengubah strategi pengelompokan untuk peristiwa tertentu yang Anda mengharapkan lebih banyak volume—misalnya, hari-hari saat lebih banyak tayangan yang diharapkan. Batch harus mencakup laporan dari versi API, asal pelaporan, dan jadwal waktu laporan yang sama.

Layanan Agregasi

Layanan Agregasi menerima laporan agregat yang dienkripsi dari kolektor dan membuat laporan ringkasan.

Untuk mendekripsi payload laporan, Layanan Agregasi mengambil kunci dekripsi dari koordinator. Layanan ini berjalan di trusted execution environment (TEE), yang memberikan tingkat jaminan untuk integritas data, kerahasiaan data, dan integritas kode. Meskipun Anda memiliki dan mengoperasikan layanan, Anda tidak akan dapat melihat data yang sedang diproses di dalam TEE.

Laporan ringkasan

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

Laporan ringkasan berisi kumpulan key-value pair bergaya kamus JSON. Setiap pasangan berisi:

• bucket: kunci agregasi sebagai string angka biner. Jika kunci agregasi yang digunakan adalah "123", bucket adalah "1111011".
• value: nilai ringkasan untuk sasaran pengukuran tertentu, diringkas dari semua laporan agregat yang tersedia dengan derau 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 memiliki kontrol langsung atas cara derau ditambahkan, Anda dapat memengaruhi dampak derau pada data pengukurannya.

Distribusi derau akan sama terlepas dari jumlah semua nilai agregat. Oleh karena itu, makin tinggi nilai agregat, makin kecil dampak yang mungkin ditimbulkan oleh derau.

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

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

Meningkatkan 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 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 gabungan di semua kunci.

Lihat Dokumentasi anggaran kontribusi untuk mempelajari lebih lanjut.

Berinteraksi dan memberikan masukan

Private Aggregation API sedang dalam diskusi aktif dan dapat berubah pada masa mendatang. Jika Anda mencoba API ini dan memiliki masukan, kami akan dengan senang hati mendengarnya.

• GitHub: Baca penjelasan, ajukan pertanyaan dan berpartisipasi dalam diskusi. * Dukungan developer: Ajukan pertanyaan dan ikuti diskusi di repositori Dukungan Developer Privacy Sandbox. * Gabung ke grup Shared Storage API dan grup Protected Audience API untuk mendapatkan pengumuman terbaru terkait Private Aggregation.