Als Verkäufer mit B&A verknüpfen

Gebots- und Auktionsdienste sind eine Reihe von Diensten für Werbetreibende und Verkäufer, die in einer vertrauenswürdigen Ausführungsumgebung (Trusted Execution Environment, TEE) ausgeführt werden, um eine Protected Audience-Auktion (PA) zu ermöglichen. In diesem Entwicklerhandbuch wird erläutert, wie ein Verkäufer eine Chrome-PA-Auktion für B&A einbinden kann.

Schritt-für-Schritt-Anleitung

Ablauf der Verkäuferintegration, bei dem der JavaScript-Code die B&A-Auktionsnutzlast erhält, die an SAS gesendet wird, und SAS die Anfrage an das Verkäufer-Front-End (SFE) weiterleitet. SFE gibt das Ergebnis zurück, das SAS an den Browser weiterleiten soll, und der JavaScript-Code des Verkäufers ruft „runAdAuction“ auf.

Die Schritte können so zusammengefasst werden:

  1. getInterestGroupAdAuctionData() aufrufen, um die verschlüsselte Nutzlast vom Browser abzurufen
  2. Rufen Sie fetch('https://your-ad-server.example') auf und senden Sie die Anfrage für die einheitliche Auktion mit der verschlüsselten Nutzlast an Ihren SAS.
  3. Rufen Sie den SelectAd()-Vorgang Ihrer SFE von Ihrem SAS aus auf, um die B&A-Auktion auszuführen.
  4. B&A-Auktionsergebnis zusammen mit dem Hash der Antwort auf die Seite zurückgeben
  5. Rufen Sie runAdAuction() im Browser auf, um eine PA-Auktion für Einzelkunden, im gemischten Modus oder für mehrere Kunden auszuführen, und geben Sie das serverseitige Ergebnis der B&A-Auktion an den Aufruf weiter.

Verschlüsselte Daten zu Anzeigenauktionen abrufen

Dasselbe Schritt-für-Schritt-Diagramm mit dem hervorgehobenen ersten Schritt, bei dem der JavaScript-Code des Verkäufers „getInterestGroupAdAuctionData“ aufruft

Um die Daten für die serverseitige B&A-Auktion abzurufen, ruft der JavaScript-Code des Verkäufers auf der Publisher-Seite navigator.getInterestGroupAdAuctionData() auf.

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;
Feld Beschreibung
seller Erforderlich. Herkunft des Verkäufers, der die Auktion durchführt. Dieser Wert muss mit dem seller-Wert im runAdAuction()-Aufruf übereinstimmen.
requestSize Optional: Legt die maximale Nutzlastgröße aller Käuferdaten fest. Weitere Informationen finden Sie im Abschnitt Anfragegröße der Erläuterung.
perBuyerConfig Optional: Hier legen Sie Konfigurationen für jeden Käufer fest und steuern, welche Käufer an der B&A-Auktion teilnehmen.

Wenn Käuferquellen in perBuyerConfig aufgeführt sind, sind nur die Daten der Käuferinteressengruppe in der Nutzlast enthalten. Wenn in perBuyerConfig keine Käufer aufgeführt sind, sind alle Interessengruppen des Nutzers in der Payload enthalten.
targetSize Optional, wenn requestSize festgelegt ist. Erforderlich, wenn in perBuyerConfig ein Käuferursprung festgelegt ist, requestSize aber nicht.

Legt die maximale Nutzlastgröße der Daten dieses Käufers fest. Weitere Informationen finden Sie im Abschnitt Anfragegröße der Erläuterung.
coordinatorOrigin Optional, wird aber irgendwann erforderlich sein. Wenn kein Wert festgelegt ist, wird https://publickeyservice.pa.gcp.privacysandboxservices.com als Standardwert verwendet.

Legt den Koordinator fest, der zum Abrufen des Schlüssels zum Verschlüsseln der Nutzlast verwendet werden soll. Weitere Informationen finden Sie im Abschnitt Koordinator der Erläuterung.

Bei der Aufrufung liest der Browser die Interessengruppen der in perBuyerConfig aufgeführten Käufer und verschlüsselt die Käuferdaten. Diese Käuferdaten enthalten websiteübergreifende Informationen, die für Gebote verwendet werden. Sie können nicht außerhalb eines TEE entschlüsselt werden. Bei der Nutzlastoptimierung sind nur der Name der Interessengruppe, die Schlüssel für vertrauenswürdige Gebotssignale und Browsersignale in der Nutzlast enthalten.

Im vom getInterestGroupAdAuctionData()-Aufruf zurückgegebenen Datenobjekt für die Anzeigenauktion sind der requestId-String und das verschlüsselte request-Byte-Array verfügbar.

Screenshot der Chrome-Entwicklertools, in dem zu sehen ist, dass Anfrage und Anfrage-ID in den Daten der Anzeigenauktion verfügbar sind

Der String requestId wird später verwendet, wenn runAdAuction() aufgerufen wird, um die Auktion im Browser abzuschließen. Die verschlüsselte request-Nutzlast wird als Teil der Anfrage für die gemeinsame Auktion an den Anzeigendienst des Verkäufers gesendet.

Ein Beispiel für diesen Aufruf finden Sie im JavaScript-Code des Verkäufers der lokalen Test-App.

Anfrage für die gemeinsame Auktion an SAS senden

Dasselbe Schritt-für-Schritt-Diagramm mit dem hervorgehobenen zweiten Schritt, in dem der JavaScript-Code des Verkäufers eine einheitliche Auktionsanfrage an SAS sendet

Eine Anfrage für eine einheitliche Auktion enthält die Nutzlast der kontextbezogenen Auktion im Klartext und die Nutzlast der Auktion mit Preis- und Verfügbarkeitsinformationen. Die Auktionsnutzlast für die Preis- und Verfügbarkeitsanfrage ist die verschlüsselte request-Daten, die der Browser im getInterestGroupAdAuctionData()-Aufruf generiert hat. Diese Anfrage wird an SAS gesendet, wo die kontextbezogene Auktion und die B&A-Auktion für die Preisvergleichsportale verwaltet werden.

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

Um die Anfrage an SAS zu senden, wird von der Seite ein fetch()-Aufruf ausgeführt:

  • Der Aufruf muss die Option adAuctionHeaders: true enthalten, die dem Browser signalisiert, die Antwort dieses Aufrufs später zu überprüfen, wenn runAdAuction() aufgerufen wird, um die Auktion im Browser abzuschließen.
  • Der Ursprung der Abrufanfrage muss mit dem seller-Ursprung übereinstimmen, der für die getInterestGroupAdAuctionData()- und runAdAuction()-Aufrufe angegeben wurde.

Der Body des Aufrufs enthält:

  1. Die Klartextnutzlast der kontextbezogenen Auktion, die von SAS für die Durchführung der kontextbezogenen Auktion verwendet wird.
  2. Die verschlüsselte Protected Audience-Auktionsnutzlast, die von SAS an die SFE gesendet wird, um die serverseitige B&A-Auktion durchzuführen.

Ein Beispiel für diesen Aufruf finden Sie im JavaScript-Code des Verkäufers der lokalen Test-App.

Base64-Codierung und -Decodierung

Die verschlüsselte request-Nutzlast, die vom getInterestGroupAdAuctionData()-Aufruf zurückgegeben wird, ist eine Instanz von Uint8Array, einem Datentyp, der von JSON nicht verarbeitet werden kann. Wenn Sie das Byte-Array in einem JSON-Format senden möchten, können Sie die Binärdaten mit einer base64 in einen String umwandeln.

Die JavaScript-Browser API bietet die Funktionen atob() und btoa() für window, mit denen zwischen Binärdaten und Base64-codierten ASCII-Strings konvertiert werden kann. (atob steht für ASCII-zu-Binär und btoa für Binär-zu-ASCII).

Der Aufruf von btoa() zum Codieren von Binärdaten in einen base64-codierten String sieht so aus:

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

Das verschlüsselte B&A-Auktionsergebnis, das von diesem fetch-Aufruf zurückgegeben wird, ist ebenfalls base64-codiert. Sie müssen es also wieder in Binärdaten decodieren. Rufe atob() auf, um den Base64-codierten ASCII-String in Binärdaten zu decodieren:

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

Ein Base64-codierter String ist jedoch in der Regel etwa 33% größer als die ursprünglichen Daten. Wenn Sie die Latenz weiter verbessern möchten, verwenden Sie zum Senden der Binärdaten ein anderes Format als JSON.

SelectAd der SFE aufrufen, um die B&A-Auktion durchzuführen

Dasselbe Ablaufdiagramm mit dem dritten Schritt, bei dem SAS eine SelectAd-Anfrage an SFE sendet und SFE eine B&A-Auktion durchführt

Sobald der Anzeigendienst des Verkäufers die Anfrage für die gemeinsame Auktion von der Seite erhält, wird zuerst die kontextbezogene Auktion ausgeführt, um den Gewinner der kontextbezogenen Auktion zu ermitteln und die Käufersignale zu erfassen, die an die B&A-Auktion von Publisher Advantage übergeben werden. Anschließend wird die B&A-Auktion gestartet, indem der SelectAd-Vorgang der SFE aus SAS mit der Anfragen-Nutzlast aufgerufen wird. Einige Metadaten aus der Anfrage der Seite an SAS in Schritt 2 werden an die SFE weitergeleitet.

SelectAdRequest-Nutzlast erstellen

Die Nutzlast der SelectAd-Anfrage kann so aufgebaut sein:

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

Wenn die verschlüsselten Daten der Anzeigenauktion aus dem Browser base64-codiert waren, müssen sie zurück in Binärdaten decodiert werden, wenn die Anfrage an die SFE mit gRPC gesendet wird. Wenn die Anfrage über HTTP gesendet wird, können die verschlüsselten Daten der Anzeigenauktionen in ihrer Base64-codierten Form bleiben.

Weitere in der SelectAd-Anfrage definierte Felder finden Sie in der Proto-Definition von SelectAdRequest.

Verkäuferfeld der obersten Ebene für Auktionen im gemischten Modus und Komponentenauktionen festlegen

Wenn der Verkäufer eine Auktion im gemischten Modus durchführt oder als Komponentenverkäufer an einer Mehrfachkundenauktion teilnimmt, muss das Feld top_level_seller in der Anfrage definiert werden.

Wenn Sie im gemischten Modus verkaufen, ist der Wert top_level_seller Ihr Herkunftsland:

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

Wenn Sie ein Komponentenanbieter sind, ist der Wert für top_level_seller der Verkäufer der obersten Ebene der Auktion mit mehreren Verkäufern:

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

SelectAd von SFE anrufen

Der Aufruf von SFE von SAS aus kann mit gRPC oder HTTP erfolgen.

gRPC-Aufruf

Die gRPC-Anfrage an die SFE sieht so aus, wenn Express in Node mit einem gRPC-Client verwendet wird:

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

Die Proto-Definition für den SFE-Client finden Sie im Repository der lokalen Test-App.

HTTP-Aufruf an den Envoy-Proxy

Die HTTP-POST-Anfrage an die SFE wird an den Pfad /v1/selectAd gesendet und sieht so aus:

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

Metadaten weiterleiten

Die folgenden Metadaten aus dem SAS-Aufruf der Seite müssen dem SelectAd-Aufruf von SAS an die SFE hinzugefügt werden:

Wenn die Metadaten an die SFE gesendet werden, müssen die folgenden nicht standardmäßigen Header verwendet werden, da gRPC den User-Agent-Header ändern kann:

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

Im folgenden Beispiel wird gezeigt, wie die Metadaten mit Express in Node mit einem gRPC-Client weitergeleitet werden können:

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

Im folgenden Beispiel wird gezeigt, wie die Metadaten mit einem HTTP-Aufruf weitergeleitet werden können:

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

Servergestützte Mehrfachkundenauktion

Wenn Sie ein Verkäufer auf oberster Ebene sind und eine servergestützte Mehrfachkunden-Auktion durchführen, wird der GetComponentAuctionCiphertexts-Aufruf an die SFE gesendet, bevor der SelectAd-Aufruf erfolgt. Die Antwort enthält die neu verschlüsselten Auktionsnutzlasten für Komponenten, die an die Werbedienste des Komponentenanbieters gesendet werden. Die zurückgegebenen Ergebnisse der Anzeigenauktionen für die Komponenten „B&A“ werden an den SelectAd-Aufruf der SFE des Verkäufers der obersten Ebene gesendet.

Weitere Informationen finden Sie in der Erläuterung zu Mehrfachverkäufern auf GitHub.

B&A-Auktionsergebnis auf die Seite zurückgeben

Dasselbe Schritt-für-Schritt-Diagramm mit dem hervorgehobenen vierten Schritt, in dem SAS das Auktionsergebnis von SelectAd an den Browser zurücksendet

Nach Abschluss der B&A-Auktion wird das verschlüsselte Auktionsergebnis an SAS zurückgegeben. SAS antwortet dann auf die Anfrage für die einheitliche Auktion von der Seite in Schritt 2 mit dem verschlüsselten Auktionsergebnis. In der SAS-Antwort auf die Seite wird der base64url-codierte SHA-256-Hash des verschlüsselten Auktionsergebnisses im Ad-Auction-Result-Antwortheader festgelegt. Dieser Hash wird vom Browser verwendet, um die Nutzlast zu überprüfen, wenn die Auktion im Client abgeschlossen wird.

So erstellen Sie in Node einen SHA-256-Hash mit Base64-Codierung:

import { createHash } from 'crypto';

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

Das Anhängen des Hashwerts im Antwortheader und das Zurückgeben des Auktionsergebnisses an die Seite sieht so aus:

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

Da dies eine Antwort auf die Anfrage für die gemeinsame Auktion ist, die in Schritt 2 von der Seite gesendet wurde, ist auch das Ergebnis der kontextbezogenen Auktion in der Antwort enthalten.

Es können mehrere Hashes in der Ad-Auction-Result enthalten sein, indem der Header wiederholt oder die Hashes getrennt werden. Die folgenden beiden Antwortheader sind gleichwertig:

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

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

Ein Beispiel für diesen Aufruf finden Sie im Servercode des Verkäufers der lokalen Test-App.

Rufen Sie runAdAuction() an, um die Auktion abzuschließen

Das gleiche Ablaufdiagramm mit dem hervorgehobenen fünften Schritt, in dem der clientseitige JavaScript-Code die Auktion durchführt und die Serverantwort liefert

Die einheitliche Auktionsantwort, die von SAS zurückgegeben wird, enthält das verschlüsselte B&A-Auktionsergebnis. Diese Nutzlast wird an den runAdAuction()-Aufruf übergeben, um die Auktion im Browser abzuschließen. Der Wert requestId aus dem getInterestGroupAdAuctionData()-Aufruf in Schritt 1 wird ebenfalls an die Auktion übergeben.

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

Die Struktur der Auktionskonfiguration, die an den runAdAuction()-Aufruf übergeben wird, hängt von der vom Verkäufer ausgewählten Auktionskonfiguration ab.

Auktion für Einzelkundenkonto

Für die Durchführung einer B&A-Auktion mit einem einzelnen Verkäufer sieht die Auktionskonfiguration des runAdAuction()-Aufrufs so aus:

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

Das Feld requestId akzeptiert den requestId, der vom getInterestGroupAdAuctionData()-Aufruf zurückgegeben wird. Das Feld serverResponse akzeptiert ein Byte-Array der B&A-Auktion, die in Schritt 3 ausgeführt wurde.

Ein Beispiel für diesen Aufruf finden Sie im JavaScript-Code des Verkäufers der lokalen Test-App.

Auktion im gemischten Modus

Wenn Sie eine B&A-Auktion im gemischten Modus ausführen möchten, an der sowohl On-Device- als auch B&A-Käufer teilnehmen können, sieht die Auktionskonfiguration des runAdAuction()-Aufrufs so aus:

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
      ],
    },
  ]
});

Für eine Auktion im gemischten Modus werden das B&A-Auktionsergebnis und die On-Device-Auktionskonfiguration in das Feld componentAuctions übergeben. Bei Auktionen im gemischten Modus ist der Wert für seller sowohl für die übergeordnete Konfiguration als auch für die Komponentenkonfigurationen identisch.

Ein Beispiel für diesen Aufruf finden Sie im JavaScript-Code des Verkäufers der lokalen Test-App.

Mehrfachkundenauktion

Wenn Sie ein Verkäufer auf oberster Ebene sind und eine gerätebasierte Mehrfachkundenauktion durchführen, reichen alle Komponentenverkäufer ihr B&A-Auktionsergebnis und die On-Device-Auktionskonfigurationen ein.

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',
    }
  ]
})

Ein Beispiel für diesen Aufruf finden Sie im JavaScript-Code des Verkäufers der lokalen Test-App.

Nächste Schritte

Nachdem Sie diesen Leitfaden gelesen haben, können Sie die folgenden Schritte ausführen:

Weitere Informationen

Hast du Fragen?