B&A als Käufer einbinden

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 Entwicklerhandbuch wird beschrieben, wie ein Käufer eine Integration mit einer B&A PA-Auktion für Chrome vornehmen kann.

Übersicht

Um an einer Protected Audience-Auktion mit B&A Services teilzunehmen, aktualisiert der Käufer die Interessengruppe, um die Nutzlast für eine verbesserte Auktionslatenz zu optimieren.

Der Käufer verlangt die folgenden Aufgaben zur Nutzlastoptimierung:

• joinAdInterestGroup() Aufgaben
  • Flags für Serveranfragen festlegen
  • Anzeigen-Render-IDs festlegen
  • Prioritäten für Interessengruppen festlegen
  • Vertrauenswürdige Gebotssignale einrichten
• generateBid() Aufgaben
  • Browsersignale lesen
  • Rückgabe-Render-URL
  • ID für die Rückgabeberichterstellung

Interessengruppe für B&A

Im Folgenden finden Sie ein Beispiel für die Konfiguration einer Interessengruppe für eine B&A-PA-Auktion mit angewandter Nutzlastoptimierung:

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

Die Unterschiede zwischen den Konfigurationen für B&A und On-Device-Interessengruppen sind:

• Mit dem Feld auctionServerRequestFlags können Sie Flags festlegen, mit denen der Browser angewiesen wird, bestimmte Daten in der Nutzlast der B&A-Auktion wegzulassen.
• Der Wert userBiddingSignals kann in der Interessengruppe definiert werden. Es wird jedoch empfohlen, ihn mit dem Flag omit-user-bidding-signals wegzulassen. Die ausgelassenen Signale können über den K/V-Dienst bereitgestellt werden.
• Das Feld adRenderId wird zusammen mit dem zugehörigen renderURL festgelegt, aber nur adRenderId wird Teil der B&A-Auktionsnutzlast. Die Render-URL, die später während der Auktionszeit von generateBid() zurückgegeben wird, muss mit der in der IG definierten Render-URL übereinstimmen.
• Berichts-IDs werden in der B&A IG definiert, sind aber nicht in der B&A-Auktionsnutzlast enthalten. Die Berichts-ID, die später während der Auktionszeit von generateBid() zurückgegeben wird, muss mit der in der IG definierten Render-URL übereinstimmen.
• Die ad.metadata- und Berichts-IDs sind nicht in der B&A-Auktionsnutzlast enthalten. Stattdessen sind diese Daten durch die Nutzung des Trusted Key/Value Service verfügbar.

renderURLs und Reporting-IDs in ads sind weiterhin in der Konfiguration der Interessengruppe definiert. Sie werden jedoch nicht in die Nutzlast der Auktionsanfrage aufgenommen, da der Browser prüft, ob die von der generateBid()-Funktion des Bidding Service zurückgegebene Render-URL und die Reporting-IDs mit den in der Interessengruppe definierten Werten übereinstimmen.

joinAdInterestGroup() Aufgaben

Die folgenden Aufgaben müssen für den joinAdInterestGroup()-Aufruf ausgeführt werden.

Flags für Serveranfragen festlegen

Das Feld auctionServerRequestFlags der joinAdInterestGroup()-Konfiguration akzeptiert die folgenden Flags:

Die ausgelassenen Daten werden durch die Bereitstellung relevanter Informationen in trustedBiddingSignals behandelt. Die Flags können einzeln verwendet werden und müssen nicht zusammen verwendet werden.

Nutzungsbeispiel:

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

Anzeigen-Render-IDs festlegen

Um die Größe der B&A-Auktionsnutzlast zu verringern, werden die Objekte ads und adComponents der Interessengruppe ausgelassen. Diese Objekte sind daher nicht in der Funktion generateBid() verfügbar, die im Bidding Service ausgeführt wird.

Um die fehlenden Anzeigeninformationen zu verarbeiten, verwaltet der Käufer eine Kennung (adRenderId und adComponentRenderId), die jeder Anzeige in der Konfiguration der Interessengruppe zugeordnet ist. Der Bezeichner muss ein DOMString mit einer Länge von maximal 12 Byte sein. Wenn die Kennung Base64-codiert ist, darf sie höchstens 12 Byte lang sein.

Beispiel für eine Interessengruppe mit Anzeigen-Render-IDs:

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

Die adRenderId, die mit den Anzeigen verknüpft sind, sind in prevWins.browserSignals in generateBid() verfügbar.

Obwohl renderURL nicht in der Anfrage-Nutzlast enthalten ist, muss die zurückgegebene Render-URL von generateBid() mit der in der Konfiguration der Interessengruppe definierten Render-URL übereinstimmen. Ad-Tech-Unternehmen können Anzeigenmetadaten und andere Informationen in trustedBiddingSignals zurücksenden, damit die Anzeigen-Rendering-URL und die Rendering-URL für Anzeigenkomponenten für das Gebot während der Ausführung von generateBid() generiert werden können.

Prioritäten für Interessengruppen festlegen

In Chrome können Käufer Interessengruppen priorisieren. Wenn das vom Verkäufer festgelegte Nutzlastgrößenlimit pro Käufer erreicht ist, werden die Prioritätswerte der Interessengruppen verwendet, um die Interessengruppen mit niedrigerer Priorität für einen einzelnen Käufer zu entfernen, wenn die Nutzlast der B&A-Auktion für den Verkäufer generiert wird. Bei der Auswahl von Interessengruppen zwischen verschiedenen Käufern entscheidet der Browser anhand der Größe der serialisierten Nutzlast. Standardmäßig wird jeder Käufer gleich gewichtet. Die tatsächliche Priorisierung erfolgt auf den B&A-Servern und nicht beim Generieren der Anfrage-Payload.

Die Priorität wird zum Zeitpunkt der Auktion anhand der Prioritätsvektoren des Käufers (priorityVector) und der Prioritätssignale des Verkäufers (prioritySignals) berechnet. Der Käufer kann die Prioritätssignale des Verkäufers überschreiben.

Während der Auktion berechnet der Browser das dünnbesetzte Punktprodukt der übereinstimmenden Schlüssel in priorityVector und prioritySignals für die Priorität. Im folgenden Diagramm wird die Priorität mit (4 * 2) + (3 * -1) berechnet, die auf 8 + -3 reduziert wird. Die Priorität dieser Interessengruppe zum Zeitpunkt der Auktion ist also 5.

Für die Priorisierung in B&A sind auch zusätzliche Signale verfügbar:

Weitere Informationen

Vertrauenswürdige Gebotssignale einrichten

Da einige Daten aus der Nutzlast der B&A-Auktion ausgelassen werden, können Sie den Schlüssel/Wert-Dienst verwenden, um die ausgelassenen Daten als vertrauenswürdige Gebotssignale für die Funktion generateBid() bereitzustellen.

Die folgenden ausgelassenen Daten können vom K/V-Dienst bereitgestellt werden:

• userBiddingSignals, wenn der Käufer sie verwendet
• metadata für jede Anzeige
• adRenderId für jede Anzeige
• Berichts-ID

Eine Möglichkeit besteht darin, eine eindeutige Kennung in die Schlüssel für vertrauenswürdige Gebotssignale aufzunehmen und die zugehörigen Daten dann an Ihren Server zu senden, damit sie in den Schlüssel/Wert-Dienst geladen werden können. Die tatsächliche Implementierung liegt jedoch im Ermessen des Ad-Tech-Unternehmens und die API ist nicht vorschreibend.

Im Folgenden wird ein Ansatz beschrieben, der implementiert werden kann:

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

Im Beispiel wird eine eindeutige Kennung für eine IG definiert, die Teil des Schlüssels für vertrauenswürdige Signale wird. Der Schlüssel für die Interessengruppe und die zugehörigen Werte werden an Ihren Server gesendet, um in den Schlüssel/Wert-Dienst geladen zu werden. Später während der Auktion ruft der Browser die vertrauenswürdigen Signale ab und stellt sie in der generateBid()-Funktion des Käufers zur Verfügung.

Bei Bedarf Signal zur Aktualisierung der Interessengruppe aus K/V zurückgeben

Der updateIfOlderThanMs-Schlüssel für die vertrauenswürdigen Signale wird verwendet, um die Interessengruppe früher als im üblichen täglichen Intervall zu aktualisieren. Wenn die Interessengruppe seit einem Zeitraum, der den für den Schlüssel updateIfOlderThanMs zurückgegebenen Millisekundenwert überschreitet, nicht beigetreten oder aktualisiert wurde, wird die Interessengruppe mit dem updateURL-Mechanismus aktualisiert. Hinweis: Chrome aktualisiert Interessengruppen nicht häufiger als einmal alle 10 Minuten.

Wenn bei der B&A-Auktion eine Gewinneranzeige zurückgegeben wird, die nicht mit einer der Anzeigen übereinstimmt, die in der im Browser gespeicherten Interessengruppe definiert sind, schlägt die Auktion im Browser fehl. Der updateIfOlderThanMs-Mechanismus kann hilfreich sein, um sicherzustellen, dass der Browser und die B&A-Auktion sich auf die Menge der Anzeigen in der Interessengruppe einigen.

Weitere Informationen

generateBid() Aufgaben

Die folgenden Aufgaben müssen für den generateBid()-Aufruf ausgeführt werden.

Browsersignale lesen

Das browserSignals-Objekt, das an den B&A-Aufruf generateBid() übergeben wird, sieht so aus:

{
  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,
}

Die folgenden geänderten oder neuen Properties sind in browserSignals verfügbar:

Rückgabe der Render-URL von generateBid()

Da das ads-Objekt in der B&A-Auktionsnutzlast fehlt, muss die von generateBid() zurückgegebene Render-URL neu erstellt werden. Wie die Render-URL neu erstellt wird, hängt von Ihrer Implementierung ab. Die zurückgegebene URL muss mit der in der Interessengruppe definierten Render-URL übereinstimmen.

Eine Möglichkeit wäre, eine Basis-URL beizubehalten und die Vorlage mit den Informationen aus interestGroup und trustedBiddingSignals zu füllen.

In diesem Beispiel definieren wir vier Anzeigen basierend auf Farbe und Produkt:

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

Anschließend senden wir die Lieblingsfarbe des Nutzers und die Produktinformationen, die in den Key/Value Service geladen werden sollen:

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

Wenn die Auktion später ausgeführt wird, sind die vertrauenswürdigen Gebotssignale in generateBid() verfügbar. Anhand dieser Informationen kann die URL rekonstruiert werden:

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

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

Reporting-IDs von generateBid() zurückgeben

Da die Berichts-IDs nicht in der B&A-Auktionsnutzlast enthalten sind, sind sie für generateBid() über vertrauenswürdige Gebotssignale verfügbar. Sobald die zu verwendende Identität für die Berichterstellung ermittelt wurde, wird sie von generateBid() zurückgegeben. Die zurückgegebenen IDs müssen mit den in der Interessengruppe definierten IDs übereinstimmen.

In diesem Beispiel wird Anzeige 1 ausgewählt und die zugehörige Render-ID wird von generateBid() zurückgegeben:

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

Die zurückgegebene Berichts-ID ist in reportWin() über buyerReportingSignals verfügbar:

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

Wenn buyerReportingId nicht von generateBid() zurückgegeben wird, ist der Wert interestGroupName anstelle von buyerReportingId in buyerReportingSignals verfügbar.

Weitere Informationen

Nächste Schritte

Die folgenden Ressourcen stehen Ihnen zur Verfügung:

Weitere Informationen

• Weitere Informationen zu B&A-Auktionskonfigurationen in Chrome
• 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.