B&A als Käufer einbinden

Die 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 Protected Audience-Auktionen (PA) zu ermöglichen. In diesem Entwicklerhandbuch wird erläutert, wie ein Käufer eine B&A-PA-Auktion für Chrome einbinden kann.

Übersicht

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

Für die Optimierung der Nutzlast sind folgende Aufgaben erforderlich:

Interessengruppe für B&A

Im Folgenden finden Sie ein Beispiel für eine Interessengruppenkonfiguration für eine B&A-PA-Auktion mit 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 B&A- und On-Device-Konfigurationen für Interessengruppen sind:

Fields B&A IG On-Device-Intelligenz In der B&A-Auktionsnutzlast enthalten
auctionServerRequestFlags Gebraucht Nicht verwendet Nein
userBiddingSignals Nicht empfohlen Gebraucht Nein, wenn das Flag omit-user-bidding-signals festgelegt ist
adRenderId in ads und adComponents Gebraucht Nicht verwendet Wenn das Flag omit-ads gesetzt ist, ist adRenderId in ads nur in browserSignals.prevWins der Nutzlast verfügbar. adRenderId, definiert in adComponents, ist nicht in der Nutzlast enthalten.

Wenn das Flag omit-ads nicht festgelegt ist, ist die Funktion in browserSignals.prevWins, interestGroup.adRenderIds und interestGroup.adComponentRenderIds verfügbar.
renderURL in ads und adComponents Gebraucht Gebraucht Nein
metadata in ads und adComponents Nicht verwendet Gebraucht Nein
Berichts-IDs in ads Gebraucht Gebraucht Nein
  • Im Feld auctionServerRequestFlags können Sie Flags festlegen, die dem Browser mitteilen, einige Daten in der B&A-Auktionsnutzlast zu ignorieren.
  • Der Wert userBiddingSignals kann in der Interessengruppe definiert werden. Wir empfehlen jedoch, ihn mit dem Flag omit-user-bidding-signals zu entfernen. Die fehlenden Signale können über den K/V-Dienst bereitgestellt werden.
  • Das Feld adRenderId wird zusammen mit dem zugehörigen renderURL festgelegt. Nur adRenderId wird jedoch Teil der B&A-Auktionsnutzlast. Die Rendering-URL, die später während der Auktion von generateBid() zurückgegeben wird, muss mit der in der IG definierten Rendering-URL übereinstimmen.
  • Berichts-IDs sind in der B&A-Gebotsrichtlinie definiert, aber nicht in der B&A-Auktionsnutzlast enthalten. Die Berichts-ID, die später während der Auktion von generateBid() zurückgegeben wird, muss mit der in der IG definierten Render-URL übereinstimmen.
  • Die ad.metadata und die Berichts-IDs sind nicht in der B&A-Auktionsnutzlast enthalten. Stattdessen werden diese Daten über die Nutzung des Trusted Key/Value Service verfügbar.

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

joinAdInterestGroup() Aufgaben

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

Flags für Serveranfragen festlegen

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

Flag Beschreibung
omit-user-bidding-signals Mit dem Flag omit-user-bidding-signals wird das userBiddingSignals-Objekt in der Auktionsnutzlast weggelassen.

Wenn das Flag nicht gesetzt ist, wird der in der Interessengruppe definierte userBiddingSignals-Wert in generateBid() des Gebotsdienstes verfügbar.
omit-ads Das Flag omit-ads weist den Browser an, die Objekte ads und adComponents in der Auktionsnutzlast zu ignorieren.

Die adRenderId ist in der Property prevWins von browserSignals verfügbar.

Wenn das Flag nicht festgelegt ist, enthalten die Felder adRenderIds und adComponentRenderIds im Argument interestGroup von generateBid() die entsprechenden Anzeigen-Render-IDs.

Käufern wird dringend empfohlen, das Flag omit-ads zu verwenden. In Zukunft werden die Übergabe von Render-IDs und Anzeigenkomponenten-Render-IDs vom Client möglicherweise für eine weitere Nutzlastoptimierung eingestellt.

Die ausgelassenen Daten werden behandelt, indem relevante Informationen in trustedBiddingSignals verfügbar gemacht werden. 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 reduzieren, werden die ads- und adComponents-Objekte der Interessengruppe weggelassen. Diese Objekte sind dann nicht in der generateBid()-Funktion verfügbar, die im Bidding Service ausgeführt wird.

Um mit den fehlenden Anzeigeninformationen umzugehen, verwaltet der Käufer eine Kennung (adRenderId und adComponentRenderId), die mit jeder Anzeige in der Interessengruppenkonfiguration verknüpft ist. Die Kennung muss ein DOMString mit maximal 12 Byte sein. Wenn die Kennung Base64-codiert ist, darf sie maximal 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 mit den Anzeigen verknüpften adRenderId sind ab generateBid() in prevWins.browserSignals verfügbar.

Auch wenn die renderURL nicht in der Nutzlast der Anfrage enthalten ist, muss die zurückgegebene Rendering-URL von generateBid() mit der in der Interessengruppenkonfiguration definierten Rendering-URL übereinstimmen. Anbieter von Anzeigentechnologien können Anzeigenmetadaten und andere Informationen in trustedBiddingSignals zurücksenden, damit die Anzeigen- und Anzeigenkomponenten-Render-URLs 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 Limit für die Größe der Nutzlast pro Käufer erreicht wird, werden die Interessengruppen mit niedrigerer Priorität für einen einzelnen Käufer anhand der Prioritätswerte der Interessengruppe gelöscht, wenn die B&A-Auktionsnutzlast 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 jedem Käufer die gleiche Größe zugewiesen. Die tatsächliche Priorisierung erfolgt auf den B&A-Servern und nicht bei der Generierung der Anfragen-Nutzlast.

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

Attribut Beschreibung
Prioritätsvektor Der Käufer stellt die Vektoren als Wert des Schlüssels priorityVector aus dem K/V-Dienst bereit.
Prioritätssignale Der Verkäufer stellt die Signale bereit, indem er priority_signals der Auktionskonfiguration festlegt.
Überschreibungen von Prioritätssignalen Der Käufer gibt die Überschreibung im Feld priority_signals_overrides des PerBuyerConfig in der Auktionskonfiguration an.

Während der Auktion berechnet der Browser das spärliche 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, was zu 8 + -3 führt. Die Priorität dieser Interessengruppe zum Zeitpunkt der Auktion ist also 5.

Jeder Schlüssel im Prioritätsvektor und die Prioritätssignale werden miteinander multipliziert und dann werden die Ergebnisse addiert, um die Priorität zu berechnen.
Abbildung 1: Prioritätsberechnung anhand der Vektoren des Käufers und der Signale des Verkäufers

Für die Priorisierung in B&A stehen auch zusätzliche Signale zur Verfügung:

Signal Beschreibung
deviceSignals.one Der Wert ist immer 1 und kann verwendet werden, um der Skalarmultiplikation eine Konstante hinzuzufügen.
deviceSignals.ageInMinutes Der Wert gibt das Alter der Interessengruppe (die Zeit seit der letzten Teilnahme an der Interessengruppe) in Minuten als Ganzzahl zwischen 0 und 43.200 an.
deviceSignals.ageInMinutesMax60 Der Wert beschreibt dasselbe wie das ageInMinutes-Signal, ist aber auf 60 begrenzt. Wenn die Gruppe älter als eine Stunde ist, wird „60“ zurückgegeben.
deviceSignals.ageInHoursMax24 Der Wert gibt das Alter der Interessengruppe in Stunden an, maximal 24 Stunden. Wenn die Gruppe älter als einen Tag ist, wird „24“ zurückgegeben.
deviceSignals.ageInDaysMax30 Der Wert gibt das Alter der Interessengruppe in Tagen an, maximal 30 Tage. Wenn die Gruppe älter als 30 Tage ist, wird 30 zurückgegeben.

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

Signale für vertrauenswürdige Gebote einrichten

Da einige Daten aus der B&A-Auktionsnutzlast entfernt werden, können Sie mit dem Schlüssel/Wert-Dienst die fehlenden Daten als vertrauenswürdige Gebotssignale an die Funktion generateBid() übergeben.

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

  • userBiddingSignals, wenn vom Käufer verwendet
  • metadata, die jeder Anzeige zugeordnet ist
  • adRenderId, die jeder Anzeige zugeordnet ist
  • Berichts-ID
Die ausgelassenen Daten aus der Interessengruppe können an den Erhebungsserver des Käufers gesendet werden. Der Sammlungsserver sendet die Daten an den Schlüssel/Wert-Dienst und der Browser lädt diese Daten später aus dem Schlüssel/Wert-Dienst.
Abbildung 2: Beispiel für die Einrichtung vertrauenswürdiger Signale

Eine Möglichkeit besteht darin, eine eindeutige Kennung in die Schlüssel der vertrauenswürdigen 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 in der Verantwortung der Anbieter von Anzeigentechnologien und die API ist nicht verbindlich.

Im folgenden Beispiel wird ein möglicher Ansatz beschrieben:

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

In diesem Beispiel wird für eine IG eine eindeutige Kennung definiert, die Teil des Schlüssels für vertrauenswürdige Signale wird. Der Schlüssel für die IG 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

Mit dem updateIfOlderThanMs-Schlüssel für die vertrauenswürdigen Signale wird die Interessengruppe früher als im üblichen Tagesintervall aktualisiert. Wenn die Interessengruppe innerhalb eines Zeitraums, der den für den Schlüssel updateIfOlderThanMs zurückgegebenen Millisekundenwert überschreitet, nicht zusammengeführt oder aktualisiert wurde, wird sie mit dem updateURL-Mechanismus aktualisiert. Chrome aktualisiert Interessengruppen nicht häufiger als einmal alle 10 Minuten.

Wenn die B&A-Auktion eine Anzeigenauslieferung zurückgibt, die nicht mit einer der Anzeigen übereinstimmt, die in der im Browser gespeicherten Interessengruppe definiert sind, lehnt der Browser die Auktion ab. Der updateIfOlderThanMs-Mechanismus kann hilfreich sein, um sicherzustellen, dass der Browser und die B&A-Auktion sich über die Anzeigen in der Interessengruppe einigen.

Weitere Informationen finden Sie in diesem Hilfeartikel.

generateBid() Aufgaben

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

Browsersignale lesen

Das browserSignals-Objekt, das an den B&A generateBid()-Aufruf ü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:

Attribut Beschreibung
prevWins prevWins ist ein Array von Tupeln aus Zeit und Anzeige. Die Zeit gibt an, wie viele Sekunden seit dem letzten Gewinn der zugehörigen Anzeige in den letzten 30 Tagen vergangen sind.

Es wurde geändert, um das adRenderId-Objekt anstelle des ad-Objekts bereitzustellen.
wasmHelper Kompiliertes Objekt des Codes, der von biddingWasmHelperURL bereitgestellt wurde.
dataVersion Ein vertrauenswürdiger Server kann optional einen numerischen Data-Version-Antwortheader enthalten, der in generateBid() verfügbar wird.

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

Render-URL für Rückgabe 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 zu verwenden 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 und die Produktinformationen des Nutzers, die in den Schlüssel/Wert-Dienst geladen werden sollen:

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

Später, wenn die Auktion stattfindet, sind die Signale für vertrauenswürdige Gebote 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`
  }
}

Berichts-IDs für Rücksendungen von generateBid()

Da die Berichts-IDs nicht in der B&A-Auktionsnutzlast enthalten sind, wird die ID für generateBid() über vertrauenswürdige Gebotssignale verfügbar. Sobald die Identität für die Berichterstellung festgelegt 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 ID für die Berichterstellung ist in reportWin() bis buyerReportingSignals verfügbar:

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

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

Weitere Informationen finden Sie im Leitfaden zu Berichts-IDs.

Nächste Schritte

Die folgenden Ressourcen stehen Ihnen zur Verfügung

Weitere Informationen

Hast du Fragen?