Ringkasan Private Aggregation API

Buat laporan data gabungan menggunakan data dari Protected Audience dan data lintas situs dari Shared Storage.

Untuk menyediakan fitur penting yang menjadi andalan web, Private Aggregation API telah dibuat untuk menggabungkan dan melaporkan data lintas situs dengan cara yang menjaga privasi.

Status penerapan

提案 状态
通过对共享存储空间的报告进行验证，防止 Private Aggregation API 报告无效
说明		 在 Chrome 中提供
私有汇总调试模式的可用性取决于 3PC 资格条件
GitHub 问题		 适用于 Chrome M119
缩短报告延迟时间
说明		 适用于 Chrome M119
共享存储空间的不公开汇总贡献超时
说明		 适用于 M119
支持 Google Cloud 专用汇总 API 和汇总服务
说明		 适用于 Chrome M121
可汇总报告载荷的填充
说明		 适用于 Chrome M119
私密汇总调试模式适用于 auctionReportBuyers 报告
说明		 适用于 Chrome M123
过滤 ID 支持
说明		 适用于 Chrome M128
客户端贡献合并
说明		 适用于 Chrome M129

Apa yang dimaksud dengan Private Aggregation API

Private Aggregation API memungkinkan developer membuat laporan data gabungan dengan data dari Protected Audience API dan data lintas situs dari Shared Storage.

Fungsi utama API ini dikenal sebagai contributeToHistogram(). Operasi histogram memungkinkan Anda menggabungkan data di seluruh pengguna dalam setiap bucket (dikenal di API sebagai kunci agregasi) yang Anda tentukan. Panggilan histogram Anda mengakumulasi nilai dan menampilkan hasil gabungan yang berisi derau dalam bentuk laporan ringkasan. Misalnya, laporan mungkin menampilkan jumlah situs tempat setiap pengguna melihat konten Anda, atau menemukan bug dalam skrip pihak ketiga Anda. Operasi ini dilakukan dalam worklet API lain.

Misalnya, jika sebelumnya Anda telah mencatat data demografis dan geografis di Shared Storage, Anda dapat menggunakan Private Aggregation API untuk membuat histogram yang memberi tahu Anda perkiraan jumlah pengguna di New York City yang telah melihat konten Anda di seluruh 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 membuat laporan agregat.

Laporan agregat dikirim ke server Anda untuk pengumpulan dan pengelompokan. Laporan batch akan diproses kemudian 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 tersebut menghasilkan laporan agregat yang digunakan oleh backend Layanan Agregasi untuk membuat laporan ringkasan.

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.

Menguji API ini

Untuk menguji Private Aggregation API secara lokal, aktifkan semua Ad privacy API di bagian chrome://settings/adPrivacy.

Baca selengkapnya tentang pengujian di eksperimen dan berpartisipasi.

Menggunakan demo

Demo Private Aggregation API untuk Shared Storage 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 Shared Storage dan Protected Audience API. Langkah pertama adalah menentukan secara spesifik informasi yang ingin Anda kumpulkan. Titik data tersebut adalah dasar kunci agregasi Anda.

Dengan Penyimpanan bersama

Shared Storage memungkinkan Anda membaca dan menulis data lintas situs di lingkungan yang aman untuk mencegah kebocoran, dan 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 kontennya. Private Aggregation API dapat memberikan jawaban seperti "Sekitar 317 pengguna unik telah melihat Content ID 861".

Anda dapat menetapkan tanda di Penyimpanan Bersama untuk menunjukkan apakah pengguna telah melihat konten atau belum. Pada kunjungan pertama saat tanda tidak ada, panggilan ke Agregasi Pribadi akan dilakukan, lalu tanda akan ditetapkan. Pada kunjungan berikutnya oleh pengguna, termasuk kunjungan lintas situs, Anda dapat memeriksa Penyimpanan Bersama dan melewati pengiriman laporan ke Agregasi Pribadi jika tanda tersebut ditetapkan. Untuk mempelajari lebih lanjut metode penerapan pengukuran ini, lihat laporan resmi jangkauan kami.

Pengukuran demografi

Anda mungkin ingin mengukur demografi pengguna yang telah melihat konten Anda di berbagai situs.

Agregasi Pribadi dapat memberikan jawaban, seperti "Sekitar 317 pengguna unik berusia 18-45 tahun dan berasal dari Jerman". Gunakan Penyimpanan Bersama untuk mengakses data demografi dari konteks pihak ketiga. Pada waktu berikutnya, Anda dapat membuat laporan dengan Agregasi Pribadi dengan mengenkode dimensi kelompok usia dan negara di kunci agregasi.

Pengukuran frekuensi K+

Anda mungkin ingin mengukur jumlah pengguna yang telah melihat konten atau iklan setidaknya K kali di browser tertentu, untuk nilai K yang telah dipilih sebelumnya.

Agregasi Pribadi dapat memberikan jawaban seperti "Sekitar 89 pengguna telah melihat Content ID 581 setidaknya 3 kali". Penghitung dapat bertambah di Penyimpanan Bersama dari berbagai situs dan dapat dibaca dalam worklet. Jika jumlahnya telah mencapai K, laporan dapat dikirim menggunakan Agregasi Pribadi.

Atribusi multi-sentuh

Panduan ini akan dipublikasikan di situs developer agar teknologi iklan dapat memahami cara menerapkan MTA dalam Penyimpanan Bersama + Agregasi Pribadi.

Dengan Protected Audience API

Protected Audience API memungkinkan kasus penggunaan penargetan ulang dan audiens kustom, dan 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 Shared Storage dan Protected Audience API.

contributeToHistogram()

Anda dapat memanggil privateAggregation.contributeToHistogram({ bucket: <bucket>, value: <value> }), dengan kunci agregasi bucket dan nilai agregat sebagai value. Untuk parameter bucket, BigInt wajib ada. Untuk parameter value, Bilangan bilangan bulat diperlukan.

Berikut adalah contoh cara memanggilnya 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 sharedStorage.get(key) === 'true';

    // Don't 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 sharedStorage.set(key, true);
  }
}

register('reach-measurement', ReachMeasurementOperation);

Contoh kode sebelumnya 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 menjadi 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 titik tersebut dalam lelang.

Metode privateAggregation.contributeToHistogramOnEvent(eventType, contribution) menggunakan eventType yang menentukan peristiwa pemicu, dan contribution yang akan 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 bingkai berpagar yang merender iklan.

Untuk mengirim laporan peristiwa lelang, Anda dapat menggunakan dua kata kunci yang dicadangkan, reserved.win, reserved.loss, dan reserved.always. Untuk mengirimkan laporan yang dipicu oleh peristiwa dari bingkai yang dibatasi, tentukan jenis peristiwa kustom. Untuk memicu peristiwa dari bingkai berpagar, gunakan metode fence.reportEvent() yang tersedia dari Fenced Frames Ads Reporting API.

Contoh berikut mengirimkan laporan tayangan saat peristiwa kemenangan lelang dipicu, dan mengirimkan laporan klik jika peristiwa click dipicu dari bingkai berpagar yang merender iklan. Kedua nilai ini dapat digunakan untuk menghitung rasio klik-tayang.

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 menyediakan mekanisme sementara yang memungkinkan proses debug dan pengujian yang lebih mudah dengan mengaktifkan mode debug. Laporan debug berguna untuk 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 agregat menyertakan payload (cleartext) yang tidak dienkripsi. Kemudian, Anda dapat memproses payload ini dengan alat pengujian lokal Layanan Agregasi.

Mode debug hanya tersedia untuk pemanggil yang diizinkan untuk mengakses cookie pihak ketiga. Jika pemanggil tidak memiliki akses ke cookie pihak ketiga, enableDebugMode() akan gagal tanpa ada peringatan.

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.

Fungsi 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) });

Verifikasi laporan

Private Aggregation API memungkinkan pengukuran lintas situs sekaligus melindungi privasi pengguna. Namun, pihak tidak bertanggung jawab dapat mencoba memanipulasi akurasi pengukuran ini. Untuk mencegah hal ini, Anda dapat menggunakan ID konteks untuk memverifikasi autentisitas laporan.

Menetapkan ID konteks membantu memastikan bahwa data akurat saat berkontribusi pada hasil gabungan akhir. Hal ini dapat dilakukan dengan:

  • Mencegah laporan yang tidak sah atau tidak autentik: Pastikan laporan dibuat melalui panggilan API yang sah dan autentik, sehingga pelaku kejahatan sulit membuat laporan palsu.
  • Mencegah pemutaran ulang laporan: Mendeteksi dan menolak setiap upaya untuk menggunakan kembali laporan lama, memastikan bahwa setiap laporan hanya berkontribusi satu kali ke hasil agregat.

Penyimpanan Bersama

Saat menggunakan Shared Storage untuk menjalankan operasi yang dapat mengirim laporan agregat, Anda dapat menetapkan ID yang tidak dapat diprediksi di luar worklet.

ID ini disematkan dalam laporan yang dibuat dari worklet. Anda dapat menentukannya saat memanggil metode Penyimpanan Bersama run() atau selectURL(), dalam objek opsi pada kunci privateAggregationConfig.

Contoh:

sharedStorage.run('measurement-operation', {
  privateAggregationConfig: {
    contextId: 'exampleId123456789abcdeFGHijk'
  }
});

Setelah ID ini ditetapkan, Anda dapat menggunakannya untuk memverifikasi bahwa laporan dikirim dari operasi Penyimpanan Bersama. Untuk mencegah kebocoran informasi, tepat satu laporan dikirim per operasi Penyimpanan Bersama (meskipun tidak ada kontribusi yang dilakukan), terlepas dari jumlah panggilan contributeToHistogram().

Private Aggregation API mengirimkan laporan agregat dengan penundaan acak hingga satu jam. Namun, menetapkan ID konteks untuk memverifikasi laporan akan mengurangi penundaan ini. Dalam hal ini, ada penundaan tetap yang lebih kecil sebesar 5 detik sejak operasi Penyimpanan Bersama dimulai.

Contoh alur kerja untuk verifikasi laporan

Contoh alur kerja (seperti yang ditunjukkan dalam diagram di atas):

  1. Operasi Penyimpanan Bersama dijalankan dengan konfigurasi Agregasi Pribadi yang menentukan ID konteks dan laporan agregat dihasilkan.
  2. ID konteks disematkan dalam laporan agregat yang dihasilkan dan dikirim ke server Anda.
  3. Server Anda mengumpulkan laporan gabungan yang dihasilkan.
  4. Proses di server Anda memeriksa ID konteks dalam setiap laporan agregat dengan ID konteks yang disimpan untuk memastikan validitasnya sebelum mengelompokkan laporan dan mengirimkannya ke Layanan Agregasi.

Verifikasi ID Konteks

Laporan masuk ke server kolektor Anda dapat diverifikasi dengan beberapa cara yang berbeda sebelum dikirim ke Layanan Agregasi. Laporan dengan ID konteks tidak valid dapat ditolak jika ID Konteks:

  • Tidak diketahui: Jika laporan tiba dengan ID konteks yang belum dibuat oleh sistem, Anda dapat menghapusnya. Tindakan ini mencegah pelaku yang tidak dikenal atau berbahaya memasukkan data ke dalam pipeline agregasi Anda.
  • Duplikat: Jika Anda menerima dua (atau lebih) laporan dengan ID konteks yang sama, artinya Anda harus memilih laporan mana yang akan dihapus.
  • Dilaporkan dalam deteksi spam:
    • Jika Anda mendeteksi aktivitas mencurigakan dari pengguna, misalnya perubahan mendadak pada aktivitas pengguna, saat memproses laporannya, Anda dapat menghapusnya.
    • Anda dapat menyimpan laporan beserta ID konteksnya dan sinyal relevan apa pun (misalnya, agen pengguna, sumber rujukan, dll.). Kemudian, saat menganalisis perilaku pengguna dan mengidentifikasi indikator spam baru, Anda dapat mengevaluasi ulang laporan yang disimpan berdasarkan ID dan sinyal konteks terkait. Dengan begitu, Anda dapat menghapus laporan dari pengguna yang menunjukkan aktivitas mencurigakan, meskipun awalnya tidak ditandai.

Berinteraksi dan memberikan masukan

Private Aggregation API sedang dalam diskusi aktif dan dapat berubah di masa mendatang. Jika Anda mencoba API ini dan memiliki masukan, kami ingin mendengarnya.