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, assegnare un punteggio a un'offerta e generare report. Gli ID report vengono forniti dall'acquirente nella configurazione del gruppo di interesse e diventano disponibili in generateBid(), scoreAd(), reportResult() e reportWin() in base a varie condizioni discusse in questa guida.

Gli ID report ti consentono di segnalare un identificatore per un annuncio e attivano anche 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 ID report selezionabili. Quando vengono utilizzati solo ID report non selezionabili, questi ID diventano disponibili solo all'interno delle funzioni di generazione di report. Quando vengono utilizzati ID report selezionabili, insieme a ID report non selezionabili, se necessario, tutti gli ID definiti diventano disponibili anche in 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à degli ID report selezionabili

buyerReportingId e buyerAndSellerReportingId sono ID report non selezionabili definiti nella configurazione del gruppo 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 verranno 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 per l'acquirente riceve buyerReportingId o buyerAndSellerReportingId a seconda del comportamento di sovrascrittura, mentre la funzione di generazione di report per il venditore riceve buyerAndSellerReportingId. Se né buyerReportingId né buyerAndSellerReportingId sono definiti nella configurazione del gruppo di interesse, la funzione reportWin() riceve il nome del gruppo di interesse (interestGroupName) dell'offerta vincente.

Gli ID non selezionabili non sono disponibili in generateBid() e scoreAd() se non vengono utilizzati in combinazione con ID report selezionabili.

ID report nei gruppi di interesse

Gli ID report vengono 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 per i venditori

Durante la fase di generazione dei report per i venditori, il valore 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 in reportResult(), viene controllato per verificare 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). Se non è k-anonimo, la funzione reportResult() verrà comunque 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 è definito più di un ID report, viene applicata una regola di sovrascrittura in cui buyerAndSellerReportingId sovrascrive buyerReportingId:

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

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

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

L'ID report che diventa disponibile in reportWin() 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). Se non supera il controllo di anonimità k, reportWin() verrà comunque 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 è disponibile in reportWin():

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

Prima di essere reso disponibile per reportWin(), buyerReportingId 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).

È 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 è disponibile in 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).

Sia buyerAndSellerReportingId che buyerReportingId sono definiti

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

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

In questo caso, solo buyerAndSellerReportingId è disponibile 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).

Né buyerAndSellerReportingId né buyerReportingId sono definiti

Se nessuno degli ID report è definito nella configurazione del gruppo di interesse:

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

Il gruppo di interesse name è disponibile all'interno di reportWin():

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

Prima di essere reso disponibile per reportWin(), il nome del gruppo di interesse (interestGroupName) 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).

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 delle offerte e il browser rende disponibile il valore selezionato per scoreAd() e le funzioni di generazione di 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() verranno eseguite per ogni annuncio definito nella configurazione del gruppo di interesse e riceveranno gli ID report per ogni annuncio. Le funzioni di generazione di report per acquirenti e venditori verranno 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, in cui gli ID report non selezionabili erano disponibili solo all'interno delle funzioni di generazione di report, gli ID report selezionabili consentono di rendere disponibili anche gli ID report non selezionabili in generateBid() e scoreAd().

Nota: gli ID report selezionabili saranno disponibili nella versione stabile in 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 di interesse

Il campo ID report selezionabile - selectableBuyerAndSellerReportingIds - è un array di stringhe definito dall'acquirente nel gruppo di interesse per un annuncio. Oltre agli ID report selezionabili, è possibile definire anche ID report non 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 di offerte dell'acquirente

Se selectableBuyerAndSellerReportingIds è stato definito nella configurazione del gruppo di interesse, diventa disponibile in generateBid() insieme agli altri ID report definiti.

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
  };
}

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 è nell'array selectableBuyerAndSellerReportingIds. Se selectableBuyerAndSellerReportingIds è definito nella configurazione del gruppo 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 (queste ultime sono escluse da questo controllo almeno fino al primo trimestre del 2025).

Nota: nei casi in cui generateBid() viene eseguito di nuovo perché l'invocazione iniziale non ha generato offerte con annunci che hanno superato i controlli di anonimità k, gli identificatori selectableBuyerAndSellerReportingIds che non superano il controllo di anonimità k non saranno presenti nel gruppo di interesse al momento della nuova esecuzione.

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 del gruppo di interesse.

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

  // ...
}

Report per i venditori

Per i report dei venditori, il valore selectedBuyerAndSellerReportingId restituito dall'acquirente da generateBid() diventa disponibile in reportResult(), insieme a buyerAndSellerReportingId, se è stato definito nel gruppo di interesse.

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

Se selectableBuyerAndSellerReportingIds è stato definito nella configurazione del gruppo di interesse e selectedBuyerAndSellerReportingId è stato restituito da generateBid(), non può vincere l'asta a meno che selectedBuyerAndSellerReportingId e buyerAndSellerReportingId (se presenti) non siano k-anonimi 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) e reportResult() non verrà eseguito per l'offerta. Pertanto, se reportResult() viene chiamato con un valore per selectedBuyerAndSellerReportingId, significa che gli ID report hanno superato il controllo di anonimità k e tutti gli ID report definiti saranno disponibili all'interno di reportResult().

Report sugli 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 per i report dei venditori, se gli ID report non sono anonimi k, non possono vincere l'asta e reportWin() non verrà eseguito per quell'offerta.

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

  // ...
}

Regole di override

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

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

La seguente tabella descrive il comportamento di sovrascrittura:

Gli ID report sono definiti nella configurazione del gruppo di interesse?			ID report disponibili
selectableBuyerAnd SellerReportingIds	buyerAndSeller ReportingId	buyerReportingId	reportWin()	reportResult()
Sì e ho selezionato in generateBid()	Facoltativo	Facoltativo	1) selectedBuyerAnd SellerReportingIds 2) buyerAndSeller ReportingId (se definito) 3) buyerReportingId (se definito)	1) selectedBuyerAnd SellerReportingIds 2) buyerAndSeller ReportingId (se definito)
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

Coinvolgere e condividere feedback

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