Eseguire l'integrazione con B&A come acquirente

I servizi di offerte e aste (B&A) sono un insieme di servizi per acquirenti e venditori di annunci che vengono eseguiti in un ambiente di esecuzione sicuro (TEE) per facilitare un'asta Protected Audience (PA). Questa Guida per gli sviluppatori spiega come un acquirente può eseguire l'integrazione con un'asta di pubblicità programmata di tipo B2B per Chrome.

Panoramica

Per partecipare a un'asta Protected Audience con i servizi B&A, l'acquirente aggiorna il gruppo di interesse (IG) per ottimizzare il payload in modo da ridurre la latenza dell'asta.

Le seguenti attività di ottimizzazione del payload sono richieste dall'acquirente:

Gruppo di interesse per B&A

Di seguito è riportato un esempio di configurazione del gruppo di interesse per un'asta B&A PA con ottimizzazione del payload applicata:

navigator.joinAdInterestGroup({
  name: 'example-ig',
  owner: 'https://dsp.example',

  // An ID is mapped to each render URL
  ads: [
    {
      renderURL: 'https://dsp.example/ad.html',
      adRenderId: '12345678' // 12 characters max,
      buyerReportingId: 'brid123', // Optional
      buyerAndSellerReportingId: 'bsrid123', // Optional
      selectableBuyerAndSellerReportingId: ['sbsrid123', 'sbsrid456'], // Optional
    },
  ],
  adComponents: [
    {
      renderURL: 'https://dsp.example/ad-component.html',
      adRenderId: 'abcdefgh'
    },
  ],

  // Flags are set to omit data in the B&A auction payload
  auctionServerRequestFlags: ['omit-ads', 'omit-user-bidding-signals'],

  // Data not included in the B&A auction payload can be fetched as trusted signals
  // The following is an example of how the keys could look, but the actual
  // implementation is up to the ad tech
  trustedBiddingSignalsKeys: [
    'exampleUserBiddingSignalsKey',
    'exampleAdRenderIdKey',
    'exampleAdMetadataKey',
    'exampleAdReportingIdKey',
  ],

  // Optionally, interest groups can be prioritized
  priority: 0.0,
});

Le differenze tra le configurazioni di gruppi di interesse B&A e on-device sono:

Campi IG B&A IG on-device Incluso nel payload dell'asta B&A
auctionServerRequestFlags Usato Non utilizzate No
userBiddingSignals Sconsigliato Usato No, se il flag omit-user-bidding-signals è impostato
adRenderId in ads e adComponents Usato Non utilizzate Se il flag omit-ads è impostato, adRenderId in ads è disponibile solo in browserSignals.prevWins del payload. adRenderId definito in adComponents non è incluso nel payload.

Se il flag omit-ads non è impostato, è disponibile in browserSignals.prevWins, interestGroup.adRenderIds e interestGroup.adComponentRenderIds.
renderURL in ads e adComponents Usato Usato No
metadata in ads e adComponents Non utilizzate Usato No
ID report in ads Usato Usato No
  • Il campo auctionServerRequestFlags consente di impostare flag che indicano al browser di omettere alcuni dati nel payload dell'asta B&A.
  • Il valore userBiddingSignals può essere definito nel gruppo di interesse, ma è consigliabile ometterlo utilizzando il flag omit-user-bidding-signals. Gli indicatori omessi possono essere forniti utilizzando il servizio K/V.
  • Il campo adRenderId viene impostato insieme al campo renderURL associato, ma solo adRenderId farà parte del payload dell'asta B&A. L'URL di rendering restituito da generateBid() in un secondo momento durante l'asta deve corrispondere all'URL di rendering definito nell'IG.
  • Gli ID report sono definiti nell'IG di B&A, ma non sono inclusi nel payload dell'asta B&A. L'ID report restituito da generateBid() in un secondo momento durante l'asta deve corrispondere all'URL di rendering definito nell'IG.
  • Gli ID ad.metadata e report non sono inclusi nel payload dell'asta B&A, ma diventano disponibili tramite l'utilizzo del servizio di chiavi/valori attendibili.

Tieni presente che i renderURL e gli ID report in ads sono ancora definiti nella configurazione del gruppo di interesse, anche se non vengono inclusi nel payload della richiesta di asta, perché il browser controlla che l'URL di rendering e gli ID report restituiti dalla funzione generateBid() del servizio di offerta corrispondano ai valori definiti nel gruppo di interesse.

joinAdInterestGroup() attività

Per la chiamata joinAdInterestGroup() devono essere eseguite le seguenti attività.

Impostare i flag di richiesta del server

Il campo auctionServerRequestFlags della configurazione joinAdInterestGroup() accetta i seguenti flag:

Bandiera Descrizione
omit-user-bidding-signals Il flag omit-user-bidding-signals omette l'oggetto userBiddingSignals nel payload dell'asta.

Se l'indicatore non è impostato, il valore userBiddingSignals definito nel gruppo di interesse diventerà disponibile in generateBid() del servizio di offerta.
omit-ads Il flag omit-ads indica al browser di omettere gli oggetti ads e adComponents nel payload dell'asta.

adRenderId sarà disponibile nella proprietà prevWins di browserSignals.

Se il flag non è impostato, i campi adRenderIds e adComponentRenderIds nell'argomento interestGroup di generateBid() conterranno gli ID di rendering dell'annuncio corrispondenti.

Consigliamo vivamente agli acquirenti di optare per il flag omit-ads. In futuro, la trasmissione degli ID di rendering e degli ID di rendering dei componenti dell'annuncio dal client potrebbe essere ritirata per un'ulteriore ottimizzazione del payload.

I dati omessi vengono gestiti rendendo disponibili informazioni pertinenti in trustedBiddingSignals. I flag possono essere utilizzati singolarmente e non devono essere utilizzati insieme.

Esempio di utilizzo:

navigator.joinAdInterestGroup({
  auctionServerRequestFlags: ['omit-user-bidding-signals', 'omit-ads'],
});

Impostare gli ID di rendering degli annunci

Per ridurre le dimensioni del payload dell'asta B&A, gli oggetti ads e adComponents del gruppo di interesse vengono omessi e, a loro volta, questi oggetti non sono disponibili all'interno della funzione generateBid() in esecuzione nel servizio di offerta.

Per gestire le informazioni mancanti sugli annunci, l'acquirente gestisce un identificatore (adRenderId e adComponentRenderId) associato a ogni annuncio nella configurazione del gruppo di interesse. L'identificatore deve essere una DOMString di massimo 12 byte. Se l'identificatore è codificato in Base64, la sua lunghezza deve essere inferiore o uguale a 12 byte.

Un esempio di gruppo di interesse con ID di visualizzazione dell'annuncio:

navigator.joinAdInterestGroup({
  ads: [
    {
      renderURL: 'https://dsp.example/ad.html',
      adRenderId: '12345678' // 12 characters max
    },
  ],
  adComponents: [
    {
      renderURL: 'https://dsp.example/ad-component.html',
      adComponentRenderId: 'abcdefgh'
    },
  ],
});

I adRenderId associati agli annunci diventano disponibili in prevWins.browserSignals a partire da generateBid().

Sebbene renderURL non sia incluso nel payload della richiesta, l'URL di rendering restituito da generateBid() deve corrispondere all'URL di rendering definito nella configurazione del gruppo di interesse. Le tecnologie pubblicitarie possono inviare i metadati degli annunci e altre informazioni in trustedBiddingSignals, in modo che l'URL di rendering dell'annuncio e l'URL di rendering del componente dell'annuncio possano essere generati per l'offerta durante l'esecuzione di generateBid().

Impostare le priorità dei gruppi di interesse

Chrome consente agli acquirenti di dare la priorità ai gruppi di interesse. Se viene raggiunto il limite di dimensione del payload per acquirente impostato dal venditore, i valori di priorità del gruppo di interesse vengono utilizzati per eliminare i gruppi di interesse con priorità inferiore per un singolo acquirente quando viene generato il payload dell'asta B&A per il venditore. Per la selezione dei gruppi di interesse tra acquirenti diversi, il browser decide in base alle dimensioni del payload serializzato. Per impostazione predefinita, a ogni acquirente viene assegnata una dimensione uguale. Tieni presente che l'assegnazione effettiva della priorità avviene sui server B&A e non quando viene generato il payload della richiesta.

La priorità viene calcolata al momento dell'asta utilizzando i vettori di priorità dell'acquirente (priorityVector) e gli indicatori di priorità del venditore (prioritySignals). L'acquirente ha la possibilità di sostituire gli indicatori di priorità del venditore.

Proprietà Descrizione
Vettore di priorità L'acquirente fornisce i vettori come valore della chiave priorityVector del servizio K/V
Indicatori di priorità Il venditore fornisce gli indicatori impostando priority_signals della configurazione dell'asta
Sostituzioni degli indicatori di priorità L'acquirente fornisce l'override nel campo priority_signals_overrides di PerBuyerConfig nella configurazione dell'asta.

Durante l'asta, il browser calcola il prodotto scalare sparso delle chiavi corrispondenti in priorityVector e prioritySignals per la priorità. Nel seguente diagramma, la priorità viene calcolata in base a (4 * 2) + (3 * -1), che viene ridotta a 8 + -3, quindi la priorità di questo gruppo di interesse al momento dell'asta è 5.

Ogni chiave negli oggetti vettore di priorità e indicatori di priorità viene moltiplicata per l'altra, quindi i risultati vengono sommati per calcolare la priorità
Figura 1: calcolo della priorità utilizzando i vettori dell'acquirente e gli indicatori del venditore

Sono disponibili anche altri indicatori da utilizzare per definire le priorità in B&A:

Segnale Descrizione
deviceSignals.one Il valore è sempre 1 ed è utile per aggiungere una costante al prodotto scalare.
deviceSignals.ageInMinutes Il valore descrive l'età del gruppo di interesse (il tempo trascorso dall'ultima iscrizione al gruppo di interesse) in minuti come numero intero compreso tra 0 e 43.200.
deviceSignals.ageInMinutesMax60 Il valore descrive lo stesso indicatore ageInMinutes, ma ha un limite massimo di 60. Se il gruppo è stato creato più di un'ora fa, viene restituito il valore 60.
deviceSignals.ageInHoursMax24 Il valore descrive l'età del gruppo di interesse in ore, con un limite massimo di 24 ore. Se il gruppo è stato creato da più di un giorno, viene restituito il valore 24.
deviceSignals.ageInDaysMax30 Il valore descrive l'età del gruppo di interesse in giorni, con un limite massimo di 30 giorni. Se il gruppo è stato creato da più di 30 giorni, viene restituito il valore 30.

Per saperne di più, consulta la documentazione su GitHub.

Configurare gli indicatori di offerta attendibili

Poiché alcuni dati verranno omessi dal payload dell'asta B&A, puoi utilizzare il servizio Key/Value per fornire i dati omessi come indicatori di offerta attendibili alla funzione generateBid().

I seguenti dati omessi possono essere forniti dal servizio K/V:

  • userBiddingSignals se utilizzato dall'acquirente
  • metadata associato a ogni annuncio
  • adRenderId associato a ogni annuncio
  • ID report
I dati omessi dal gruppo di interesse possono essere inviati al server di raccolta dell'acquirente. Il server di raccolta invia i dati al servizio chiave/valore e in un secondo momento il browser li carica dal servizio chiave/valore.
Figura 2: esempio di configurazione degli indicatori attendibili

Un approccio che puoi adottare è includere un identificatore univoco nelle chiavi degli indicatori di offerta attendibili e inviare i dati associati al tuo server in modo che possano essere caricati nel servizio Key/Value. Tuttavia, l'implementazione effettiva dipende dalla tecnologia pubblicitaria e l'API non è prescrittiva.

L'esempio seguente descrive un approccio che può essere implementato:

const ad1RenderURL = 'https://dsp.example/ad-1.html';
const ad2RenderURL = 'https://dsp.example/ad-2.html';
const ad1RenderId = 'render-id-1';
const ad2RenderId = 'render-id-2';
const ad1ReportingId = 'reporting-id-1';
const ad2ReportingId = 'reporting-id-2';

// Generate a unique identifier
const id = crypto.randomUUID();

// Define the keys with the unique ID
const trustedSignalsKeyForIG = `interest-group-${id}`

// Set the keys in the interest group
navigator.joinAdInterestGroup({
  // …
  ads: [
    {
      renderURL: ad1RenderURL,
      adRenderId: ad1RenderId,
      buyerReportingId: ad1ReportingId
    },
    {
      renderURL: ad2RenderURL,
      adRenderId: ad2RenderId,
      buyerReportingId: ad2ReportingId
    },
  ],
  trustedBiddingSignalsKeys: [
    trustedSignalsKeyForIG
  ]
});

// Send the associated data to your server to be loaded into the Key/Value Service
fetch('https://dsp.example/kv/load', {
  method: 'POST',
  body: JSON.stringify({
    id,
    [trustedSignalsKeyForIG]: {
      userBiddingSignals: {
        favoriteColor: 'blue'
      },
      ads: [
        {
          renderURL: ad1RenderURL,
          adRenderId: ad1RenderId,
          buyerReportingId: ad1ReportingId,
          metadata: {
            color: 'red'
          }   
        },
        {
          renderURL: ad2RenderURL,
          adRenderId: ad2RenderId,
          buyerReportingId: ad2ReportingId,
          metadata: {
            color: 'blue'
          }   
        },
      ]
    }
  })
});

Nell'esempio, viene definito un identificatore univoco per un IG e questo diventa parte della chiave degli indicatori attendibili. La chiave dell'IG e i relativi valori associati vengono inviati al server per essere caricati nel servizio chiavi/valori. In un secondo momento durante l'asta, il browser recupera gli indicatori attendibili e li rende disponibili nella funzione generateBid() dell'acquirente.

Se necessario, restituisci l'indicatore di aggiornamento del gruppo di interesse da K/V

La chiave updateIfOlderThanMs per gli indicatori attendibili viene utilizzata per aggiornare il gruppo di interesse prima dell'intervallo giornaliero consueto. Se il gruppo di interesse non è stato unito o aggiornato in un periodo di tempo superiore al valore in millisecondi restituito per la chiave updateIfOlderThanMs, il gruppo di interesse verrà aggiornato con il meccanismo updateURL. Tieni presente che Chrome non aggiorna i gruppi di interesse più di una volta ogni 10 minuti.

Se l'asta B&A restituisce un annuncio vincente che non corrisponde a uno degli annunci definiti nel gruppo di interesse memorizzato nel browser, l'asta non andrà a buon fine. Il meccanismo updateIfOlderThanMs può essere utile per garantire che il browser e l'asta B&A siano d'accordo sull'insieme di annunci nel gruppo di interesse.

Per saperne di più, consulta la spiegazione.

generateBid() attività

Per la chiamata generateBid() devono essere eseguite le seguenti attività.

Leggere gli indicatori del browser

L'oggetto browserSignals passato alla chiamata generateBid() di B&A ha il seguente aspetto:

{
  topWindowHostname: 'advertiser.example',
  seller: 'https://ssp.example',
  topLevelSeller: 'https://ssp-top.example',
  joinCount: 5,
  bidCount: 24,
  recency: 1684134092,

  // prevWins is [timeInSeconds, adRenderId]
  prevWins: [
    [9342, 'render-id-1'],
    [1314521, 'render-id-2']
  ],

  // Compiled WebAssembly code
  wasmHelper: WebAssembly.Module

  // Data-Version value from K/V response, if available
  dataVersion: 1,
}

In browserSignals sono disponibili le seguenti proprietà modificate o nuove:

Proprietà Descrizione
prevWins prevWins è un array di tuple di ora e annuncio. Il tempo rappresenta i secondi trascorsi dall'ultima vittoria dell'annuncio associato negli ultimi 30 giorni.

È stato modificato per fornire l'oggetto adRenderId anziché ad.
wasmHelper Oggetto compilato del codice fornito da biddingWasmHelperURL.
dataVersion Un server attendibile può includere facoltativamente un'intestazione di risposta Data-Version numerica che diventa disponibile in generateBid().

Per saperne di più, leggi l'articolo esplicativo su GitHub.

URL di rendering del reso da generateBid()

Poiché l'oggetto ads viene omesso nel payload dell'asta B&A, l'URL di rendering restituito da ads deve essere ricreato.generateBid() La modalità di ricreazione dell'URL di rendering dipende dall'implementazione e l'URL restituito deve corrispondere all'URL di rendering definito nel gruppo di interesse.

Un approccio che puoi adottare è mantenere un URL base e compilare il modello con le informazioni di interestGroup e trustedBiddingSignals.

In questo esempio, definiamo quattro annunci in base al colore e al prodotto:

await navigator.joinAdInterestGroup({
  ads: [
    { renderURL: 'https://dsp.example/red-shirt-ad.html', adRenderId: 'arid1'},
    { renderURL: 'https://dsp.example/blue-shirt-ad.html', adRenderId: 'arid2'},
    { renderURL: 'https://dsp.example/red-pants-ad.html', adRenderId: 'arid3'},
    { renderURL: 'https://dsp.example/blue-pants-ad.html', adRenderId: 'arid4'},
  ],
  trustedBiddingSignalKeys: [
    'userBiddingSignals-someUniqueId',
    // ...and more
  ]
})

Poi inviamo il colore preferito dell'utente e le informazioni sul prodotto da caricare nel servizio Key/Value:

fetch('https://dsp.example/kv/load', {
  body: JSON.stringify({
    'userBiddingSignals-someUniqueId': {
      favoriteColor: 'blue',
      favoriteProduct: 'shirt'
    }
  })
})

In un secondo momento, quando viene eseguita l'asta, gli indicatori per le offerte attendibili diventano disponibili in generateBid() e queste informazioni possono essere utilizzate per ricostruire l'URL:

function generateBid(..., trustedBiddingSignals, browserSignals) {
  const { userBiddingSignals } = trustedBiddingSignals
  const { favoriteColor, favoriteProduct } = userBiddingSignals

  return {
    bid: 1,
    render: `https://dsp.example/${favoriteColor}-${favoriteProduct}-ad.html`
  }
}

ID report sui ritorni da generateBid()

Poiché gli ID report non sono inclusi nel payload dell'asta B&A, l'ID diventa disponibile per generateBid() tramite indicatori di offerta attendibili. Una volta determinato l'ID report da utilizzare, l'ID report scelto viene restituito da generateBid(). Gli ID restituiti devono corrispondere a quelli definiti nel gruppo di interesse.

In questo esempio, viene scelto l'annuncio 1 e il relativo ID di rendering viene restituito da generateBid():

generateBid(..., trustedBiddingSignals, …) {
  const { ad1ReportingId, ad2reportingId } = trustedBiddingSignals;
  // ...
  return {
    bid: 1,
    render: 'https://dsp.example/ad-1.html'
    buyerReportingId: ad1reportingId
  }
}

L'ID report restituito diventa disponibile in reportWin() e buyerReportingSignals:

reportWin(..., buyerReportingSignals) {
  const { buyerReportingId } = buyerReportingSignals;
}

Se buyerReportingId non viene restituito da generateBid(), il valore interestGroupName è disponibile in buyerReportingSignals anziché in buyerReportingId.

Per saperne di più, consulta la guida all'ID report.

Passaggi successivi

Hai a disposizione le seguenti risorse

Scopri di più

Domande?