Pelaporan lelang Protected Audience API

Mengukur data dan hasil lelang Protected Audience API

Dalam artikel ini, Anda akan menemukan ringkasan tingkat tinggi dari berbagai mekanisme yang tersedia untuk melaporkan data lelang Protected Audience API ke server Anda, beserta mekanisme transisi yang tersedia saat ini untuk Anda gunakan selama migrasi hingga solusi alternatif siap.

Untuk melaporkan metrik penting yang Anda kumpulkan dari lelang iklan, Protected Audience API berfungsi dengan:

• Private Aggregation yang mengumpulkan sinyal dan hasil lelang untuk membuat laporan ringkasan.
• Ads Reporting API untuk Fenced Frames dan iframe yang merupakan saluran dalam frame untuk berkomunikasi dengan worklet Protected Audience API. API ini memungkinkan pengaitan data tingkat peristiwa dengan sinyal lelang. Pelaporan tingkat peristiwa Ads Reporting API adalah mekanisme transisi hingga mekanisme pelaporan yang lebih privat dirancang.
• Attribution Reporting yang memungkinkan Anda mengaitkan data konversi dengan sinyal lelang.
• Shared Storage yang memungkinkan Anda menulis sinyal lelang ke penyimpanan lintas origin, lalu memungkinkan Anda melaporkan data tersebut nanti menggunakan Private Aggregation.

Ringkasan pelaporan Protected Audience API

Ada tiga jangka waktu utama saat data dari alur lelang Protected Audience API dapat dilaporkan ke server Anda: waktu lelang saat lelang dijalankan dari situs penayang, waktu rendering saat iklan dirender ke dalam frame tertutup atau iframe di situs penayang, dan waktu konversi saat pengguna melakukan beberapa tindakan di situs lain yang dapat diatribusikan ke lelang.

Selama waktu lelang, Anda dapat melaporkan data lelang menggunakan worklet pelaporan. Selama waktu render, Anda dapat melaporkan data engagement dari iframe atau frame tertutup. Selama waktu konversi, Anda dapat melaporkan data atribusi dari halaman tujuan menggunakan Attribution Reporting API.

Melaporkan lokasi

Dalam lelang, pembeli dapat melaporkan sinyal yang tersedia di worklet generateBid() dan reportWin(), dan penjual dapat melaporkan sinyal yang tersedia di scoreAd() dan reportResult(). Di luar lelang, pembeli dan penjual dapat melaporkan data dari frame yang merender iklan, dan dari situs tempat konversi dilakukan.

Selama setiap jangka waktu yang tercantum, pembeli dan penjual akan memiliki akses ke berbagai API pelaporan yang tersedia untuk melaporkan data seperti sinyal lelang, data tingkat peristiwa, dan data konversi.

Data yang tersedia dalam lelang Protected Audience API

Data berikut tersedia untuk dilaporkan dari worklet Protected Audience API selama lelang.

Sinyal

Sinyal adalah data kontekstual lelang, data pengguna, data real-time, dan data browser yang tersedia bagi pembeli dan penjual dalam worklet untuk membuat bid, memberi skor pada iklan, dan melaporkan hasil lelang.

Objek konfigurasi lelang adalah sumber utama data yang disediakan agar tersedia sebagai sinyal dalam worklet. Penayang dan penjual dapat memberikan data kontekstual dan data pihak pertama dalam konfigurasi lelang, dan sinyal ini dapat diperkaya dengan data grup minat dari pembeli, data tingkat peristiwa dari frame rendering iklan, dan data atribusi dari halaman click-through. Data yang dilaporkan dapat digunakan untuk pelaporan pembeli/penjual, penagihan, pembuatan anggaran, pelatihan model ML, dan lainnya.

Data lain yang tersedia

• Data hasil yang terkait dengan data menang dan kalah lelang seperti harga bid yang menang dan alasan penolakan bid.
• Data performa yang berisi informasi latensi, seperti berapa lama waktu yang diperlukan untuk mengambil dan menjalankan worklet bidding.

Data yang tersedia di luar lelang Protected Audience API

Di luar lelang Protected Audience API, ada dua jangka waktu saat data tersedia untuk dilaporkan.

Selama waktu render, saat iklan dirender di situs penayang, data tingkat peristiwa dari dalam iframe atau frame tertutup dapat dikaitkan dengan data lelang Protected Audience API, dan dilaporkan ke server Anda. Contoh data tingkat peristiwa mencakup tayangan iklan, klik-tayang, pengarahan kursor, dan peristiwa lain yang terjadi di dalam frame.

Selama waktu konversi, saat pengguna melakukan beberapa tindakan di halaman tayang-klik yang dikaitkan kembali dengan lelang, data tingkat peristiwa dari halaman konversi dapat dikaitkan dengan data lelang Protected Audience API, dan dilaporkan ke server Anda.

Pelaporan tingkat peristiwa

Laporan tingkat peristiwa memberikan informasi mendetail dari satu atau beberapa peristiwa. Peristiwa dapat berupa kemenangan lelang, tayangan iklan, atau konversi. Setidaknya hingga tahun 2026, pelaporan kemenangan lelang tingkat peristiwa akan tetap ada, frame tertutup tidak akan diperlukan untuk merender iklan Protected Audience, dan iframe dengan akses jaringan yang tidak dibatasi dapat digunakan untuk pelaporan tingkat peristiwa. Selain itu, Ads Reporting API tersedia di frame tertutup dan iframe agar Anda dapat mengaitkan data lelang dan konversi dengan data tingkat peristiwa dari frame. Hal ini dirancang agar ekosistem memiliki jalur migrasi yang lebih mudah, karena Anda dapat terus menggunakan infrastruktur pelaporan yang ada hingga setidaknya tahun 2026 saat Anda memigrasikan sistem ke Protected Audience.

Pelaporan kemenangan lelang tingkat peristiwa dengan sendReportTo()

Mekanisme yang tersedia untuk melaporkan data tingkat peristiwa dalam lelang Protected Audience adalah sendReportTo() function pada kemenangan lelang. Fungsi ini tersedia di worklet pelaporan pembeli dan penjual, dan browser membuat permintaan GET ke string URL yang diberikan saat rendering iklan dimulai. Anda dapat mengenkode sinyal apa pun yang tersedia di worklet sebagai parameter kueri URL.

Misalnya, pembeli dapat melaporkan jumlah bid yang menang dari worklet reportWin() untuk tujuan penagihan:

// Buyer reporting worklet
function reportWin(auctionSignals, perBuyerSignals, sellerSignals, browserSignals, directFromSellerSignals) {
  sendReportTo(`https://buyer-reporting-server.example/reporting?bid=${browserSignals.bid}`);
}

Fungsi sendReportTo() dapat digunakan untuk membuat laporan kemenangan bagi penjual saat dipanggil dari reportResult(), dan laporan kemenangan bagi pembeli saat dipanggil dari reportWin(). Fungsi sendReportTo() tersedia setidaknya hingga tahun 2026,

Laporan engagement

Laporan engagement berisi data tingkat peristiwa dari materi iklan, seperti data tayangan iklan atau klik yang terkait dengan sinyal lelang Protected Audience API yang merender iklan. Karena iklan dirender setelah lelang selesai, sinyal lelang tidak tersedia di dalam frame yang merender iklan. Untuk mengaitkan data ini dari jangka waktu yang berbeda, kami menyediakan dua mekanisme transisi untuk membuat laporan engagement.

Fungsi sendReportTo() yang dijelaskan di atas dapat digunakan untuk mengaitkan data lelang dengan data tingkat peristiwa dari iframe, tetapi tidak berfungsi untuk frame tertutup karena ID unik tidak dapat diteruskan dari penyemat karena komunikasi antara penyemat dan frame tertutup terbatas. Untuk mengaitkan data lelang dengan data tingkat peristiwa dari iklan frame tertutup, Ads Reporting API dapat digunakan.

Ads Reporting API untuk frame tertutup dan iframe

Ads Reporting API untuk frame tertutup dan iframe menyediakan mekanisme bagi Anda untuk mengaitkan data tingkat peristiwa pengguna dari frame iklan dengan sinyal dalam lelang Protected Audience.

Dalam worklet pelaporan Protected Audience API, Anda dapat mendaftarkan beacon iklan dengan fungsi registerAdBeacon() dan meneruskan URL pelaporan dengan sinyal yang ditambahkan sebagai parameter kueri. Anda juga menentukan peristiwa kustom yang ingin dikaitkan dengan URL pelaporan. Kemudian, di lain waktu saat iklan dirender dalam frame tertutup, Anda dapat memicu peristiwa kustom dengan memanggil fungsi window.fence.reportEvent(). Data yang tersedia dalam frame yang dibatasi dapat ditambahkan sebagai payload.

Fungsi registerAdBeacon() hanya tersedia di fungsi pelaporan, dan tidak tersedia di logika bidding pembeli dan logika pemberian skor penjual.

Dalam contoh berikut, ID kampanye dikaitkan dengan payload tingkat peristiwa dengan koordinat klik:

// Protected Audience API buyer win reporting worklet
function reportWin(auctionSignals) {
  const { campaignId } = auctionSignals

  registerAdBeacon({
    click: `https://buyer-server.example/report/click?campaignId=${campaignId}`
  })
}

// Protected Audience API seller reporting worklet
function reportResult(auctionConfig) {
  const { campaignId } = auctionConfig.auctionSignals;

  registerAdBeacon({
    click: `https://seller-server.example/report/click?campaignId=${campaignId}`
  })
}

// Ad frame
window.fence.reportEvent({
  eventType: 'click',
  eventData: JSON.stringify({'clickX': '123', 'clickY': '456'}),
  destination:['buyer', 'seller']
});

Fenced Frames Ads Reporting API juga akan tersedia hingga setidaknya tahun 2026 karena alasan yang sama dengan pelaporan kemenangan lelang.

Untuk penjelasan lebih mendalam, lihat penjelasan.

Akses jaringan tanpa batasan

Frame tertutup akan memungkinkan pemuatan resource jaringan dengan cara yang sama seperti iframe, dan Anda dapat mengirim data tingkat peristiwa dalam frame tertutup ke server Anda. Anda dapat membuat laporan tingkat peristiwa di sisi server nanti dengan mengaitkan data tingkat peristiwa dari frame tertutup dengan data lelang yang dikirim dengan sendReportTo() yang dibahas di bagian mekanisme pelaporan tingkat peristiwa lelang di atas.

Akses jaringan akan dibatasi pada masa mendatang.

Laporan atribusi

Laporan atribusi memungkinkan Anda mengaitkan konversi di situs dengan iklan yang dipilih dari lelang Protected Audience API. Misalnya, pengguna dapat mengklik iklan produk yang Anda tayangkan, dialihkan ke situs pengiklan, melakukan pembelian di sana, dan Anda tertarik untuk mengatribusikan pembelian tersebut ke iklan yang ditampilkan. Attribution Reporting API akan diintegrasikan dengan Protected Audience API untuk menggabungkan data lelang dari situs penayang dan data konversi dari situs pengiklan.

Saat kami mendesain solusi yang lebih permanen, Anda dapat menggunakan Ads Reporting API untuk frame tertutup sebagai mekanisme transisi untuk membuat laporan tingkat peristiwa dan agregat dengan Attribution Reporting. Perhatikan bahwa laporan ini digunakan untuk mengukur konversi, dan terpisah dari laporan engagement tingkat peristiwa dan gabungan yang dibuat dari lelang dan frame iklan. Kami akan memublikasikan penjelasan untuk solusi yang lebih permanen saat siap.

Mekanisme transisi

Saat mendaftarkan suar iklan, Anda dapat menggunakan kata kunci reserved.top_navigation yang akan otomatis menambahkan header Attribution-Reporting-Eligible agar suar memenuhi syarat untuk didaftarkan sebagai sumber atribusi.

registerAdBeacon({
 'reserved.top_navigation': 'https://adtech.example/click?buyer_event_id=123',
});

Untuk melampirkan data tingkat peristiwa ke beacon yang Anda daftarkan, Anda dapat memanggil setReportEventDataForAutomaticBeacons() dari frame yang dibatasi dengan payload peristiwa.

window.fence.setReportEventDataForAutomaticBeacons({
  eventType: 'reserved.top_navigation',
  eventData: 'data from the frame',
  destination:['seller', 'buyer']
})

Lihat bagian Attribution Reporting pada penjelasan Ads Reporting API untuk mempelajari lebih lanjut.

Contoh pelaporan engagement dan konversi

Dalam contoh ini, kita akan melihatnya dari perspektif pembeli yang tertarik untuk mengaitkan data dari lelang, frame iklan, dan situs konversi secara bersamaan.

Dalam alur kerja ini, pembeli berkoordinasi dengan penjual untuk mengirimkan ID unik ke lelang. Selama lelang, pembeli mengirimkan ID unik ini bersama dengan data lelang. Selama waktu render dan konversi, data dari frame tertutup atau iframe juga dikirim dengan ID unik yang sama. Selanjutnya, ID unik tersebut dapat digunakan untuk mengaitkan laporan ini secara bersamaan.

Alur kerja:

1. Sebelum lelang dimulai, pembeli mengirimkan ID unik ke penjual sebagai bagian dari respons bid bidding real-time ("RTB") terprogram mereka. ID dapat ditetapkan sebagai variabel seperti auctionId. ID diteruskan sebagai perBuyerSignals di auctionConfig dan akan tersedia di worklet pembeli.
2. Selama waktu lelang, pembeli dapat mendaftarkan beacon iklan agar dipicu selama waktu render iklan dan waktu konversi (registerAdBeacon()).
   1. Untuk mengaitkan sinyal lelang peristiwa frame iklan, tetapkan auctionId sebagai parameter kueri URL beacon.
   2. Untuk mengaitkan sinyal lelang peristiwa konversi, tetapkan auctionId di URL suar.
3. Selama waktu render iklan, beacon yang didaftarkan selama waktu lelang dapat dipicu atau ditingkatkan dengan data tingkat peristiwa.
   1. Picu peristiwa frame dengan reportEvent() dan teruskan data tingkat peristiwa.
   2. Tambahkan payload tingkat peristiwa ke beacon atribusi dengan setReportEventDataForAutomaticBeacons()
   3. Daftarkan iklan ke Attribution Reporting API dengan merespons permintaan beacon iklan menggunakan header Attribution-Reporting-Register-Source.
4. Selama waktu konversi, Anda dapat memicu sumber yang Anda daftarkan selama waktu lelang.

Setelah proses di atas, pembeli akan memiliki laporan lelang, laporan engagement, dan laporan konversi, yang semuanya diikat oleh satu kunci unik yang dapat digunakan untuk mengaitkan satu sama lain.

Alur kerja serupa berlaku untuk penjual jika memerlukan akses ke data atribusi, dan penjual juga dapat menggunakan ID unik untuk mengirim dengan registerAdBeacon(). Dari frame, panggilan reportEvent() berisi properti tujuan yang dapat digunakan untuk mengirim laporan kepada pembeli dan penjual. Perhatikan bahwa SSP juga harus ada di halaman landing agar pemicu diatribusikan ke sumber.

Menggabungkan data Protected Audience

Private Aggregation API adalah mekanisme yang digunakan untuk melaporkan data Protected Audience guna membuat laporan ringkasan, yang merupakan laporan gabungan data yang bernoise dan dikumpulkan dalam bucket. Bucket diwakili oleh kunci agregasi, dan beberapa informasi dapat dienkode ke dalam kunci.

Misalnya, peristiwa tayangan iklan dapat dihitung ke dalam bucket yang berbeda, dengan setiap bucket mewakili kampanye iklan yang berbeda. Laporan ringkasan berbeda dengan laporan tingkat peristiwa karena tidak mengungkapkan informasi tentang setiap peristiwa. Dengan laporan tingkat peristiwa, Anda dapat menentukan bahwa pengguna A, B, dan C telah melihat kampanye 123. Dengan laporan ringkasan, Anda dapat mengukur jumlah pengguna yang telah melihat kampanye 123 dan derau ditambahkan untuk melindungi privasi pengguna.

Lihat artikel Private Aggregation untuk mengetahui informasi selengkapnya tentang API.

Menggabungkan sinyal lelang

Anda dapat menggabungkan sinyal yang tersedia dalam worklet ke server Anda menggunakan Private Aggregation. Untuk agregasi sinyal, Anda dapat menggunakan metode privateAggregation.contributeToHistogram() yang tersedia di worklet bidding pembeli, worklet pemberian skor penjual , dan worklet pelaporan pembeli/penjual.

Dalam contoh ini, bid yang menang digabungkan ke dalam bucket pemilik grup minat:

function convertBuyerToBucket(igOwner) {}
function convertWinningBidToValue(winningBid) {}

function reportResult(auctionConfig, browserSignals) {
  privateAggregation.contributeToHistogram({
    bucket: convertBuyerToBucket(browserSignals.interestGroupOwner),
    value: convertWinningBidToValue(browserSignals.bid)
  });
} 

Ini adalah mekanisme umum yang digunakan saat sinyal yang ingin Anda gabungkan tidak terkait dengan data tingkat peristiwa dan tidak dipicu oleh peristiwa di luar lelang. Untuk mempelajari lebih lanjut cara melaporkan sinyal lelang, lihat penjelasan.

Menggabungkan sinyal lelang dengan data peristiwa

Anda dapat menggabungkan sinyal lelang dengan informasi terbatas tentang peristiwa yang terjadi di frame iklan. Misalnya, Anda dapat mengukur secara gabungan berapa banyak klik yang diterima iklan untuk kampanye dengan membuat bucket yang merepresentasikan kampanye tersebut dan peristiwa klik. Perhatikan bahwa dari frame iklan, Anda dapat menentukan peristiwa yang telah terjadi, tetapi Anda tidak dapat melampirkan payload tingkat peristiwa.

Untuk menggabungkan sinyal lelang berdasarkan peristiwa, Anda dapat menggunakan privateAggregation.contributeToHistogramOnEvent(eventType, contribution) yang mengambil string yang menentukan jenis peristiwa dan kontribusi yang akan dilaporkan saat peristiwa tersebut dipicu. Anda dapat memanggil metode dengan jenis peristiwa kustom, lalu memanggil window.fence.reportEvent(eventType) dari frame iklan untuk memicu pengiriman laporan.

Misalnya, Anda ingin mengukur jumlah klik yang diperoleh iklan untuk suatu kampanye.

// Protected Audience API worklet
function getClickReportBucketForCampaign(campaignId) {
  // return a bucket for the campaign ID and the click event
}

function generateBid(interestGroup) {
  privateAggregation.contributeToHistogramOnEvent('click', {
    bucket: getClickReportBucketForCampaign(interestGroup.ads.metadata.campaignId), 
    value: 1
  });
}

Dalam fungsi pembuatan bid, Anda dapat menentukan bucket sebagai kombinasi ID kampanye dan peristiwa klik, lalu menaikkan nilai untuk bucket tersebut sebesar 1 setiap kali peristiwa dipicu.

// Ad frame
window.fence.reportEvent('click');

Kemudian, di lain waktu, dari frame iklan, Anda dapat memicu pengiriman laporan dengan memanggil reportEvent(eventType):

Pelajari lebih lanjut cara memicu kontribusi Private Aggregation dari frame dari penjelasan.

Melaporkan hasil dan performa lelang

Anda juga dapat menggabungkan hasil lelang saat dipicu oleh peristiwa menang atau kalah dalam lelang dengan contributeToHistogramOnEvent(eventType, contribution) saat Anda meneruskan kata kunci jenis peristiwa yang dicadangkan (reserved.win, reserved.loss, dan reserved.always).

Agregasi Pribadi menyediakan daftar nilai dasar yang dapat Anda gunakan untuk menghitung bucket dan nilai kontribusi Anda. Nilai dasar yang tersedia untuk hasil lelang adalah nilai bid iklan pemenang, nilai bid yang diberi skor tertinggi kedua, dan alasan bid ditolak dari lelang.

Jika beberapa nilai dasar diberikan, seperti jumlah bid yang menang, Anda dapat menetapkan jumlah yang akan ditambahkan atau dikurangi dari nilai tersebut, lalu melaporkan nilai akhir. Misalnya, jika bid yang menang sebesar $5 diberikan sebagai nilai dasar, Anda dapat mengurangi bid sebesar $2 untuk menghitung nilai sebenarnya sebesar $3 dari seberapa besar Anda kalah dalam lelang.

Pelaporan hasil lelang

Mari kita lihat contoh saat Anda kalah dalam lelang, dan Anda ingin mengetahui seberapa jauh selisih bid Anda dari harga penyelesaian lelang.

Untuk mengetahui selisih harga bid Anda dengan harga bid pemenang, Anda dapat mengurangkan harga bid Anda dari harga bid pemenang:

function generateBid() {
  const bid = calculateBidAmount();

  privateAggregation.contributeToHistogramOnEvent('reserved.loss', {
    bucket: getBucketForCampaign(interestGroup.ads.metadata.campaignId),
    value: {
      baseValue: 'winning-bid',
      scale: 1 // Scale the value to minimize noise-to-signal ratio 
      offset: -bid, // Numbers added to browser value after scaling 
    }
  });
}

Saat laporan dikirimkan, nilai yang sebenarnya dilaporkan akan menjadi baseValue yang diskalakan dan digeser oleh nilai offset. Untuk mempelajari lebih lanjut, lihat penjelasan.

Pelaporan performa

Pembeli dan penjual dapat melaporkan berapa lama waktu yang dibutuhkan skrip untuk dieksekusi, dan berapa lama waktu yang dibutuhkan untuk mengambil sinyal tepercaya. Penjual dapat mengumpulkan waktu pembuatan bid dan waktu sinyal bidding tepercaya setiap pembeli dengan izin mereka.

Lihat penjelasan untuk mempelajari lebih lanjut.

Menyimpan sinyal lelang di Shared Storage

Penyimpanan bersama adalah penyimpanan lintas origin dan tidak dipartisi yang dapat Anda tulis dengan bebas, tetapi dilindungi dengan gerbang saat membaca dan memproses nilai yang disimpan. Salah satu gerbang yang tersedia untuk Shared Storage API adalah Private Aggregation. Anda hanya dapat membaca nilai di penyimpanan bersama dari dalam worklet, dan Anda dapat melaporkan nilai tersebut menggunakan Private Aggregation dari worklet.

Anda juga dapat menulis ke penyimpanan bersama dari bidding, pemberian skor, dan worklet pelaporan Protected Audience API. Di lain waktu, Anda dapat melaporkan nilai tersebut di penyimpanan bersama ke server menggunakan Private Aggregation . Anda juga dapat menggunakan nilai yang disimpan untuk operasi Pemilihan URL.

Dari worklet Protected Audience API, Anda dapat menulis kunci dan nilai apa pun ke penyimpanan bersama:

// Protected Audience API worklet
function generateBid() {
  sharedStorage.set('test-bucket', 123);
}

Di lain waktu, Anda dapat memuat worklet penyimpanan bersama untuk membaca dan mengirim nilai tersebut dengan Private Aggregation:

// Shared Storage worklet
class SendReachReport{
  async run() {
    const testBucket = await this.sharedStorage.get('test-bucket');

    privateAggregation.contributeToHistogram({
      bucket: testBucket,
      value: 1
    });
  }
}

register('send-report', SendReachReport);

Untuk mempelajari lebih lanjut Shared Storage, lihat bagian shared storage di panduan developer pelaporan Protected Audience API, penjelasan, demo langsung, dan kode demo di GitHub.

Apa selanjutnya?

Kami ingin berbincang dengan Anda untuk memastikan bahwa kami membangun API yang berlaku untuk semua orang.

Diskusikan API

Seperti API Privacy Sandbox lainnya, API ini didokumentasikan dan dibahas secara publik.

Bereksperimen dengan API

Anda dapat bereksperimen dan berpartisipasi dalam percakapan tentang Protected Audience API.