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 Trusted Execution Environment (TEE) per facilitare un'asta Protected Audience (PA). Questa Guida per gli sviluppatori spiega come un acquirente può integrarsi con un'asta PA B&A per Chrome.

Panoramica

Per partecipare a un'asta Protected Audience con B&A Services, l'acquirente aggiorna il gruppo di interesse (GI) per ottimizzare il payload e migliorare la latenza dell'asta.

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

• joinAdInterestGroup() tasks
  • Impostare i flag di richiesta del server
  • Impostare gli ID rendering annuncio
  • Impostare le priorità dei gruppi di interesse
  • Configurare gli indicatori di offerta attendibili
• generateBid() tasks
  • Leggi gli indicatori del browser
  • Return render URL
  • ID report sui resi

Gruppo basato sugli interessi per B&A

Di seguito è riportata una configurazione di gruppo di interesse di esempio per un'asta PA B&A 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 dei gruppi di interesse B&A e on-device sono:

• 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 ometterli utilizzando il flag omit-user-bidding-signals. I segnali 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 nel gruppo di interesse.
• Gli ID report sono definiti nella guida all'integrazione di B&A, ma non sono inclusi nel payload dell'asta B&A. L'ID report restituito da generateBid() in un secondo momento durante il periodo dell'asta deve corrispondere all'URL di rendering definito nel gruppo di interesse.
• L'ad.metadata e gli ID report non sono inclusi nel payload dell'asta B&A. Questi dati diventano disponibili tramite l'utilizzo del servizio di coppie chiave-valore attendibili.

Tieni presente che gli ID report e renderURL 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 verifica 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:

I dati omessi vengono gestiti rendendo disponibili le 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'],
});

Imposta ID rendering annuncio

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

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

Un esempio di gruppo di interesse con ID rendering 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'
    },
  ],
});

Il adRenderId associato agli annunci diventa disponibile in prevWins.browserSignals in 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 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 basati sugli interessi. Se viene raggiunto il limite di dimensioni del payload per acquirente impostato dal venditore, i valori di priorità dei gruppi 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 di gruppi di interesse tra diversi acquirenti, il browser decide in base alle dimensioni del payload serializzato. Per impostazione predefinita, a ogni acquirente viene assegnata una dimensione uguale. Tieni presente che la definizione delle priorità effettiva avviene sui server B&A e non durante la generazione del 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 ignorare gli indicatori di priorità del venditore.

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 ridotto a 8 + -3, quindi la priorità di questo gruppo di interesse al momento dell'asta è 5.

Sono disponibili anche indicatori aggiuntivi da utilizzare per la definizione delle priorità in Brand Lift:

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

Configurare gli indicatori di offerta attendibili

Poiché alcuni dati verranno omessi dal payload dell'asta Acquisto e asta, puoi utilizzare il servizio chiave/valore 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

Un approccio che può essere adottato consiste nell'includere un identificatore univoco nelle chiavi degli indicatori di offerta attendibili e quindi inviare i dati associati al tuo server in modo che possano essere caricati nel servizio chiave/valore. Tuttavia, l'implementazione effettiva dipende dalla tecnologia pubblicitaria e l'API non è prescrittiva.

Il seguente esempio 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 gruppo di interesse e diventa parte della chiave dei segnali attendibili. La chiave del gruppo di interesse e i relativi valori 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.

Restituisci l'indicatore di aggiornamento del gruppo di interesse da K/V, se necessario

La chiave updateIfOlderThanMs per gli indicatori attendibili viene utilizzata per aggiornare il gruppo di interesse prima dell'intervallo giornaliero abituale. Se il gruppo di interesse non è stato aggiunto o aggiornato per 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 aggiornerà 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 concordino sul set di annunci nel gruppo basato sugli interessi.

Per saperne di più, consulta la spiegazione.

generateBid() attività

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

Leggi 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:

Restituisci l'URL di rendering da generateBid()

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

Un approccio che potrebbe essere adottato è quello di mantenere un URL di 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
  ]
})

Quindi inviamo il colore preferito dell'utente e le informazioni sul prodotto da caricare nel servizio chiave/valore:

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 di offerta 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`
  }
}

Restituisci gli ID report da generateBid()

Poiché gli ID report non sono inclusi nel payload dell'asta B&A, l'ID diventa disponibile per generateBid() tramite gli indicatori di offerta attendibili. Una volta determinato l'ID report da utilizzare, quest'ultimo 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 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() fino a buyerReportingSignals:

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

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

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

Passaggi successivi

Sono disponibili le seguenti risorse

Scopri di più

• Scopri di più sulle configurazioni dell'asta B&A in Chrome
• Sperimenta con Protected Audience con B&A seguendo il codelab per i test locali end-to-end.

Domande?

• Se hai una domanda sui servizi di aste e offerte, apri un problema nel repository dei servizi di aste e offerte.