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 pelaporan fungsi dalam Shared Storage dan Protected Audience API.

• Jika Anda adalah developer yang sedang membangun sistem pelaporan untuk pengukuran.
• Jika Anda adalah pemasar, data scientist, atau laporan ringkasan lainnya konsumen, memahami mekanisme ini akan membantu Anda membuat keputusan penting untuk mengambil laporan ringkasan yang dioptimalkan.

Istilah utama

Sebelum membaca dokumen ini, akan sangat membantu jika Anda memahami istilah dan konsep penting. Setiap istilah 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 kumpulan data lokasi tempat browser melaporkan negara nama. 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 berapa banyak pengguna dari Prancis telah melihat konten Anda, maka France adalah dimensi dalam kunci agregasi, dan viewCount dari 1 adalah nilai agregat.
• Laporan agregat dibuat dan dienkripsi di dalam browser. Untuk Private Aggregation API, yang 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 bising dan data konversi yang mendetail.
• Worklet adalah sebuah bagian yang memungkinkan Anda menjalankan fungsi JavaScript tertentu dan mengembalikan informasi ke pemohon. Dalam {i>worklet<i}, Anda dapat menjalankan JavaScript, tetapi Anda tidak dapat berinteraksi atau berkomunikasi dengan halaman luar.

Alur kerja Agregasi Pribadi

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

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

Istilah penting: trusted execution environment adalah konfigurasi khusus dari perangkat keras dan perangkat lunak komputer yang memungkinkan pihak eksternal untuk memverifikasi versi sebenarnya dari perangkat lunak yang berjalan di komputer Anda TEE memungkinkan pihak eksternal untuk memverifikasi bahwa perangkat lunak itu sesuai dengan klaim produsen software—tidak lebih atau kurang.

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

Kunci agregasi

Kunci agregasi (disingkat "kunci") menunjukkan bucket tempat nilai agregat akan diakumulasikan. Satu atau beberapa dimensi dapat dienkode ke dalam kunci. Dimensi mewakili beberapa aspek yang ingin Anda peroleh lebih lebih lanjut, seperti kelompok usia pengguna atau jumlah tayangan iklan kampanye.

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

Kunci yang disediakan 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 mencapai 4 digit panjang seperti 1234, dan setiap negara dipetakan ke angka dalam abjad urutan seperti Afganistan adalah 1, Prancis adalah 61, dan Zimbabwe adalah '195'. Oleh karena itu, panjang kunci agregat akan memiliki 7 digit, di mana 4 digit pertama karakter dicadangkan untuk WidgetID dan 3 karakter terakhir yang 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 memiliki lebih sedikit, tambahkan angka nol di depan. Misalnya, jika ID negara memungkinkan 3 digit, ID negara untuk Aljazair adalah 003.

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

Dalam worklet Penyimpanan Bersama, Anda dapat mengakses crypto dan Modul TextEncoder yang dapat membantu Anda membuat {i>hash<i}. Untuk mempelajari lebih lanjut tentang cara menghasilkan {i>hash<i}, lihat SubtleCrypto.digest() aktif MDN.

Contoh berikut menjelaskan cara membuat kunci bucket dari nilai:

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 serupa, intinya dibuat secara berbeda untuk Private Aggregation API dibandingkan dengan Attribution Reporting API. Untuk Agregasi Pribadi, kunci lengkap ditentukan pada satu waktu, dalam panggilan JavaScript.

Nilai agregat

Nilai agregat dijumlahkan per kunci di banyak pengguna untuk membuat wawasan dalam bentuk nilai ringkasan dalam laporan ringkasan.

Sekarang, kembali ke contoh pertanyaan yang diajukan sebelumnya: "Berapa banyak pengguna yang pernah melihat widget saya berasal dari Prancis?" Jawaban atas pertanyaan ini akan terlihat sesuatu seperti "Kira-kira 4881 pengguna yang telah melihat {i>Widget ID 3276<i} saya dari Prancis." Nilai gabungan adalah 1 untuk setiap pengguna, dan "4881 pengguna" bernilai nilai gabungan yang merupakan jumlah semua nilai agregat untuk tombol agregasi.

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

Untuk contoh ini, kita menambahkan nilai 1 untuk setiap pengguna yang melihat widget. Dalam praktiknya, nilai agregat dapat diskalakan untuk meningkatkan kualitas signal-to-noise rasio aspek.

Anggaran kontribusi

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

Saat Anda menjumlahkan semua nilai agregat di semua kunci agregasi, jumlahnya harus kurang dari anggaran kontribusi. Anggaran dibatasi per worklet origin, per hari, dan untuk worklet Protected Audience API dan Shared Storage. Berkelanjutan periode kira-kira 24 jam terakhir digunakan untuk hari itu. Jika akan menyebabkan anggaran terlampaui, laporan ini tidak dibuat.

Anggaran kontribusi direpresentasikan 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 arbitrer, tetapi derau diskalakan mengikutinya. Anda dapat menggunakan anggaran ini untuk memaksimalkan rasio sinyal terhadap gangguan pada nilai ringkasan (dibahas lebih lanjut di bagian Derau dan penskalaan).

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

Laporan agregat

Setelah pengguna memanggil Private Aggregation API, browser akan membuat laporan agregat untuk diproses oleh Layanan Agregasi di lain waktu untuk membuat ringkasan laporan. Channel laporan agregat berformat JSON dan berisi daftar kontribusi, masing-masing merupakan pasangan {aggregation key, aggregatable value}. Laporan gabungan 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. Tujuan kunci enkripsi untuk browser dan kunci dekripsi untuk Agregasi Layanan dikeluarkan oleh koordinator, yang bertindak sebagai key management service. Koordinator menyimpan daftar hash biner dari image layanan untuk diverifikasi bahwa pemanggil diizinkan untuk menerima kunci dekripsi.

Contoh laporan agregat dengan debug mode 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 chrome://private-aggregation-internals halaman:

Untuk tujuan pengujian, opsi "Kirim Laporan yang Dipilih" dapat digunakan untuk mengirimkan segera laporkan ke server.

Mengumpulkan dan mengelompokkan laporan agregat

Browser mengirimkan laporan agregat ke asal worklet berisi panggilan ke Private Aggregation API, menggunakan metode jalur:

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

Pada endpoint ini, Anda harus mengoperasikan server — dengan bertindak sebagai kolektor — yang menerima laporan agregat yang dikirim dari klien.

Server kemudian harus mengelompokkan laporan dan mengirimkan batch ke Agregasi Layanan. Buat batch berdasarkan informasi yang tersedia dalam payload laporan agregat, 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 harapkan lebih banyak volume—misalnya, hari-hari saat tayangan iklan diperkirakan lebih banyak. Batch harus menyertakan laporan dari versi API, asal pelaporan, dan menjadwalkan waktu laporan.

Layanan Agregasi

Layanan Agregasi menerima laporan agregat terenkripsi dari kolektor dan membuat ringkasan laporan.

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 tersebut, Anda tidak akan memiliki visibilitas ke dalam data yang sedang diproses di dalam TEE.

Laporan ringkasan

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

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

• bucket: kunci agregasi sebagai string angka biner. Jika kunci agregasi yang digunakan adalah "123", maka bucket-nya adalah "1111011".
• value: nilai ringkasan untuk sasaran pengukuran tertentu, diringkas dari semua laporan agregat yang tersedia dengan penambahan derau.

Contoh:

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

Derau dan penskalaan

Untuk menjaga privasi pengguna, Layanan Agregasi menambahkan derau sekali ke setiap nilai ringkasan setiap kali laporan ringkasan diminta. Nilai noisenya adalah diambil secara acak dari probabilitas Laplace distribusi. Saat Anda tidak mengontrol langsung cara penambahan derau, Anda dapat memengaruhi dampaknya derau pada data pengukurannya.

Distribusi derau sama terlepas dari jumlah semua agregat masing-masing. Oleh karena itu, semakin tinggi nilai agregat, semakin kecil dampak derau Anda miliki.

Sebagai contoh, distribusi derau memiliki standar deviasi 100 dan berpusat di nol. Jika nilai laporan agregat yang dikumpulkan (atau "nilai agregat") hanya 200, maka deviasi standar derau akan menjadi 50% dari nilai gabungan. Tetapi, jika nilai agregat adalah 20.000, maka standar deviasi derau hanya akan 0,5% dari nilai gabungan. Jadi, nilai agregat 20.000 akan memiliki rasio sinyal-ke-kebisingan yang jauh lebih tinggi.

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

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

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

Lihat Anggaran kontribusi dokumentasi untuk mempelajari lebih lanjut.

Berinteraksi dan memberikan masukan

Private Aggregation API sedang dalam diskusi aktif dan dapat berubah sewaktu-waktu masa depan. Jika Anda mencoba API ini dan memiliki masukan, kami ingin sekali mendengarnya.

• GitHub: Baca penjelasan, mengajukan pertanyaan dan berpartisipasi dalam diskusi. * Dukungan developer: Ajukan pertanyaan dan ikuti diskusi di Dukungan Developer Privacy Sandbox Repositories. * Bergabung dengan Shared Storage API grup dan Protected Audience API grup untuk mendapatkan pengumuman terbaru terkait Agregasi Pribadi.