ID pelaporan

Mempelajari cara kerja ID pelaporan di lelang Protected Audience

Ringkasan

ID pelaporan adalah ID yang terkait dengan iklan yang tersedia untuk digunakan dalam membuat bid, menilai bid, dan pelaporan. ID pelaporan diberikan oleh pembeli di konfigurasi grup minat, dan ID tersebut akan tersedia di generateBid(), scoreAd(), reportResult(), dan reportWin() dalam berbagai kondisi yang dibahas dalam panduan ini.

ID pelaporan memungkinkan Anda melaporkan ID untuk iklan, dan juga memungkinkan kasus penggunaan seperti promo.

Ketersediaan ID pelaporan

Ada tiga ID pelaporan dari dua jenis:

• ID pelaporan yang tidak dapat dipilih
  • buyerReportingId (string)
  • buyerAndSellerReportingId (string)
• ID pelaporan yang dapat dipilih
  • selectableBuyerAndSellerReportingIds (array string)

Perilaku ID pelaporan berbeda-beda, bergantung pada apakah ID pelaporan yang dapat dipilih digunakan. Jika hanya ID pelaporan yang tidak dapat dipilih yang digunakan, ID tersebut hanya akan tersedia di dalam fungsi pelaporan. Jika ID pelaporan yang dapat dipilih digunakan, bersama dengan ID pelaporan yang tidak dapat dipilih jika diperlukan, semua ID yang ditentukan juga akan tersedia di dalam generateBid() dan scoreAd().

Penting: ID pelaporan diperiksa untuk k-anonimitas sebelum tersedia di dalam fungsi pelaporan (reportResult() dan reportWin()).

ID pelaporan yang tidak dapat dipilih

Ketersediaan ID pelaporan yang dapat dipilih

buyerReportingId dan buyerAndSellerReportingId adalah ID pelaporan yang tidak dapat dipilih yang ditentukan dalam konfigurasi grup minat yang tersedia di fungsi pelaporan pembeli dan penjual. Fungsi pelaporan pembeli dan penjual hanya akan berjalan untuk iklan pemenang, dan fungsi tersebut akan menerima ID pelaporan yang ditentukan untuk iklan pemenang tersebut.

Jika digunakan tanpa ID pelaporan yang dapat dipilih, fungsi pelaporan pembeli akan menerima buyerReportingId atau buyerAndSellerReportingId, bergantung pada perilaku penggantian, dan fungsi pelaporan penjual akan menerima buyerAndSellerReportingId. Jika buyerReportingId atau buyerAndSellerReportingId tidak ditentukan dalam konfigurasi grup minat, fungsi reportWin() akan menerima nama grup minat (interestGroupName) dari bid pemenang.

ID yang tidak dapat dipilih tidak tersedia di dalam generateBid() dan scoreAd() jika tidak digunakan bersama dengan ID pelaporan yang dapat dipilih.

ID pelaporan di grup minat

ID pelaporan ditentukan oleh pembeli untuk setiap iklan dalam grup minat:

navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
    // buyerAndSellerReportingId goes to the buyer and seller reporting functions
    buyerAndSellerReportingId: 'bsrid123',
    // buyerReportingId is defined here as an example, but
    // is not used due to the overwrite rules described later
    buyerReportingId: 'brid123',
  }]
});

Pelaporan penjual

Selama fase pelaporan penjual, nilai buyerAndSellerReportingId akan tersedia untuk reportResult():

function reportResult(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId // 'bsrid123'
  } = browserSignals;

  sendReportTo(`https://seller.example/report?bsrid=${buyerAndSellerReportingId}`);
}

Sebelum tersedia di dalam reportResult(), ID akan diperiksa k-anonimitas-nya dengan pemilik grup minat, URL skrip bidding, URL render, dan ukuran iklan (ukuran iklan dikecualikan dari pemeriksaan ini hingga setidaknya Kuartal 1 2025). Jika tidak k-anonymous, fungsi reportResult() akan tetap berjalan, tetapi nilai ID pelaporan tidak akan tersedia di dalam fungsi.

Pelaporan pembeli

Selama fase pelaporan pembeli lelang, satu ID pelaporan akan tersedia untuk reportWin(). Jika ada lebih dari satu ID pelaporan yang ditentukan dalam grup minat, aturan penggantian akan diterapkan dengan buyerAndSellerReportingId menimpa buyerReportingId:

• Jika buyerAndSellerReportingId dan buyerReportingId ditentukan, buyerAndSellerReportingId akan menimpa buyerReportingId, dan buyerAndSellerReportingId akan tersedia di dalam reportWin().
• Jika hanya buyerReportingId yang ditentukan, buyerReportingId akan tersedia.
• Jika buyerAndSellerReportingId atau buyerReportingId tidak ditentukan, interestGroupName akan tersedia.

function reportWin(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId // 'bsrid123'
  } = browserSignals;

  sendReportTo(`https://seller.example/report?bsrid=${buyerAndSellerReportingId}`);
}

ID pelaporan yang tersedia di dalam reportWin() diperiksa untuk k-anonymity dengan pemilik grup minat, URL skrip bidding, URL render, dan ukuran iklan (ukuran iklan dikecualikan dari pemeriksaan ini hingga setidaknya Kuartal 1 2025). Jika gagal dalam pemeriksaan k-anonimitas, reportWin() akan tetap berjalan, tetapi nilai ID pelaporan tidak akan tersedia di dalam fungsi.

Hanya buyerReportingId yang ditentukan

Jika hanya buyerReportingId yang ditentukan dalam konfigurasi grup minat:

navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
    buyerReportingId: 'brid123',
  }]
});

Kemudian, buyerReportingId tersedia di dalam reportWin():

function reportWin(..., browserSignals, ...) {
  const {
    buyerReportingId, // 'brid123'
  } = browserSignals;
}

Sebelum tersedia untuk reportWin(), buyerReportingId akan diperiksa k-anonimitas-nya dengan pemilik grup minat, URL skrip bidding, URL render, dan ukuran iklan (ukuran iklan dikecualikan dari pemeriksaan ini hingga setidaknya Kuartal 1 2025).

Hanya buyerAndSellerReportingId yang ditentukan

Jika hanya buyerAndSellerReportingId yang ditentukan dalam konfigurasi grup minat:

navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
    buyerAndSellerReportingId: 'bsrid123',
  }]
});

Kemudian, buyerAndSellerReportingId tersedia di dalam reportWin():

function reportWin(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId, // 'bsrid123'
  } = browserSignals;
}

Sebelum tersedia untuk reportWin(), buyerAndSellerReportingId akan diperiksa k-anonimitas-nya dengan pemilik grup minat, URL skrip bidding, URL render, dan ukuran iklan (ukuran iklan dikecualikan dari pemeriksaan ini hingga setidaknya Kuartal 1 2025).

buyerAndSellerReportingId dan buyerReportingId ditentukan

Jika buyerAndSellerReportingId dan buyerReportingId ditentukan dalam konfigurasi grup minat:

navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
    buyerReportingId: 'brid123',
    buyerAndSellerReportingId: 'bsrid123',
  }]
});

Kemudian, hanya buyerAndSellerReportingId yang tersedia di dalam reportWin() karena perilaku penggantian:

function reportWin(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId, // 'bsrid123'
  } = browserSignals;
}

Sebelum tersedia untuk reportWin(), buyerAndSellerReportingId akan diperiksa k-anonimitas-nya dengan pemilik grup minat, URL skrip bidding, URL render, dan ukuran iklan (ukuran iklan dikecualikan dari pemeriksaan ini hingga setidaknya Kuartal 1 2025).

buyerAndSellerReportingId atau buyerReportingId tidak ditentukan

Jika ID pelaporan tidak ditentukan dalam konfigurasi grup minat:

navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
  }]
});

Kemudian, grup minat name tersedia di dalam reportWin():

function reportWin(..., browserSignals, ...) {
  const {
    interestGroupName, // 'example-interest-group'
  } = browserSignals;
}

Sebelum tersedia untuk reportWin(), nama grup minat (interestGroupName) akan diperiksa untuk k-anonimitas dengan pemilik grup minat, URL skrip bidding, URL render, dan ukuran iklan (ukuran iklan dikecualikan dari pemeriksaan ini hingga setidaknya Kuartal 1 2025).

ID pelaporan yang dapat dipilih

Ketersediaan ID pelaporan dengan ID pelaporan yang dapat dipilih

ID pelaporan yang dapat dipilih memungkinkan pembeli memilih ID selama pembuatan bid, dan browser menyediakan nilai yang dipilih untuk scoreAd() dan fungsi pelaporan. Nilai selectableBuyerAndSellerReportingIds, yang merupakan array string, diberikan ke generateBid(), dan pembeli dapat menampilkan satu ID yang dipilih sebagai selectedBuyerAndSellerReportingId.

Fungsi generateBid() dan scoreAd() akan berjalan untuk setiap iklan yang ditentukan dalam konfigurasi grup minat dan menerima ID pelaporan untuk setiap iklan. Fungsi pelaporan pembeli dan penjual hanya akan berjalan untuk iklan pemenang, dan fungsi tersebut akan menerima ID pelaporan yang ditentukan untuk iklan pemenang tersebut.

Jika ID pelaporan yang tidak dapat dipilih digunakan bersama dengan ID pelaporan yang dapat dipilih, perilakunya akan berubah dari alur kerja yang dijelaskan di bagian sebelumnya. Tidak seperti perilaku awal ID pelaporan yang tidak dapat dipilih yang hanya tersedia di dalam fungsi pelaporan, ID pelaporan yang dapat dipilih memungkinkan ID pelaporan yang tidak dapat dipilih juga tersedia di dalam generateBid() dan scoreAd().

Catatan: ID pelaporan yang dapat dipilih akan tersedia di versi Stabil pada M130. Sebelum ID pelaporan yang dapat dipilih mencapai Stabil, ID tersebut dapat diuji dengan meluncurkan Canary M130 dari command line dengan flag --enable-privacy-sandbox-ads-apis --disable-features=EnforcePrivacySandboxAttestations --enable-features=ProtectedAudienceDealsSupport

Grup minat

Kolom ID pelaporan yang dapat dipilih - selectableBuyerAndSellerReportingIds - adalah array string yang ditentukan oleh pembeli di grup minat untuk iklan. ID pelaporan yang tidak dapat dipilih juga dapat ditentukan bersama dengan ID pelaporan yang dapat dipilih:

navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
    buyerReportingId: 'brid123',
    buyerAndSellerReportingId: 'bsrid123',
    selectableBuyerAndSellerReportingIds: ['sbsrid1', 'sbsrid2', 'sbsrid3']
  }]
});

Pembuatan bid pembeli

Jika selectableBuyerAndSellerReportingIds ditentukan dalam konfigurasi grup minat, selectableBuyerAndSellerReportingIds akan tersedia di dalam generateBid() bersama dengan ID pelaporan lainnya yang ditentukan.

function generateBid(interestGroup, ...) {
  const [{
    buyerReportingId, // 'brid123'
    buyerAndSellerReportingId, // 'bsrid123'
    selectableBuyerAndSellerReportingIds // ['sbsrid1', 'sbsrid2', 'sbsrid3']
  }] = interestGroup.ads;

  return {
    bid: 1,
    render: 'https://buyer.example/ad.html',
    selectedBuyerAndSellerReportingId: 'sbsrid2' // Buyer returns the selected ID
  };
}

Pembeli dapat memilih salah satu ID dari array selectableBuyerAndSellerReportingIds di generateBid() dan menampilkan ID yang dipilih sebagai selectedBuyerAndSellerReportingId. Bid akan ditolak jika nilai yang dipilih tidak ada dalam array selectableBuyerAndSellerReportingIds. Jika selectableBuyerAndSellerReportingIds ditentukan dalam konfigurasi grup minat, dan pembeli tidak menampilkan selectedBuyerAndSellerReportingId dari generateBid(), ID pelaporan akan dikembalikan ke perilaku yang dijelaskan untuk ID pelaporan yang tidak dapat dipilih.

Bid dengan nilai yang ditampilkan untuk selectedbuyerAndSellerReportingId hanya dapat memenangkan lelang jika nilai selectedbuyerAndSellerReportingId secara bersama-sama bersifat k-anonim bersama dengan buyerAndSellerReportingId (jika ada), buyerReportingId (jika ada), pemilik grup minat, URL skrip bidding, URL render, dan ukuran iklan (ukuran iklan dikecualikan dari pemeriksaan ini hingga setidaknya Kuartal 1 2025).

Catatan: Jika generateBid() dijalankan ulang karena pemanggilan awal tidak menghasilkan bid apa pun dengan iklan yang lulus pemeriksaan k-anonimitas, selectableBuyerAndSellerReportingIds yang tidak lulus pemeriksaan k-anonimitas tidak akan ada dalam grup minat saat dijalankan ulang.

Penskoran iklan penjual

Untuk penjual, selectedBuyerAndSellerReportingId yang ditampilkan oleh pembeli dari generateBid() akan tersedia di scoreAd(), bersama dengan buyerAndSellerReportingId jika ditentukan dalam konfigurasi grup minat.

function scoreAd(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId, // 'bsrid123'
    selectedBuyerAndSellerReportingId, // 'sbsrid2'
  } = browserSignals;

  // ...
}

Pelaporan penjual

Untuk pelaporan penjual, selectedBuyerAndSellerReportingId yang ditampilkan oleh pembeli dari generateBid() akan tersedia di reportResult(), bersama dengan buyerAndSellerReportingId, jika ditentukan dalam grup minat.

function reportResult(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId, // 'bsrid123'
    selectedBuyerAndSellerReportingId // 'sbsrid2'
  } = browserSignals;
  
  // ...
}

Jika selectableBuyerAndSellerReportingIds ditentukan dalam konfigurasi grup minat, dan selectedBuyerAndSellerReportingId ditampilkan dari generateBid(), selectedBuyerAndSellerReportingId tidak dapat memenangkan lelang kecuali jika selectedBuyerAndSellerReportingId dan buyerAndSellerReportingId (jika ada) bersifat k-anonim dengan pemilik grup minat, URL skrip bidding, URL render, dan ukuran iklan (ukuran iklan dikecualikan dari pemeriksaan ini hingga setidaknya Kuartal 1 2025), dan reportResult() tidak akan dieksekusi untuk bid tersebut. Oleh karena itu, jika reportResult() dipanggil dengan nilai untuk selectedBuyerAndSellerReportingId, artinya ID pelaporan lulus pemeriksaan k-anonymity, dan semua ID pelaporan yang ditentukan akan tersedia di dalam reportResult().

Pelaporan pembeli

Jika selectableBuyerAndSellerReportingIds ditentukan dalam konfigurasi grup minat, dan selectedBuyerAndSellerReportingId ditampilkan dari generateBid(), semua ID pelaporan yang ditentukan dalam konfigurasi grup minat akan tersedia. Perhatikan bahwa, mirip dengan pelaporan penjual, jika ID pelaporan tidak k-anonim, ID tersebut tidak dapat memenangkan lelang dan reportWin() tidak akan berjalan untuk bid tersebut.

function reportWin(..., browserSignals, ...) {
  const {
    buyerReportingId, // 'brid123'
    buyerAndSellerReportingId, // 'bsrid123'
    selectedBuyerAndSellerReportingId // 'sbsrid2'
  } = browserSignals;

  // ...
}

Aturan pengganti

Di sini, kami merangkum aturan penggantian untuk ID pelaporan yang tidak dapat dipilih dan ID pelaporan yang dapat dipilih. Manakah dari selectableBuyerAndSellerReportingIds, buyerAndSellerReportingId, buyerReportingId, dan nama grup minat yang diteruskan ke reportWin() yang ditentukan oleh browser dengan logika berikut:

• Jika selectedBuyerAndSellerReportingId ditampilkan dari bid, selectedBuyerAndSellerReportingId, buyerAndSellerReportingId (jika ditentukan dalam grup minat), dan buyerReportingId (jika ditentukan dalam grup minat) semuanya tersedia untuk pelaporan.
• Jika tidak, jika buyerAndSellerReportingId ditentukan dalam grup minat, hanya buyerAndSellerReportingId yang tersedia untuk pelaporan.
• Jika tidak, jika buyerReportingId ditentukan dalam grup minat, hanya buyerReportingId yang tersedia untuk pelaporan.
• Jika tidak, hanya grup minat name yang tersedia untuk pelaporan.

Tabel berikut menjelaskan perilaku penggantian:

Apakah ID pelaporan ditentukan dalam konfigurasi grup minat?			ID pelaporan tersedia
selectableBuyerAnd SellerReportingIds	buyerAndSeller ReportingId	buyerReportingId	reportWin()	reportResult()
Ya, dan memilih di generateBid()	Opsional	Opsional	1) selectedBuyerAnd SellerReportingIds 2) buyerAndSeller ReportingId (jika ditentukan) 3) buyerReportingId (jika ditentukan)	1) selectedBuyerAnd SellerReportingIds 2) buyerAndSeller ReportingId (jika ditentukan)
Tidak, atau tidak dipilih di generateBid()	Ya	Diabaikan	buyerAndSeller ReportingId	buyerAndSeller ReportingId
Tidak, atau tidak dipilih di generateBid()	Tidak	Ya	buyerReportingId	Tidak ada
Tidak, atau tidak dipilih di generateBid()	Tidak	Tidak	interestGroupName	Tidak ada

Berinteraksi dan memberikan masukan

• Untuk mempelajari ID pelaporan lebih lanjut, lihat bagian ID Pelaporan dalam penjelasan Protected Audience.
• GitHub: Ajukan pertanyaan dan ikuti diskusi dalam masalah di repositori API.
• W3C: Membahas kasus penggunaan industri dalam panggilan WICG.
• Pengumuman: Bergabung atau melihat daftar email.
• Dukungan developer Privacy Sandbox: Ajukan pertanyaan dan bergabunglah dalam diskusi di repositori Dukungan Developer Privacy Sandbox.
• Chromium: Laporkan bug Chromium untuk mengajukan pertanyaan tentang penerapan yang tersedia untuk diuji di Chrome.