ID report

Scopri come funzionano gli ID report in un'asta Protected Audience

Panoramica

Gli ID report sono identificatori associati a un annuncio che possono essere utilizzati per generare un'offerta, determinare il punteggio di un'offerta e generare report. Gli ID report vengono forniti dall'acquirente nella configurazione dei gruppi di interesse e diventano disponibili in generateBid(), scoreAd(), reportResult() e reportWin() in varie condizioni descritte in questa guida.

Gli ID report ti consentono di segnalare un identificatore per un annuncio e di attivare casi d'uso come i deal.

Disponibilità degli ID report

Esistono tre ID report di due tipi:

• ID report non selezionabili
  • buyerReportingId (una stringa)
  • buyerAndSellerReportingId (una stringa)
• ID report selezionabili
  • selectableBuyerAndSellerReportingIds (un array di stringhe)

Gli ID report si comportano in modo diverso a seconda che vengano utilizzati o meno gli ID report selezionabili. Quando vengono utilizzati solo ID report non selezionabili, questi ID diventano disponibili solo all'interno delle funzioni di generazione dei report. Quando vengono utilizzati gli ID report selezionabili, insieme agli ID report non selezionabili (se necessario), tutti gli ID definiti diventano disponibili anche all'interno di generateBid() e scoreAd().

Importante: viene verificata l'anonimità k degli ID report prima che diventino disponibili all'interno delle funzioni di generazione di report (reportResult() e reportWin()).

ID report non selezionabili

Disponibilità di ID report selezionabili

buyerReportingId e buyerAndSellerReportingId sono ID report non selezionabili definiti nella configurazione dei gruppi di interesse che diventano disponibili nelle funzioni di generazione di report per acquirenti e venditori. Le funzioni di generazione di report per acquirenti e venditori vengono eseguite solo per l'annuncio vincente e riceveranno gli ID report definiti per l'annuncio vincente.

Se utilizzata senza ID report selezionabili, la funzione di generazione di report sugli acquirenti riceve buyerReportingId o buyerAndSellerReportingId a seconda del comportamento di sovrascrittura, mentre la funzione di generazione di report sul venditore riceve buyerAndSellerReportingId. Se né buyerReportingId né buyerAndSellerReportingId sono definiti nella configurazione dei gruppi di interesse, la funzione reportWin() riceve il nome del gruppo di interesse (interestGroupName) dell'offerta vincente.

Gli ID non selezionabili non sono disponibili all'interno di generateBid() e scoreAd() se non vengono utilizzati insieme agli ID report selezionabili.

ID report nei gruppi di interesse

Gli ID report sono definiti dall'acquirente per ogni annuncio in un gruppo di interesse:

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',
  }]
});

Report sui venditori

Durante la fase di generazione dei report sul venditore, il valore di buyerAndSellerReportingId diventa disponibile per reportResult():

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

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

Prima che l'ID diventi disponibile all'interno di reportResult(), viene verificata la presenza di k-anonymity con il proprietario del gruppo di interesse, l'URL dello script di offerta, l'URL di rendering e le dimensioni dell'annuncio (le dimensioni dell'annuncio sono escluse da questo controllo almeno fino al primo trimestre del 2025). Se non è k-anonymous, la funzione reportResult() continuerà a essere eseguita, ma il valore dell'ID report non sarà disponibile all'interno della funzione.

Report sugli acquirenti

Durante la fase di generazione di report per l'acquirente dell'asta, un ID report diventa disponibile per reportWin(). Se nel gruppo di interesse viene definito più di un ID report, viene applicata una regola di sovrascrittura in cui buyerAndSellerReportingId sovrascrive buyerReportingId:

• Se buyerAndSellerReportingId e buyerReportingId sono definiti entrambi, buyerAndSellerReportingId sovrascriverà buyerReportingId e buyerAndSellerReportingId sarà disponibile all'interno di reportWin().
• Se è definito solo buyerReportingId, sarà disponibile buyerReportingId.
• Se non viene definito né buyerAndSellerReportingId né buyerReportingId, interestGroupName sarà disponibile.

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

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

L'ID report che diventa disponibile all'interno di reportWin() viene controllato per verificare la presenza di k-anonymity con il proprietario del gruppo di interesse, l'URL dello script di offerta, l'URL di rendering e le dimensioni dell'annuncio (le dimensioni dell'annuncio sono escluse da questo controllo almeno fino al primo trimestre del 2025). Se non supera il controllo di k-anonymity, reportWin() continuerà a essere eseguito, ma il valore dell'ID report non sarà disponibile all'interno della funzione.

È definito solo buyerReportingId

Se nella configurazione del gruppo di interesse è definito solo buyerReportingId:

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

buyerReportingId sarà disponibile all'interno di reportWin():

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

Prima di diventare disponibile per reportWin(), buyerReportingId viene controllata per verificare la presenza di k-anonymity con il proprietario del gruppo di interesse, l'URL dello script di offerta, l'URL di rendering e le dimensioni dell'annuncio (le dimensioni dell'annuncio sono escluse da questo controllo almeno fino al primo trimestre del 2025).

È definito solo buyerAndSellerReportingId

Se nella configurazione del gruppo di interesse è definito solo buyerAndSellerReportingId:

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

buyerAndSellerReportingId sarà disponibile all'interno di reportWin():

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

Prima di essere reso disponibile per reportWin(), buyerAndSellerReportingId viene verificato per l'anonimizzazione k con il proprietario del gruppo di interesse, l'URL dello script di offerta, l'URL di rendering e le dimensioni dell'annuncio (queste ultime sono escluse da questo controllo almeno fino al primo trimestre del 2025).

Sono definiti sia buyerAndSellerReportingId che buyerReportingId

Se buyerAndSellerReportingId e buyerReportingId sono definiti nella configurazione del gruppo di interesse:

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

Poiché buyerAndSellerReportingId è disponibile solo all'interno di reportWin() a causa del comportamento di sovrascrittura:

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

Prima di essere reso disponibile per reportWin(), buyerAndSellerReportingId viene verificato per l'anonimizzazione k con il proprietario del gruppo di interesse, l'URL dello script di offerta, l'URL di rendering e le dimensioni dell'annuncio (queste ultime sono escluse da questo controllo almeno fino al primo trimestre del 2025).

Non sono definiti né buyerAndSellerReportingId né buyerReportingId

Se nessuno degli ID report è definito nella configurazione dei gruppi di interesse:

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

Il gruppo basato sugli interessi name sarà disponibile all'interno di reportWin():

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

Prima di diventare disponibile per reportWin(), il nome del gruppo di interesse (interestGroupName) viene controllato per verificare la presenza di k-anonymity con il proprietario del gruppo di interesse, l'URL dello script di offerta, l'URL di rendering e le dimensioni dell'annuncio (le dimensioni dell'annuncio sono escluse da questo controllo almeno fino al primo trimestre del 2025).

ID report selezionabili

Disponibilità degli ID report con ID report selezionabile

Gli ID report selezionabili consentono a un acquirente di selezionare un ID durante la generazione dell'offerta e il browser rende il valore selezionato disponibile a scoreAd() e alle funzioni di generazione dei report. Il valore selectableBuyerAndSellerReportingIds, che è un array di stringhe, viene fornito a generateBid() e l'acquirente può restituire un ID selezionato come selectedBuyerAndSellerReportingId.

Le funzioni generateBid() e scoreAd() vengono eseguite per ogni annuncio definito nella configurazione dei gruppi di interesse e ricevono gli ID report per ogni annuncio. Le funzioni di generazione di report per acquirenti e venditori vengono eseguite solo per l'annuncio vincente e riceveranno gli ID report definiti per l'annuncio vincente.

Quando gli ID report non selezionabili vengono utilizzati insieme a quelli selezionabili, il loro comportamento cambia rispetto al flusso di lavoro descritto nella sezione precedente. A differenza del comportamento iniziale degli ID report non selezionabili che sono disponibili solo all'interno delle funzioni di reporting, gli ID report selezionabili consentono di rendere disponibili gli ID report non selezionabili anche all'interno di generateBid() e scoreAd().

Nota: gli ID report selezionabili sono disponibili nella versione stabile nella versione M130. Prima che gli ID report selezionabili raggiungano la versione stabile, possono essere testati avviando Canary M130 dalla riga di comando con i flag --enable-privacy-sandbox-ads-apis --disable-features=EnforcePrivacySandboxAttestations --enable-features=ProtectedAudienceDealsSupport

Gruppo basato sugli interessi

Il campo degli ID report selezionabili (selectableBuyerAndSellerReportingIds) è un array di stringhe definite dall'acquirente nel gruppo di interesse per un annuncio. Gli ID report non selezionabili possono essere definiti anche insieme agli ID report selezionabili:

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']
  }]
});

Generazione dell'offerta dell'acquirente

Se selectableBuyerAndSellerReportingIds è stato definito nella configurazione dei gruppi di interesse, diventa disponibile all'interno di generateBid() insieme agli altri ID report definiti.

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

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

L'acquirente può scegliere uno degli ID dall'array selectableBuyerAndSellerReportingIds in generateBid() e restituire l'ID selezionato come selectedBuyerAndSellerReportingId. L'offerta viene rifiutata se il valore selezionato non è presente nell'array selectableBuyerAndSellerReportingIds. Se selectableBuyerAndSellerReportingIds è definito nella configurazione dei gruppi di interesse e l'acquirente non restituisce selectedBuyerAndSellerReportingId da generateBid(), gli ID report torneranno al comportamento descritto per gli ID report non selezionabili.

Un'offerta con un valore restituito per selectedbuyerAndSellerReportingId può vincere l'asta solo se il valore di selectedbuyerAndSellerReportingId è k-anonimo insieme a buyerAndSellerReportingId (se presente), buyerReportingId (se presente), il proprietario del gruppo di interesse, l'URL dello script di offerta, l'URL di rendering e le dimensioni dell'annuncio (le dimensioni dell'annuncio sono escluse da questo controllo almeno fino al primo trimestre del 2025).

Nota: nei casi in cui generateBid() viene eseguito di nuovo perché la chiamata iniziale non ha prodotto offerte con annunci che hanno superato i controlli di k-anonymity, gli attributi selectableBuyerAndSellerReportingId che non superano il controllo k-anonymity non saranno presenti nel gruppo di interesse quando verrà eseguita di nuovo.

Punteggio degli annunci del venditore

Per il venditore, il valore selectedBuyerAndSellerReportingId restituito dall'acquirente da generateBid() diventa disponibile in scoreAd(), insieme a buyerAndSellerReportingId se è stato definito nella configurazione dei gruppi di interesse.

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

  // ...
}

Report sui venditori

Per i report sui venditori, il valore selectedBuyerAndSellerReportingId restituito dall'acquirente tramite generateBid() diventa disponibile in reportResult(), insieme a buyerAndSellerReportingId, se è stato definito nel gruppo basato sugli interessi.

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

Se selectableBuyerAndSellerReportingIds è stato definito nella configurazione dei gruppi di interesse e selectedBuyerAndSellerReportingId è stato restituito da generateBid(), non può vincere l'asta a meno che selectedBuyerAndSellerReportingId e buyerAndSellerReportingId (se presenti) non siano in forma anonima con il proprietario del gruppo di interesse, l'URL dello script di offerta, l'URL di rendering e le dimensioni dell'annuncio (le dimensioni dell'annuncio sono escluse da questo controllo almeno fino al primo trimestre 2025) e non verranno eseguiti reportResult() per questa offerta. Pertanto, se reportResult() viene chiamato con un valore per selectedBuyerAndSellerReportingId, significa che gli ID report hanno superato il controllo di k-anonymity e tutti gli ID report definiti saranno disponibili all'interno di reportResult().

Report acquirenti

Se selectableBuyerAndSellerReportingIds è stato definito nella configurazione del gruppo di interesse e selectedBuyerAndSellerReportingId è stato restituito da generateBid(), tutti gli ID report definiti nella configurazione del gruppo di interesse diventano disponibili. Tieni presente che, come accade per i report sui venditori, se gli ID report non sono k-anonymous, non possono vincere l'asta e reportWin() non sarà pubblicato per quell'offerta.

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

  // ...
}

Sovrascrivi regole

Qui riepiloghiamo le regole di sovrascrittura sia per gli ID report non selezionabili che per gli ID report selezionabili. Quale tra selectableBuyerAndSellerReportingIds, buyerAndSellerReportingId, buyerReportingId e il nome del gruppo di interesse viene passato a reportWin() viene determinato dal browser con la seguente logica:

• Se selectedBuyerAndSellerReportingId viene restituito da un'offerta, selectedBuyerAndSellerReportingId, buyerAndSellerReportingId (se definito nel gruppo basato sugli interessi) e buyerReportingId (se definito nel gruppo basato sugli interessi) sono tutti disponibili per i report.
• In caso contrario, se nel gruppo basato sugli interessi viene definito il valore buyerAndSellerReportingId, per i report è disponibile solo buyerAndSellerReportingId.
• In caso contrario, se nel gruppo basato sugli interessi viene definito il valore buyerReportingId, per i report è disponibile solo buyerReportingId.
• In caso contrario, solo il gruppo di interesse name è disponibile per i report.

Nella tabella seguente viene descritto il comportamento di sovrascrittura:

Gli ID report sono definiti nella configurazione dei gruppi di interesse?			ID report disponibili
selectableBuyerAnd SellerReportingIds	buyerAndSeller ReportingId	buyerReportingId	reportWin()	reportResult()
Sì e selezionato in generateBid()	Facoltativo	Facoltativo	1) selectableBuyerAnd SellerReportingIds 2) buyerAndSeller ReportingId (se definita) 3) buyerReportingId (se definita)	1) selectableBuyerAnd SellerReportingIds 2) buyerAndSeller ReportingId (se definita)
No o non selezionato in generateBid()	Sì	Ignorato	buyerAndSeller ReportingId	buyerAndSeller ReportingId
No o non selezionato in generateBid()	No	Sì	buyerReportingId	Nessuno
No o non selezionato in generateBid()	No	No	interestGroupName	Nessuno

Interagisci e condividi il feedback

• Per scoprire di più sugli ID report, consulta la sezione ID report della spiegazione di Protected Audience.
• GitHub: fai domande e segui la discussione sui problemi nel repository API.
• W3C: parla dei casi d'uso del settore nella chiamata a W3C.
• Annunci: iscriviti o visualizza la mailing list.
• Assistenza per gli sviluppatori di Privacy Sandbox: fai domande e partecipa alle discussioni nel repository dell'assistenza per gli sviluppatori di Privacy Sandbox.
• Chromium: segnala un bug di Chromium per porre domande sull'implementazione disponibile da testare in Chrome.