Pelaporan lelang Protected Audience API

Mengukur data dan hasil lelang Protected Audience API

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

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

• Agregasi Pribadi 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 memungkinkan pengaitan data tingkat peristiwa dengan sinyal lelang. Pelaporan tingkat peristiwa Ads Reporting API merupakan mekanisme transisi hingga mekanisme pelaporan yang lebih pribadi didesain.
• Pelaporan Atribusi yang memungkinkan Anda mengaitkan data konversi dengan sinyal lelang.
• Penyimpanan Bersama yang memungkinkan Anda menulis sinyal lelang ke penyimpanan lintas asal, lalu memungkinkan Anda melaporkan data tersebut nanti menggunakan Agregasi Pribadi.

Ringkasan pelaporan Protected Audience API

Ada tiga jangka waktu utama tempat 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 frame dengan fence 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 interaksi dari iframe atau frame dengan fence. 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(), serta 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 dibuat.

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 tersedia dalam lelang Protected Audience API

Data berikut dapat 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 konfigurasi lelang adalah sumber utama data yang disediakan untuk tersedia sebagai sinyal di worklet. Penayang dan penjual dapat menyediakan data kontekstual dan data pihak pertama dalam konfigurasi lelang, serta 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, penganggaran, pelatihan model ML, dan lainnya.

Data lain yang tersedia

• Data hasil yang berkaitan dengan data kemenangan dan kekalahan lelang seperti harga bid yang menang dan alasan penolakan bid.
• Data performa yang berisi informasi latensi, seperti waktu yang dibutuhkan untuk mengambil dan menjalankan worklet bidding.

Data tersedia di luar lelang Protected Audience API

Di luar lelang Protected Audience API, ada dua jangka waktu yang dapat digunakan untuk melaporkan data.

Selama waktu render, saat iklan dirender di situs penayang, data tingkat peristiwa dari dalam iframe atau frame dengan fence 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 menampilkan informasi detail dari satu atau beberapa peristiwa. Peristiwa dapat berupa kemenangan lelang, tayangan iklan, atau konversi. Hingga setidaknya tahun 2026, pelaporan kemenangan lelang tingkat peristiwa akan tetap berlaku, frame dengan fence 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 dalam frame dan iframe fence agar Anda dapat mengaitkan data lelang dan konversi dengan data tingkat peristiwa dari frame. Tindakan ini dirancang untuk memudahkan ekosistem dalam melakukan migrasi 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 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 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 untuk pembeli saat dipanggil dari reportWin(). Fungsi sendReportTo() tersedia hingga setidaknya 2026,

Laporan engagement

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

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

Ads Reporting API untuk bingkai dan iframe fence

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

Fungsi registerAdBeacon() hanya tersedia dalam fungsi pelaporan, dan tidak tersedia dalam logika bidding pembeli dan logika penskoran penjual.

Pada 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 dengan alasan yang sama seperti pelaporan kemenangan.

Untuk mempelajari lebih lanjut, lihat penjelasan ini.

Akses jaringan tanpa batasan

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

Akses jaringan akan dibatasi di 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 mengaitkan pembelian pada iklan yang ditampilkan. Attribution Reporting API akan terintegrasi dengan Protected Audience API untuk menggabungkan data lelang dari situs penayang dan data konversi dari situs pengiklan.

Meskipun kami mendesain solusi yang lebih permanen, Anda dapat menggunakan Ads Reporting API untuk frame dengan fence sebagai mekanisme transisi untuk membuat laporan agregat dan tingkat peristiwa dengan Attribution Reporting. Perhatikan bahwa laporan ini ditujukan untuk mengukur konversi, dan terpisah dari laporan engagement tingkat peristiwa dan agregat 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 didaftarkan, Anda dapat memanggil setReportEventDataForAutomaticBeacons() dari frame dengan fence 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, 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 data lelang. Selama waktu render dan konversi, data dari frame atau iframe fence juga dikirim bersama 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 untuk dipicu selama waktu render iklan dan waktu konversi (registerAdBeacon()).
   1. Guna mengaitkan sinyal lelang untuk peristiwa frame 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. Picu peristiwa frame dengan reportEvent() dan teruskan 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, semuanya digabungkan 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 berisi data yang 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-beda, dengan setiap bucket merepresentasikan kampanye iklan yang berbeda. Laporan ringkasan berbeda dari laporan tingkat peristiwa karena tidak mengungkapkan informasi tentang setiap peristiwa. Dengan laporan tingkat peristiwa, Anda dapat mengetahui apakah pengguna A, B, dan C telah melihat kampanye 123. Dengan laporan ringkasan, Anda dapat mengukur jumlah pengguna yang telah melihat kampanye 123 dan derau yang ditambahkan untuk melindungi privasi pengguna.

Lihat artikel Agregasi Pribadi untuk mengetahui informasi selengkapnya tentang API.

Menggabungkan sinyal lelang

Anda dapat menggabungkan sinyal yang tersedia dalam worklet ke server menggunakan Agregasi Pribadi. Untuk penggabungan sinyal, Anda dapat menggunakan metode privateAggregation.contributeToHistogram() yang tersedia di worklet bidding pembeli, worklet penskoran penjual , dan alur kerja 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 dalam frame iklan. Misalnya, Anda dapat mengukur secara gabungan jumlah klik yang diterima suatu 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 menambahkan payload tingkat peristiwa.

Untuk menggabungkan sinyal lelang berdasarkan 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 agar dikirimkan.

Misalnya, Anda ingin mengukur jumlah klik yang diterima suatu 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 meningkatkan 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 Agregasi Pribadi dari frame dalam penjelasan ini.

Melaporkan hasil dan performa lelang

Anda juga dapat menggabungkan hasil lelang saat dipicu oleh peristiwa menang atau kalah lelang dengan contributeToHistogramOnEvent(eventType, contribution) saat 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 ditambah atau dikurangi dari nilai tersebut, lalu melaporkan nilai akhir. Misalnya, jika bid pemenang sebesar Rp50.000 diberikan sebagai nilai dasar, Anda dapat mengurangi bid sebesar Rp20.000 untuk menghitung nilai sebenarnya sebesar Rp30.000 dari jumlah kerugian lelang Anda.

Pelaporan hasil lelang

Mari kita lihat contoh di mana Anda kalah dalam lelang, dan Anda ingin mengetahui seberapa jauh tawaran Anda dari harga kliring lelang.

Untuk mengetahui seberapa banyak Anda kalah dalam lelang, Anda dapat mengurangi harga bid dari harga bid yang menang:

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 aktual yang dilaporkan akan berupa baseValue yang diskalakan dan diubah oleh nilai offset. Untuk mempelajari lebih lanjut, lihat penjelasan ini.

Pelaporan performa

Pembeli dan penjual dapat melaporkan berapa lama waktu yang diperlukan untuk mengeksekusi skrip, 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 Penyimpanan Bersama

Penyimpanan bersama adalah penyimpanan lintas origin dan tidak dipartisi yang dapat Anda gunakan untuk menulis dengan bebas, tetapi dilindungi 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 di penyimpanan bersama dari dalam worklet, dan melaporkan nilai tersebut menggunakan Agregasi Pribadi dari worklet.

Anda juga dapat menulis ke penyimpanan bersama dari worklet pelaporan, penskoran, dan bidding Protected Audience API. Di lain waktu, Anda dapat melaporkan nilai tersebut dalam penyimpanan bersama ke server menggunakan Agregasi Pribadi . 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 Penyimpanan Bersama lebih lanjut, lihat bagian penyimpanan bersama dalam panduan developer pelaporan Protected Audience API, penjelasan, demo live, 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.