Als Verkäufer mit B&A verknüpfen

Gebots- und Auktionsdienste (Bidding and Auction, B&A) sind eine Reihe von Diensten für Werbetreibende und Publisher, 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 Entwicklerleitfaden wird beschrieben, wie ein Verkäufer die Integration in eine Chrome PA-Auktion für B&A vornehmen kann.

Schritt-für-Schritt-Anleitung

Die Schritte können so zusammengefasst werden:

1. Rufen Sie getInterestGroupAdAuctionData() auf, um die verschlüsselte Nutzlast vom Browser abzurufen.
2. Rufen Sie fetch('https://your-ad-server.example') auf und senden Sie die einheitliche Auktionsanfrage mit der verschlüsselten Nutzlast an Ihre SAS.
3. Rufen Sie den SelectAd()-Vorgang Ihres SFE aus Ihrem SAS auf, um die B&A-Auktion auszuführen.
4. Das Ergebnis der B&A-Auktion zusammen mit dem Hash der Antwort auf der Seite zurückgeben
5. Rufen Sie runAdAuction() im Browser auf, um eine PA-Auktion für einen einzelnen Verkäufer, im gemischten Modus oder für mehrere Verkäufer auszuführen, und übergeben Sie das serverseitige B&A-Auktionsergebnis an den Aufruf.

Verschlüsselte Daten aus Anzeigenauktionen abrufen

Um die für die serverseitige B&A-Auktion erforderlichen Daten zu erhalten, 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;

Wenn der Aufruf erfolgt, liest der Browser die in perBuyerConfig aufgeführten Interessengruppen der Käufer und verschlüsselt die Käuferdaten. Diese Käuferdaten enthalten websiteübergreifende Informationen, die für Gebote verwendet werden. Sie können nur innerhalb einer 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 Datenobjekt für die Anzeigenauktion, das vom getInterestGroupAdAuctionData()-Aufruf zurückgegeben wird, sind der requestId-String und das verschlüsselte request-Byte-Array verfügbar.

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 gemeinsamen Auktionsanfrage an den Seller Ad Service gesendet.

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

Einheitliche Auktionsanfrage an SAS senden

Eine einheitliche Auktionsanfrage ist eine Anfrage, die die Kontextauktionsnutzlast im Klartext und die Nutzlast der PA B&A-Auktion enthält. Die Nutzlast der PA B&A-Auktion ist die verschlüsselten request-Daten, die der Browser im getInterestGroupAdAuctionData()-Aufruf generiert hat. Diese Anfrage wird an SAS gesendet, wo die kontextbezogene Auktion und die PA B&A-Auktion orchestriert 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 den Browser anweist, die Antwort dieses Aufrufs zu einem späteren Zeitpunkt zu überprüfen, wenn runAdAuction() aufgerufen wird, um die Auktion im Browser abzuschließen.
• Der Ursprung der Fetch-Anfrage muss mit dem seller-Ursprung übereinstimmen, der für die getInterestGroupAdAuctionData()- und runAdAuction()-Aufrufe angegeben wurde.

Der Text des Aufrufs enthält:

1. Die unverschlüsselte kontextbezogene Auktionsnutzlast, die von SAS zum Ausführen der kontextbezogenen Auktion verwendet werden soll.
2. Die verschlüsselte Protected Audience-Auktionsnutzlast, die von SAS an 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 im JSON-Format senden möchten, können Sie die Binärdaten mit base64 codieren, um sie in einen String umzuwandeln.

Die JavaScript-Browser-API bietet die Funktionen atob() und btoa() für window, mit denen zwischen Binärdaten und Base64-codierten ASCII-Strings konvertiert wird. (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 Ergebnis der B&A-Auktion, das von diesem fetch-Aufruf zurückgegeben wird, ist ebenfalls base64-codiert. Sie müssen es also wieder in Binärdaten decodieren. Rufen Sie 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 Originaldaten. Wenn Sie die Latenz weiter verbessern möchten, verwenden Sie ein anderes Format als JSON, um die Binärdaten zu senden.

Rufen Sie das SFE-Team unter SelectAd an, um die B&A-Auktion durchzuführen.

Sobald der Seller Ad Service die Anfrage für die gemeinsame Auktion von der Seite empfängt, wird zuerst die kontextbezogene Auktion durchgeführt, um den Gewinner der kontextbezogenen Auktion zu ermitteln und die Käufersignale zu erfassen, die an die PA B&A-Auktion übergeben werden sollen. Anschließend wird die B&A-Auktion initiiert, indem der Vorgang SelectAd des SFE mit der Anfrage-Payload aus SAS aufgerufen wird. Einige Metadaten aus der Anfrage der Seite an SAS in Schritt 2 werden an SFE weitergeleitet.

SelectAdRequest-Nutzlast erstellen

Die Anfrage-Nutzlast des SelectAd-Aufrufs kann so erstellt werden:

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 wieder in Binärdaten decodiert werden, wenn die Anfrage an SFE über gRPC gesendet wird. Wenn die Anfrage über HTTP gesendet wird, können die verschlüsselten Auktionsdaten in ihrer base64-codierten Form bleiben.

Andere Felder, die in der SelectAd-Anfrage definiert sind, 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 Auktion mit mehreren Verkäufern teilnimmt, muss das Feld top_level_seller in der Anfrage definiert werden.

Wenn Sie ein Händler mit gemischtem Modus sind, ist der top_level_seller-Wert Ihr Ursprungsort:

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

Wenn Sie Komponenten verkaufen, ist der top_level_seller-Wert der Verkäufer der obersten Ebene der Multi-Seller-Auktion:

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

Rufen Sie die SelectAd von SFE an.

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

gRPC-Aufruf

Die gRPC-Anfrage an SFE sieht mit Express in Node mit einem gRPC-Client so aus:

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 Protobuf-Definition für den SFE-Client finden Sie im Repository der App für lokale Tests.

HTTP-Aufruf an den Envoy-Proxy

Die HTTP-POST-Anfrage an 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 Aufruf von SAS auf der Seite sollten dem SelectAd-Aufruf von SAS an SFE hinzugefügt werden:

• Accept-Language
• User-Agent
• IP-Adresse

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

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

Im Folgenden sehen Sie ein Beispiel dafür, 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);
})

Das folgende Beispiel zeigt, 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)
  });
})

Serverseitig orchestrierte Auktion mit mehreren Verkäufern

Wenn Sie ein Verkäufer der obersten Ebene sind, der eine servergesteuerte Mehrfachverkäufer-Auktion durchführt, wird der Aufruf GetComponentAuctionCiphertexts vor dem Aufruf SelectAd an SFE gesendet. Die Antwort enthält die neu verschlüsselten Auktionsnutzlasten der Komponenten, die an die Anzeigendienste des Komponentenverkäufers gesendet werden. Die zurückgegebenen Ergebnisse der B&A-Anzeigenauktion für die Komponente werden an den SelectAd-Aufruf der SFE des Verkäufers auf oberster Ebene übergeben.

Weitere Informationen finden Sie in der Dokumentation zu mehreren Verkäufern auf GitHub.

Das Ergebnis der B&A-Auktion auf der Seite zurückgeben

Nach Abschluss der B&A-Auktion wird das verschlüsselte Auktionsergebnis an SAS zurückgegeben. SAS antwortet auf die einheitliche Auktionsanfrage 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 Antwortheader Ad-Auction-Result festgelegt. Dieser Hash wird vom Browser verwendet, um die Nutzlast zu überprüfen, wenn die Auktion im Client abgeschlossen wird.

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

import { createHash } from 'crypto';

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

Das Anhängen des Hash im Antwortheader und die Rückgabe 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 es sich um eine Antwort auf die Anfrage für die einheitliche Auktion handelt, die auf der Seite in Schritt 2 gestellt wurde, ist das kontextbezogene Auktionsergebnis ebenfalls in der Antwort enthalten.

Es können mehrere Hashes in 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 Verkäuferservercode der lokalen Test-App.

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

Die einheitliche Auktionsantwort, die von SAS zurückgegeben wird, enthält das verschlüsselte Ergebnis der B&A-Auktion. Diese Nutzlast wird an den Aufruf runAdAuction() übergeben, um die Auktion im Browser abzuschließen. Der requestId-Wert aus dem getInterestGroupAdAuctionData()-Aufruf in Schritt 1 wird ebenfalls in 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 mit nur einem Verkäufer

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

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

Das Feld requestId akzeptiert den requestId-Wert, 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

Für die Ausführung einer B&A-Auktion im gemischten Modus, an der sowohl On-Device- als auch B&A-Käufer teilnehmen können, wird die Auktionskonfiguration des runAdAuction()-Aufrufs so erstellt:

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

Um eine Auktion mit gemischten Modi zu ermöglichen, werden das Ergebnis der B&A-Auktion und die On-Device-Auktionskonfiguration in das Feld componentAuctions übergeben. Bei einer Auktion im gemischten Modus ist der seller-Wert sowohl für die Konfiguration auf oberster Ebene als auch für die Komponentenkonfigurationen gleich.

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

Auktion mit mehreren Verkäufern

Wenn Sie ein Verkäufer der obersten Ebene sind, der eine gerätegesteuerte Mehrfachkundenauktion durchführt, sendet jeder Komponentenverkäufer sein Ergebnis der B&A-Auktion und die Auktionskonfigurationen auf dem Gerät.

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

• Weitere Informationen finden Sie in den folgenden Erläuterungen auf GitHub:
  • B&A API in Chrome
  • Systemdesign für B&A
  • Auktion für B&A-Mehrfachkunden
  • Gemischte Auktion für B&A
• Weitere Informationen zur B&A-Architektur für das Web
• Codelab zum lokalen End-to-End-Testen

Hast du Fragen?

• Wenn Sie eine Frage zu Bidding and Auction Services haben, erstellen Sie ein Problem im B&A Services-Repository.