Integrare la piattaforma con B&A come venditore

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 venditore può integrarsi con un'asta Chrome PA per B&A.

Procedura dettagliata

I passaggi possono essere riassunti come segue:

1. Chiama getInterestGroupAdAuctionData() per ottenere il payload criptato dal browser
2. Chiama fetch('https://your-ad-server.example') e invia la richiesta di asta unificata con il payload criptato al tuo SAS
3. Chiama l'operazione SelectAd() del tuo SFE dal tuo SAS per eseguire l'asta B&A
4. Restituisci alla pagina il risultato dell'asta B&A insieme all'hash della risposta
5. Chiama runAdAuction() nel browser per eseguire un'asta PA a venditore singolo, in modalità mista o multi-venditore e trasmetti il risultato dell'asta B&A lato server alla chiamata

Ottenere dati criptati sull'asta dell'annuncio

Per ottenere i dati necessari per eseguire l'asta B&A lato server, il codice JavaScript del venditore nella pagina del publisher chiama navigator.getInterestGroupAdAuctionData().

const adAuctionData = await navigator.getInterestGroupAdAuctionData({
  seller: 'https://ssp.example', // Required
  requestSize: 51200,
  coordinatorOrigin: 'https://publickeyservice.pa.gcp.privacysandboxservices.com/',
  perBuyerConfig: {
    'https://dsp-x.example': { targetSize: 8192 },
    'https://dsp-y.example': { targetSize: 8192 }
  }
});

const { requestId, request } = adAuctionData;

Quando viene effettuata la chiamata, il browser legge i gruppi di interesse degli acquirenti elencati in perBuyerConfig e cripta i dati degli acquirenti. Questi dati dell'acquirente contengono informazioni cross-site da utilizzare per le offerte e non possono essere decriptati al di fuori di un TEE. Per l'ottimizzazione del payload, nel payload sono inclusi solo il nome del gruppo di interesse, le chiavi degli indicatori di offerta attendibili e gli indicatori del browser.

Nell'oggetto dati dell'asta dell'annuncio restituito dalla chiamata getInterestGroupAdAuctionData() sono disponibili la stringa requestId e l'array di byte request criptato.

La stringa requestId viene utilizzata in un secondo momento quando viene chiamato runAdAuction() per completare l'asta nel browser. Il payload request criptato viene inviato al servizio di annunci del venditore come parte della richiesta di asta unificata.

Per vedere un esempio di questa chiamata, consulta il codice JavaScript del venditore dell'app di test locale.

Invia la richiesta di asta unificata a SAS

Una richiesta di asta unificata è una richiesta che contiene il payload dell'asta contestuale in testo normale e il payload dell'asta PA B&A. Il payload dell'asta PA B&A sono i dati request criptati generati dal browser nella chiamata getInterestGroupAdAuctionData(). Questa richiesta viene inviata a SAS, dove vengono orchestrate l'asta contestuale e l'asta PA B&A.

fetch('https://ssp.example/ad-auction', {
  method: 'POST',
  adAuctionHeaders: true,
  body: JSON.stringify({
    contextualAuctionPayload: { somePayload },
    protectedAudienceAuctionPayload: encodeBinaryData(request)
  }),
});

Per inviare la richiesta a SAS, viene effettuata una chiamata fetch() dalla pagina:

• La chiamata deve includere l'opzione adAuctionHeaders: true, che indica al browser di verificare la risposta di questa chiamata in un secondo momento, quando viene chiamata runAdAuction() per completare l'asta nel browser.
• L'origine della richiesta di recupero deve corrispondere all'origine seller fornita alle chiamate getInterestGroupAdAuctionData() e runAdAuction().

Il corpo della chiamata contiene:

1. Il payload dell'asta contestuale in testo normale da utilizzare da SAS per eseguire l'asta contestuale.
2. Il payload dell'asta Protected Audience criptato da inviare a SFE da SAS per eseguire l'asta B&A lato server.

Per vedere un esempio di questa chiamata, consulta il codice JavaScript del venditore dell'app di test locale.

Codifica e decodifica Base64

Il payload request criptato restituito dalla chiamata getInterestGroupAdAuctionData() è un'istanza di Uint8Array, un tipo di dati che JSON non può gestire. Per inviare l'array di byte in formato JSON, puoi applicare una codifica base64 ai dati binari per convertirli in una stringa.

L'API JavaScript per browser fornisce le funzioni atob() e btoa() su window che convertono i dati binari in stringhe ASCII con codifica Base64 e viceversa. atob indica la conversione da ASCII a binario e btoa indica la conversione da binario ad ASCII.

Chiama btoa() per codificare i dati binari in una stringa con codifica base64 come segue:

function encodeBinaryData(data) {
  return btoa(String.fromCharCode.apply(null, data));
}

Il risultato dell'asta B&A criptato restituito da questa chiamata fetch è anche in codifica Base64, quindi devi decodificarlo nuovamente in dati binari. Chiama atob() per decodificare la stringa ASCII con codifica base64 in dati binari:

function decodeBase64String(base64string) {
  return new Uint8Array(
    atob(base64string)
      .split('')
      .map((char) => char.charCodeAt(0))
  );
}

Tuttavia, una stringa con codifica base64 è in genere circa il 33% più grande dei dati originali. Se vuoi migliorare ulteriormente la latenza, utilizza un formato diverso da JSON per inviare i dati binari.

Chiama SelectAd di SFE per eseguire l'asta B&A

Una volta che il servizio di annunci del venditore riceve la richiesta di asta unificata dalla pagina, viene eseguita prima l'asta contestuale per determinare il vincitore e raccogliere gli indicatori dell'acquirente da trasmettere all'asta PA B&A. Quindi, l'asta B&A viene avviata chiamando l'operazione SelectAd di SFE da SAS con il payload della richiesta. Tieni presente che alcuni metadati della richiesta della pagina a SAS nel passaggio 2 vengono inoltrati a SFE.

Costruisci il payload SelectAdRequest

Il payload della richiesta della chiamata SelectAd può essere costruito come segue:

const selectAdRequest = {
  auction_config: {
    seller: 'https://ssp.example',
    auction_signals: '{"testKey":"someValue"}',
    seller_signals: '{"testKey":"someValue"}',
    buyer_list: [
      'https://dsp-x.example',
      'https://dsp-y.example',
    ],
    per_buyer_config: {
      'https://dsp-x.example': { buyer_signals: '{"testKey": "someValue"}' },
      'https://dsp-y.example': { buyer_signals: '{"testKey": "someValue"}' },
    },
  },
  client_type: 'CLIENT_TYPE_BROWSER',
  protected_auction_ciphertext: decodeBase64string(request)
};

Tieni presente che se i dati criptati dell'asta dell'annuncio del browser sono stati codificati in base64, devono essere decodificati nuovamente in dati binari se la richiesta a SFE viene inviata utilizzando gRPC. Se la richiesta viene inviata tramite HTTP, i dati criptati dell'asta dell'annuncio possono rimanere nel formato con codifica Base64.

Per visualizzare altri campi definiti nella richiesta SelectAd, consulta la definizione proto di SelectAdRequest.

Imposta il campo venditore di primo livello per le aste in modalità mista e per componenti

Se il venditore gestisce un'asta in modalità mista o partecipa come venditore di componenti a un'asta multi-venditore, il campo top_level_seller deve essere definito nella richiesta.

Se sei un venditore in modalità mista, il valore top_level_seller è la tua origine:

const selectAdRequest = {
  auction_config: {
    seller: 'https://ssp-mix.example',
    top_level_seller: 'https://ssp-mix.example',
  }
}

Se sei un venditore di componenti, il valore di top_level_seller è il venditore di primo livello dell'asta multi-venditore:

const selectAdRequest = {
  auction_config: {
    seller: 'https://ssp-mix.example',
    top_level_seller: 'https://ssp-top.example',
  }
}

Chiama SelectAd di SFE

La chiamata a SFE da SAS può essere effettuata con gRPC o HTTP.

Chiamata gRPC

La richiesta gRPC a SFE ha il seguente aspetto utilizzando Express in Node con un client gRPC:

import grpc from '@grpc/grpc-js';

// Load proto definition
const packageDefinition = protoLoader.loadSync(protoPath, { keepCase: true, enums: String });

const {
  privacy_sandbox: {
    bidding_auction_servers: { SellerFrontEnd }
  }
} = grpc.loadPackageDefinition(packageDefinition);

// Instantiate the gRPC client
const sfeGrpcClient = new SellerFrontEnd('192.168.84.104:50067', grpc.credentials.createInsecure());

// Send SelectAd request
sfeGrpcClient.selectAd(selectAdRequest,(error, response) => {
  // Handle SFE response
});

La definizione proto per il client SFE è disponibile nel repository dell'app di test locale.

Chiamata HTTP al proxy Envoy

La richiesta HTTP POST a SFE viene inviata al percorso /v1/selectAd e ha il seguente aspetto:

fetch('https://ssp-ba.example/sfe/v1/selectAd', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(selectAdRequest),
});

Metadati inoltrati

I seguenti metadati della chiamata alla SAS dalla pagina devono essere aggiunti alla chiamata SelectAd della SAS a SFE:

• Accept-Language
• User-Agent
• Indirizzo IP

Quando i metadati vengono inviati a SFE, devono utilizzare le seguenti intestazioni non standard perché gRPC potrebbe modificare l'intestazione User-Agent:

• X-Accept-Language
• X-User-Agent
• X-BnA-Client-IP

Di seguito è riportato un esempio di come i metadati possono essere inoltrati utilizzando Express in Node con un client gRPC:

sellerAdService.post('/ad-auction', (req, res) => {
  // …
  const metadata = new grpc.Metadata();
  metadata.add('X-Accept-Language', req.header('Accept-Language'));
  metadata.add('X-User-Agent', req.header('User-Agent'));
  metadata.add('X-BnA-Client-IP', req.ip);

  const sfeGrpcClient = createSfeGrpcClient();
  sfeGrpcClient.selectAd(selectAdRequest, metadata, callbackFn);
})

Di seguito è riportato un esempio di come i metadati possono essere inoltrati utilizzando una chiamata HTTP:

sellerAdService.post('/ad-auction', (req, res) => {
  // …
  fetch('https://ssp-ba.example/sfe/v1/selectAd', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Accept-Language': req.header('Accept-Language'),
      'X-User-Agent': req.header('User-Agent'),
      'X-BnA-Client-IP': req.ip
    },
    body: JSON.stringify(selectAdRequest)
  });
})

Asta multi-venditore orchestrata dal server

Se sei un venditore di primo livello che esegue un'asta multi-venditore orchestrata dal server, la chiamata GetComponentAuctionCiphertexts viene effettuata a SFE prima della chiamata SelectAd. La risposta contiene i payload dell'asta dei componenti ri-criptati che vengono inviati ai servizi pubblicitari del venditore di componenti. I risultati dell'asta dell'annuncio B&A del componente restituito vengono forniti alla chiamata SelectAd dell'SFE del venditore di primo livello.

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

Restituisci alla pagina il risultato dell'asta B&A

Al termine dell'asta B&A, il risultato dell'asta criptato viene restituito a SAS, che risponde alla richiesta di asta unificata dalla pagina del passaggio 2 con il risultato dell'asta criptato. Nella risposta SAS alla pagina, l'base64url del risultato dell'asta criptato viene impostato nell'intestazione della risposta Ad-Auction-Result. Questo hash viene utilizzato dal browser per verificare il payload al termine dell'asta nel client.

La creazione di un hash SHA-256 con codifica base64 in Node ha il seguente aspetto:

import { createHash } from 'crypto';

createHash('sha256')
  .update(binaryData, 'base64')
  .digest('base64url');

L'allegato dell'hash nell'intestazione della risposta e la restituzione del risultato dell'asta alla pagina sono simili a quanto segue:

sellerAdService.post('/ad-auction', (req, res) => {
  // …
  sfeGrpcClient.selectAd(selectAdRequest, metadata, (error, response) => {
    const { auction_result_ciphertext } = response;

    const ciphertextShaHash = createHash('sha256')
      .update(auction_result_ciphertext, 'base64')
      .digest('base64url');

    res.set('Ad-Auction-Result', ciphertextShaHash);

    res.json({
      protectedAudienceAuctionResult: encodeBinaryData(auction_result_ciphertext),
      contextualAuctionResult: getContextualAuctionResult()
    });
  });
})

Poiché si tratta di una risposta alla richiesta di asta unificata effettuata dalla pagina nel passaggio 2, nella risposta è incluso anche il risultato dell'asta contestuale.

È possibile includere più hash in Ad-Auction-Result ripetendo l'intestazione o separando gli hash. Le seguenti due intestazioni di risposta sono equivalenti:

Ad-Auction-Result: ungWv48Bz-pBQUDeXa4iI7ADYaOWF3qctBD_YfIAFa0=,9UTB-u-WshX66Xqz5DNCpEK9z-x5oCS5SXvgyeoRB1k=

Ad-Auction-Result: ungWv48Bz-pBQUDeXa4iI7ADYaOWF3qctBD_YfIAFa0=
Ad-Auction-Result: 9UTB-u-WshX66Xqz5DNCpEK9z-x5oCS5SXvgyeoRB1k=

Per vedere un esempio di questa chiamata, consulta il codice del server del venditore dell'app di test locale.

Chiama runAdAuction() per completare l'asta

La risposta dell'asta unificata restituita da SAS include il risultato dell'asta B&A criptato. Questo payload viene passato alla chiamata runAdAuction() per completare l'asta nel browser. Anche il valore requestId della chiamata getInterestGroupAdAuctionData() nel passaggio 1 viene trasmesso all'asta.

// Get the encrypted ad auction data (Step #1)
const { requestId, request } = navigator.getInterestGroupAdAuctionData(adAuctionDataConfig)

// Send unified auction request (Step #2)
const response = await fetch('https://ssp-ba.example/ad-auction', {
  method: 'POST',
  body: JSON.stringify({
    adAuctionRequest: encodeBinaryData(request),
  }),
});

const { protectedAudienceAuctionResult } = await response.json();

// Finish the auction in the browser
await navigator.runAdAuction({
  // pass in "requestId" and "protectedAudienceAuctionResult"
  // the config structure will differ based on the auction configuration
});

La struttura della configurazione dell'asta passata nella chiamata runAdAuction() varia in base alla configurazione dell'asta scelta dal venditore.

Asta con un solo venditore

Per eseguire un'asta B&A per un singolo venditore, la configurazione dell'asta della chiamata runAdAuction() viene creata come segue:

await navigator.runAdAuction({
  seller: 'https://ssp-ba.example',
  requestId,
  serverResponse: protectedAudienceAuctionResult,
});

Il campo requestId accetta il valore requestId restituito dalla chiamata getInterestGroupAdAuctionData(). Il campo serverResponse accetta un array di byte dell'asta B&A eseguita nel passaggio 3.

Per vedere un esempio di questa chiamata, consulta il codice JavaScript del venditore dell'app di test locale.

Asta in modalità mista

Per eseguire un'asta B&A in modalità mista in cui possono partecipare sia gli acquirenti on-device sia quelli B&A, la configurazione dell'asta della chiamata runAdAuction() è strutturata come segue:

await navigator.runAdAuction({
  seller: 'https://ssp-mix.example',
  decisionLogicURL: 'https://ssp-mix.example/score-ad.js',
  componentAuctions: [
    // B&A auction result
    {
      seller: 'https://ssp-mix.example',
      requestId,
      serverResponse: protectedAudienceAuctionResult,
    },
    // On-device auction config
    {
      seller: 'https://ssp-mix.example',
      decisionLogicURL: 'https://ssp-mix.example/on-device-score-ad.js',
      interestGroupBuyers: [
        'https://dsp-a.example', // On-device buyer
        'https://dsp-a.example', // On-device buyer
      ],
    },
  ]
});

Per facilitare un'asta in modalità mista, il risultato dell'asta B&A e la configurazione dell'asta sul dispositivo vengono passati nel campo componentAuctions. In un'asta in modalità mista, il valore seller è lo stesso sia per la configurazione di primo livello sia per le configurazioni dei componenti.

Per vedere un esempio di questa chiamata, consulta il codice JavaScript del venditore dell'app di test locale.

Asta multi-venditore

Se sei un venditore di primo livello che esegue un'asta multi-venditore orchestrata dal dispositivo, ogni venditore componente invia il risultato dell'asta B&A e le configurazioni dell'asta sul dispositivo.

await navigator.runAdAuction({
  seller: 'https://ssp-top.example',
  decisionLogicURL: 'https://ssp-top.example/score-ad.js',
  componentAuctions: [
    // SSP-BA's B&A-only auction result
    {
      seller: 'https://ssp-ba.example',
      requestId: 'g8312cb2-da2d-4e9b-80e6-e13dec2a581c',
      serverResponse: Uint8Array(560) [193, 120, 4, …] // Encrypted B&A auction result
    },
    // SSP-MIX's B&A auction result
    {
      seller: 'https://ssp-mix.example',
      requestId: 'f5135cb2-da2d-4e9b-80e6-e13dec2a581c',
      serverResponse: Uint8Array(560) [133, 20, 4, …] // Encrypted B&A auction result
    }.
    // SSP-MIX's on-device auction config
    {
      seller: 'https://ssp-mix.example',
      interestGroupBuyers: ['https://dsp-a.example', 'https://dsp-b.example'],
      decisionLogicURL: 'https://ssp-mix.example/score-ad.js',
    }
    // SSP-OD's on-device auction config
    {
      seller: 'https://ssp-od.example',
      interestGroupBuyers: ['https://dsp-a.example', 'https://dsp-b.example'],
      decisionLogicURL: 'https://ssp-od.example/score-ad.js',
    }
  ]
})

Per vedere un esempio di questa chiamata, consulta il codice JavaScript del venditore dell'app di test locale.

Passaggi successivi

Dopo aver letto questa guida, puoi procedere nel seguente modo:

Scopri di più

• Per una comprensione più approfondita, consulta le seguenti spiegazioni su GitHub:
  • API B&A in Chrome
  • Progettazione del sistema B&A
  • Asta multi-venditore B&A
  • Asta in modalità mista B&A
• Scopri di più sull'architettura di B&A per il web
• 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.