ID report

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

Panoramica

Gli ID report sono identificatori associati a un annuncio che sono disponibili per l'utilizzo nella generazione di un'offerta, nell'assegnazione di un punteggio a un'offerta e nella generazione di report. Gli ID report vengono forniti dall'acquirente nella configurazione del gruppo 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 le offerte.

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 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().

ID report non 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 quell'annuncio.

Se utilizzata senza ID report selezionabili, la funzione di generazione di report dell'acquirente riceve buyerReportingId o buyerAndSellerReportingId a seconda del comportamento di sovrascrittura, mentre la funzione di generazione di report del 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 insieme agli ID report selezionabili.

ID per i 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 del venditore

Durante la fase di segnalazione ai 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 verificata la k-anonimità 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-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 segnalazione dell'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 sono definiti sia buyerAndSellerReportingId che buyerReportingId, buyerAndSellerReportingId sovrascriverà buyerReportingId e sarà disponibile all'interno di reportWin().buyerAndSellerReportingId
• 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 controllato per verificare la k-anonimity 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 il controllo k-anonimity non viene superato, 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 all'interno di reportWin():

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

Prima di essere disponibile per reportWin(), buyerReportingId viene verificato per la k-anonimità 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 è disponibile all'interno di reportWin():

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

Prima di essere disponibile per reportWin(), buyerAndSellerReportingId viene verificato per la k-anonimità 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).

Sono definiti sia buyerAndSellerReportingId che buyerReportingId

Se sia buyerAndSellerReportingId che 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',
  }]
});

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

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

Prima di essere disponibile per reportWin(), buyerAndSellerReportingId viene verificato per la k-anonimità 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).

Né buyerAndSellerReportingId né buyerReportingId sono definiti

Se nessuno dei due 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 è quindi 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 verificato per la k-anonimità 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

Gli ID report selezionabili consentono a un acquirente di selezionare un ID durante la generazione dell'offerta e il browser rende disponibile il valore selezionato per le funzioni di scoreAd() e di reporting. 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 quell'annuncio.

Quando gli ID report non selezionabili vengono utilizzati insieme a ID report selezionabili, il loro comportamento cambia rispetto al flusso di lavoro descritto nella sezione precedente. A differenza del comportamento iniziale degli ID report non selezionabili 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().

Gruppo basato sugli interessi

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

Se selectableBuyerAndSellerReportingIds è stato definito nella configurazione del gruppo di interesse, diventa disponibile in generateBid() insieme ad 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 è presente 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 congiuntamente a buyerAndSellerReportingId (se presente), buyerReportingId (se presente), al proprietario del gruppo di interesse, all'URL dello script di offerta, all'URL di rendering e alle dimensioni dell'annuncio (le dimensioni dell'annuncio sono escluse da questo controllo almeno fino al primo trimestre del 2025).

Punteggio annuncio del venditore

Per il venditore, il 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 del venditore

Per i report dei venditori, il 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 presente) 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 (le dimensioni dell'annuncio sono escluse da questo controllo almeno fino al primo trimestre del 2025) e reportResult() non venga eseguito per l'offerta. Pertanto, se reportResult() viene chiamato con un valore per selectedBuyerAndSellerReportingId, significa che gli ID report hanno superato il controllo k-anonymity 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(), diventano disponibili tutti gli ID report definiti nella configurazione del gruppo di interesse. Tieni presente che, analogamente ai report del venditore, se gli ID report non sono k-anonimi, non possono vincere l'asta e reportWin() non verrà eseguito per l'offerta.

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

  // ...
}

Regole di sovrascrittura

Di seguito riepiloghiamo le regole di override per gli ID report non selezionabili e selezionabili. Quale tra selectableBuyerAndSellerReportingIds, buyerAndSellerReportingId, buyerReportingId e il nome del gruppo di interesse viene trasmesso 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 la generazione di report.
• In caso contrario, se buyerAndSellerReportingId è definito nel gruppo di interesse, solo buyerAndSellerReportingId è disponibile per la generazione di report.
• In caso contrario, se buyerReportingId è definito nel gruppo di interesse, solo buyerReportingId è disponibile per la generazione di report.
• In caso contrario, per la generazione di report è disponibile solo il gruppo di interesse name.

La tabella seguente descrive il comportamento di sovrascrittura:

Partecipare 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 nelle issue del repository dell'API.
• W3C: discuti dei casi d'uso del settore nella chiamata WICG.
• Annunci: iscriviti o visualizza la mailing list.
• Privacy Sandbox Developer Support: fai domande e partecipa alle discussioni nel repository Privacy Sandbox Developer Support.
• Chromium: segnala un bug di Chromium per porre domande sull'implementazione disponibile per i test in Chrome.