Pelaporan lelang Protected Audience API

Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Mengukur data dan hasil lelang Protected Audience API

Dalam artikel ini, Anda akan menemukan ringkasan umum tentang berbagai mekanisme yang tersedia untuk melaporkan data lelang Protected Audience API ke server, 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 pribadi 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 render saat iklan dirender ke dalam bingkai berpagar 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 berpagar. 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, menilai iklan, dan melaporkan hasil lelang.

Objek auction config adalah sumber utama data yang disediakan agar tersedia sebagai sinyal di worklet. Penayang dan penjual dapat menyediakan 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 klik-tayang. Data yang dilaporkan dapat digunakan untuk pelaporan pembeli/penjual, penagihan, anggaran, pelatihan model ML, dan lainnya.

Data lain yang tersedia

• Data hasil yang terkait dengan data kemenangan dan kekalahan lelang seperti harga bid yang menang dan alasan penolakan bid.
• Data performa yang berisi informasi latensi, seperti 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 bingkai berpagar 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 lainnya yang terjadi di dalam bingkai.

Selama waktu konversi, saat pengguna melakukan beberapa tindakan di halaman klik-tayang yang diatribusikan kembali ke 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 menjelaskan informasi 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 berlaku, bingkai berpagar 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 berpagar 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 memigrasikan sistem ke Protected Audience.

Pelaporan kemenangan lelang tingkat peristiwa dengan sendReportTo()

Mekanisme yang tersedia untuk melaporkan data tingkat peristiwa di 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 disediakan saat rendering iklan dimulai. Anda dapat mengenkode sinyal apa pun yang tersedia di worklet sebagai parameter kueri URL.

Misalnya, pembeli dapat melaporkan jumlah bid pemenang 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 hingga setidaknya tahun 2026,

Laporan engagement

Laporan engagement berisi data tingkat peristiwa dari materi iklan seperti data tayangan atau klik yang dikaitkan 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 berpagar karena ID unik tidak dapat diteruskan dari penyempan karena komunikasi antara penyempan dan frame berpagar terbatas. Untuk mengaitkan data lelang dengan data tingkat peristiwa dari iklan bingkai berpagar, Ads Reporting API dapat digunakan.

Ads Reporting API untuk frame berpagar dan iframe

Ads Reporting API untuk frame berpagar 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, pada lain waktu saat iklan dirender dalam bingkai berpagar, Anda dapat memicu peristiwa kustom dengan memanggil fungsi window.fence.reportEvent(). Data yang tersedia dalam bingkai berpagar dapat ditambahkan sebagai payload.

Fungsi registerAdBeacon() hanya tersedia di fungsi pelaporan, dan tidak tersedia di logika bidding pembeli dan logika penskoran 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.

Untuk penjelasan lebih mendalam, lihat penjelasan.

Akses jaringan tanpa batasan

Frame berpagar akan memungkinkan pemuatan resource jaringan dengan cara yang sama seperti iframe, dan Anda dapat mengirim data tingkat peristiwa dalam frame berpagar ke server. Anda dapat membuat laporan tingkat peristiwa di sisi server nanti dengan mengaitkan data tingkat peristiwa dari frame berpagar dengan data lelang yang dikirim dengan sendReportTo() yang telah 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 mungkin 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.

Sementara kami mendesain solusi yang lebih permanen, Anda dapat menggunakan Ads Reporting API untuk frame berpagar sebagai mekanisme transisi untuk membuat laporan tingkat peristiwa dan agregat dengan Pelaporan Atribusi. Perhatikan bahwa laporan ini digunakan untuk mengukur konversi, dan terpisah dari laporan engagement tingkat peristiwa dan gabungan yang dihasilkan dari lelang dan frame iklan. Kami akan memublikasikan penjelasan untuk solusi yang lebih permanen jika sudah siap.

Mekanisme transisi

Saat mendaftarkan beacon iklan, Anda dapat menggunakan kata kunci reserved.top_navigation yang akan otomatis menambahkan header Attribution-Reporting-Eligible agar beacon memenuhi syarat untuk mendaftar 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 bingkai berpagar dengan payload peristiwa.

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

Lihat bagian Pelaporan Atribusi dalam 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, bingkai 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 atau iframe berpagar juga dikirim bersama 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 bingkai iklan, tetapkan auctionId sebagai parameter kueri URL beacon.
   2. Untuk mengaitkan sinyal lelang peristiwa konversi, tetapkan auctionId di URL beacon.
3. Selama waktu render iklan, beacon yang didaftarkan selama waktu lelang dapat dipicu atau ditingkatkan dengan data tingkat peristiwa.
   1. Memicu peristiwa frame dengan reportEvent() dan meneruskan data tingkat peristiwa.
   2. Menambahkan 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 didaftarkan selama waktu lelang.

Setelah proses di atas, pembeli akan memiliki laporan lelang, laporan engagement, dan laporan konversi, yang semuanya terikat 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 dapat 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 yang berisi banyak data yang dikumpulkan dalam bucket. Bucket direpresentasikan 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 ini.

Menggabungkan sinyal lelang

Anda dapat menggabungkan sinyal yang tersedia dalam worklet ke server menggunakan Agregasi Pribadi. Untuk agregasi sinyal, Anda dapat menggunakan metode privateAggregation.contributeToHistogram() yang tersedia di worklet bidding pembeli, worklet penskoran penjual , dan worklet pelaporan pembeli/penjual.

Dalam contoh ini, bid pemenang 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 jika sinyal yang ingin digabungkan tidak terkait dengan data tingkat peristiwa dan tidak dipicu oleh peristiwa di luar lelang. Untuk mempelajari lebih lanjut pelaporan sinyal lelang, lihat penjelasan.

Menggabungkan sinyal lelang dengan data peristiwa

Anda dapat menggabungkan sinyal lelang dengan informasi terbatas tentang peristiwa yang terjadi dalam bingkai iklan. Misalnya, Anda dapat mengukur secara agregat jumlah klik yang diterima iklan untuk kampanye dengan membuat bucket yang mewakili 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 menurut peristiwa, Anda dapat menggunakan privateAggregation.contributeToHistogramOnEvent(eventType, contribution) yang menggunakan 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 laporan yang akan dikirim.

Misalnya, Anda ingin mengukur jumlah klik yang diperoleh iklan untuk 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 meningkatkan nilai untuk bucket tersebut sebesar 1 setiap kali peristiwa dipicu.

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

Kemudian, pada lain waktu, dari bingkai 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 kemenangan atau kekalahan 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 pemenang, Anda dapat menetapkan jumlah yang akan ditambahkan atau dikurangi dari nilai tersebut, lalu melaporkan nilai akhir. Misalnya, jika bid pemenang sebesar $5 diberikan sebagai nilai dasar, Anda dapat mengurangi bid sebesar $2 untuk menghitung nilai sebenarnya sebesar $3 dari jumlah kerugian Anda dalam lelang.

Pelaporan hasil lelang

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

Untuk mengetahui selisih harga yang Anda kalahkan dalam lelang, Anda dapat mengurangi harga bid 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 dilaporkan sebenarnya akan berupa baseValue yang diskalakan dan digeser oleh nilai offset. Untuk mempelajari lebih lanjut, lihat penjelasan.

Pelaporan performa

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

Lihat penjelasan untuk mempelajari lebih lanjut.

Menyimpan sinyal lelang di Shared Storage

Penyimpanan bersama adalah penyimpanan lintas-asal yang tidak dipartisi dan dapat Anda tulis dengan bebas, tetapi dijaga dengan gate saat membaca dan memproses nilai yang disimpan. Salah satu gate yang tersedia untuk Shared Storage API adalah Private Aggregation. Anda hanya dapat membaca nilai dalam penyimpanan bersama dari dalam worklet, dan Anda dapat melaporkan nilai tersebut menggunakan Agregasi Pribadi dari worklet.

Anda juga dapat menulis ke penyimpanan bersama dari worklet bidding, penskoran, dan pelaporan Protected Audience API. Pada 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 Shared Storage lebih lanjut, lihat bagian penyimpanan bersama dalam 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.