Membuat laporan data gabungan menggunakan data dari Protected Audience dan data lintas situs dari Shared Storage.
Untuk menyediakan fitur penting yang diandalkan web, Private Aggregation API telah dibuat untuk menggabungkan dan melaporkan data lintas situs dalam cara yang menjaga privasi.
Status penerapan
Proposal | Status |
---|---|
Mencegah laporan Private Aggregation API yang tidak valid dengan verifikasi laporan untuk Shared Storage Penjelasan |
Tersedia di Chrome |
Ketersediaan mode debug Agregasi Pribadi bergantung pada kelayakan 3PC Masalah GitHub |
Tersedia di Chrome M119 |
Mengurangi penundaan laporan Penjelasan |
Tersedia di Chrome M119 |
Dukungan untuk Private Aggregation API dan Layanan Agregasi untuk Google Cloud Penjelasan |
Tersedia di Chrome M121 |
Padding untuk payload laporan agregat Penjelasan |
Tersedia di Chrome M119 |
Mode debug Agregasi Pribadi tersedia untuk pelaporan AuctionReportBuyers Penjelasan |
Diperkirakan tersedia di Chrome M123 |
Dukungan ID Pemfilteran Penjelasan |
Diperkirakan tersedia di Chrome M128 |
Apa itu Private Aggregation API
Private Aggregation API memungkinkan developer membuat laporan data gabungan dengan data dari Protected Audience API dan data lintas situs dari Penyimpanan Bersama.
Fungsi utama API ini dikenal sebagai contributeToHistogram()
. Operasi histogram memungkinkan Anda menggabungkan data
pada pengguna di setiap bucket (dikenal di API sebagai kunci agregasi) yang Anda tentukan.
Panggilan histogram Anda mengumpulkan nilai dan menampilkan hasil gabungan yang berisi derau di
dalam bentuk laporan ringkasan. Misalnya, laporan itu mungkin
menunjukkan jumlah
di situs setiap pengguna melihat konten Anda, atau menemukan {i>bug<i} di skrip pihak ketiga Anda. Operasi ini dijalankan dalam worklet API lain.
Misalnya, jika sebelumnya Anda telah mencatat data demografis dan geografis di Penyimpanan Bersama, Anda dapat menggunakan Private Aggregation API untuk membuat histogram yang memberitahukan perkiraan jumlah pengguna di New York City yang telah melihat konten Anda lintas situs. Untuk menggabungkan pengukuran ini, Anda dapat mengenkode dimensi geografi ke dalam kunci agregasi dan menghitung pengguna dalam nilai agregat.
Konsep utama
Saat Anda memanggil Private Aggregation API dengan kunci agregasi dan nilai agregat, browser akan menghasilkan laporan agregat.
Laporan agregat dikirim ke server Anda untuk dikumpulkan dan dikelompokkan. Laporan batch diproses nanti oleh Layanan Agregasi, dan laporan ringkasan akan dibuat.
Lihat dokumen dasar-dasar Private Aggregation API untuk mempelajari lebih lanjut konsep utama yang terkait dengan Private Aggregation API.
Perbedaan dengan Pelaporan Atribusi
Private Aggregation API memiliki banyak kesamaan dengan Attribution Reporting API. Attribution Reporting adalah API mandiri yang dirancang untuk mengukur konversi, sedangkan Private Aggregation dibuat untuk pengukuran lintas situs bersama dengan API seperti Protected Audience API dan Shared Storage. Kedua API menghasilkan laporan agregat yang digunakan oleh backend Layanan Agregasi untuk membuat laporan ringkasan.
Attribution Reporting mengaitkan data yang dikumpulkan dari peristiwa tayangan dan peristiwa konversi, yang terjadi pada waktu yang berbeda-beda. Agregasi Pribadi mengukur satu peristiwa lintas situs.
Uji API ini
Untuk menguji Private Aggregation API secara lokal, aktifkan semua API privasi Iklan di bagian chrome://settings/adPrivacy
.
Baca selengkapnya tentang pengujian dalam eksperimen dan berpartisipasi.
Menggunakan demo
Demo Private Aggregation API untuk Penyimpanan Bersama dapat diakses di goo.gle/shared-storage-demo, dan kodenya tersedia di GitHub. Demo ini menerapkan operasi sisi klien dan menghasilkan laporan agregat yang dikirim ke server Anda.
Demo Private Aggregation API untuk Protected Audience API akan dipublikasikan pada masa mendatang.
Kasus penggunaan
Private Aggregation adalah API tujuan umum untuk pengukuran lintas situs, dan tersedia untuk digunakan di worklet Penyimpanan Bersama dan Protected Audience API. Langkah pertama adalah menentukan secara spesifik informasi apa yang ingin Anda kumpulkan. Titik data tersebut adalah dasar dari kunci agregasi Anda.
Dengan Penyimpanan bersama
Penyimpanan Bersama memungkinkan Anda membaca dan menulis data lintas situs di lingkungan yang aman untuk mencegah kebocoran, sementara Private Aggregation API memungkinkan Anda mengukur data lintas situs yang disimpan di Shared Storage.
Pengukuran jangkauan unik
Anda mungkin ingin mengukur jumlah pengguna unik yang telah melihat konten mereka. Private Aggregation API dapat memberikan jawaban seperti "Sekitar 317 pengguna unik telah melihat Content ID 861".
Anda dapat menyetel tanda di Penyimpanan Bersama untuk menunjukkan apakah pengguna sudah melihat konten tersebut atau belum. Pada kunjungan pertama saat tanda tidak ada, panggilan ke Agregasi Pribadi akan dilakukan, lalu tanda ini ditetapkan. Pada kunjungan berikutnya oleh pengguna, termasuk kunjungan lintas situs, Anda dapat memeriksa Penyimpanan Bersama dan melewati pengiriman laporan ke Agregasi Pribadi jika tanda ini disetel. Untuk mempelajari lebih lanjut metode untuk menerapkan pengukuran ini, lihat laporan resmi jangkauan kami.
Pengukuran demografi
Anda mungkin ingin mengukur demografi pengguna yang pernah melihat konten Anda di berbagai situs.
Agregasi Pribadi dapat memberikan jawaban, seperti "Sekitar 317 pengguna unik berasal dari usia 18-45 tahun dan berasal dari Jerman". Menggunakan Penyimpanan Bersama untuk mengakses data demografi dari konteks pihak ketiga. Di lain waktu, Anda dapat membuat laporan menggunakan Agregasi Pribadi dengan mengenkode dimensi kelompok usia dan negara di kunci agregasi.
Pengukuran frekuensi K+
Anda mungkin ingin mengukur jumlah pengguna yang telah melihat setidaknya K kali pada browser tertentu, untuk nilai K yang telah dipilih sebelumnya.
Agregasi Pribadi dapat memberikan jawaban seperti "Sekitar 89 pengguna telah melihat Content ID 581 minimal 3 kali". Penghitung dapat ditambahkan di Penyimpanan Bersama dari situs yang berbeda dan dapat dibaca di dalam worklet. Setelah jumlahnya mencapai K, laporan dapat dikirim melalui Agregasi Pribadi.
Dengan Protected Audience API
Protected Audience API memungkinkan penargetan ulang dan kasus penggunaan audiens kustom, sedangkan Private Aggregation memungkinkan Anda melaporkan peristiwa dari worklet pembeli dan penjual. API ini dapat digunakan untuk tugas seperti mengukur distribusi bid lelang.
Dari worklet Protected Audience API, Anda dapat menggabungkan data secara langsung menggunakan contributeToHistogram()
dan melaporkan data berdasarkan pemicu menggunakan contributeToHistogramOnEvent()
, yang merupakan ekstensi khusus untuk Protected Audience API.
Fungsi yang tersedia
Fungsi berikut tersedia di objek privateAggregation
yang tersedia di worklet Penyimpanan Bersama dan Protected Audience API.
contributeToHistogram()
Anda dapat memanggil privateAggregation.contributeToHistogram({ bucket: <bucket>, value: <value> })
, dengan kunci agregasi adalah bucket
dan nilai agregat sebagai value
. Untuk parameter bucket
, BigInt
diperlukan. Untuk parameter value
, Angka bilangan bulat diperlukan.
Berikut adalah contoh cara pemanggilan di Penyimpanan Bersama untuk pengukuran jangkauan:
iframe.js
// Cross-site iframe code
async function measureReach() {
// Register worklet
await window.sharedStorage.worklet.addModule('worklet.js');
// Run reach measurement operation
await window.sharedStorage.run('reach-measurement', {
data: { contentId: '1234' }
});
}
measureReach();
worklet.js
// Shared storage worklet code
function convertContentIdToBucket(campaignId){
// Generate aggregation key
}
// The scale factor is multiplied by the aggregatable value to
// maximize the signal-to-noise ratio. See "Noise and scaling"
// section in the Aggregation Fundamentals document to learn more.
const SCALE_FACTOR = 65536;
class ReachMeasurementOperation {
async run(data) {
const key = 'has-reported-content';
// Read the flag from Shared Storage
const hasReportedContent = await this.sharedStorage.get(key) === 'true';
// Do not send report if the flag is set
if (hasReportedContent) {
return;
}
// Send histogram report
// Set the aggregation key in `bucket`
// Bucket examples: 54153254n or BigInt(54153254)
// Set the scaled aggregatable value in `value`
privateAggregation.contributeToHistogram({
bucket: convertContentIdToBucket(data.contentId),
value: 1 * SCALE_FACTOR
});
// Set the flag in Shared Storage
await this.sharedStorage.set(key, true);
}
}
register('reach-measurement', ReachMeasurementOperation);
Contoh kode di atas akan memanggil Agregasi Pribadi setiap kali konten iframe lintas situs dimuat. Kode iframe memuat worklet, dan worklet memanggil Private Aggregation API dengan ID konten yang dikonversi ke kunci agregasi (bucket).
contributeToHistogramOnEvent()
Hanya dalam worklet Protected Audience API, kami menyediakan mekanisme berbasis pemicu untuk mengirim laporan hanya jika peristiwa tertentu terjadi. Fungsi ini juga memungkinkan bucket dan nilai bergantung pada sinyal yang belum tersedia pada saat lelang tersebut.
Metode privateAggregation.contributeToHistogramOnEvent(eventType, contribution)
menggunakan eventType
yang menentukan peristiwa pemicu, dan contribution
untuk dikirim saat peristiwa dipicu. Peristiwa pemicu dapat berasal dari lelang itu sendiri setelah lelang berakhir, seperti peristiwa kemenangan atau kekalahan lelang, atau dapat berasal dari frame dengan fence yang merender iklan.
Untuk mengirimkan laporan peristiwa lelang, Anda dapat menggunakan dua kata kunci yang dicadangkan, yaitu reserved.win
, reserved.loss
, dan reserved.always
. Untuk mengirim laporan yang dipicu oleh peristiwa dari frame dengan fence, tentukan jenis peristiwa kustom. Untuk memicu peristiwa dari frame dengan fence, gunakan metode fence.reportEvent()
yang tersedia dari Fenced Frames Ads Reporting API.
Contoh berikut mengirim laporan tayangan saat peristiwa kemenangan lelang dipicu, dan mengirim laporan klik jika peristiwa click
dipicu dari frame dengan fence yang merender iklan. Kedua nilai tersebut dapat digunakan untuk menghitung rasio klik-tayang (CTR).
function generateBid(interestGroup, auctionSignals, perBuyerSignals, trustedBiddingSignals, browserSignals) {
// …
privateAggregation.contributeToHistogramOnEvent("reserved.win", {
bucket: getImpressionReportBucket(),
value: 1
});
privateAggregation.contributeToHistogramOnEvent("click", {
bucket: getClickReportBuckets(), // 128-bit integer as BigInt
value: 1
});
Lihat penjelasan Pelaporan Agregasi Pribadi yang Diperluas untuk mempelajari lebih lanjut.
enableDebugMode()
Meskipun cookie pihak ketiga masih tersedia, kami akan memberikan mekanisme sementara yang mempermudah proses debug dan pengujian dengan mengaktifkan mode debug. Laporan debug berguna dalam membandingkan pengukuran berbasis cookie dengan pengukuran Agregasi Pribadi, dan juga memungkinkan Anda memvalidasi integrasi API dengan cepat.
Memanggil privateAggregation.enableDebugMode()
di worklet akan mengaktifkan mode debug yang menyebabkan laporan gabungan menyertakan payload (cleartext) yang tidak dienkripsi. Kemudian, Anda dapat memproses payload ini dengan alat pengujian lokal Layanan Agregasi.
Mode debug hanya tersedia bagi pemanggil yang diizinkan untuk mengakses
cookie pihak ketiga. Jika pemanggil tidak memiliki akses ke cookie pihak ketiga,
enableDebugMode()
akan gagal secara otomatis. Artinya, ketika pihak ketiga
cookie tidak digunakan lagi, mode debug tidak akan tersedia lagi.
Anda juga dapat menetapkan kunci debug dengan memanggil privateAggregation.enableDebugMode({ <debugKey: debugKey> })
, tempat BigInt
dapat digunakan sebagai kunci debug. Kunci debug dapat digunakan untuk mengaitkan data dari pengukuran berbasis cookie dan data dari pengukuran Agregasi Pribadi.
Metode ini hanya dapat dipanggil sekali per konteks. Setiap panggilan berikutnya akan menampilkan pengecualian.
// Enables debug mode
privateAggregation.enableDebugMode();
// Enables debug mode and sets a debug key
privateAggregation.enableDebugMode({ debugKey: BigInt(1234) });
Laporkan verifikasi
Untuk Penyimpanan Bersama, Anda dapat memverifikasi bahwa laporan agregat yang Anda terima sah dengan menambahkan ID konteks ke panggilan operasi penyimpanan bersama. ID akan dilampirkan ke laporan yang dikirim, dan di lain waktu, Anda dapat menggunakan ID tersebut untuk memverifikasi bahwa laporan dikirim dari operasi penyimpanan bersama yang Anda gunakan.
Untuk mempelajari lebih lanjut, lihat penjelasan verifikasi laporan.
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 ingin sekali mendengarnya.
- GitHub: Baca penjelasan, ajukan pertanyaan, dan berpartisipasi dalam diskusi.
- Dukungan developer: Ajukan pertanyaan dan ikuti diskusi di repo Dukungan Developer Privacy Sandbox.
- Bergabunglah dengan grup Storage API Bersama dan grup Protected Audience API untuk mendapatkan pengumuman terbaru terkait Private Aggregation.