Integracja z B&A jako kupujący

Usługi określania stawek i usługi aukcyjne to zestaw usług dla kupujących i sprzedawców reklam, który działa w zaufanym środowisku wykonawczym (TEE), aby ułatwić przeprowadzanie aukcji Protected Audience (PA). Z tego przewodnika dla deweloperów dowiesz się, jak kupujący może zintegrować się z aukcją B&A PA w Chrome.

Omówienie

Aby wziąć udział w aukcji Protected Audience z użyciem usług B&A, kupujący aktualizuje grupę zainteresowań (GA), aby zoptymalizować ładunek danych pod kątem skrócenia czasu oczekiwania na wynik aukcji.

Kupujący musi wykonać te zadania związane z optymalizacją ładunku:

Grupa zainteresowań dla B&A

Oto przykład konfiguracji grupy zainteresowań w aukcji B&A PA z zaimplementowaną optymalizacją ładunku:

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

Różnice między konfiguracją grup odbiorców na podstawie zainteresowań w wersji B&A a konfiguracją grup odbiorców na podstawie zainteresowań na urządzeniu:

Pola B&A IG IG na urządzeniu Dołączone do danych aukcji B&A
auctionServerRequestFlags Używany Nieużywane Nie
userBiddingSignals Niezalecane Używany Nie, jeśli ustawiona jest flaga omit-user-bidding-signals
adRenderIdadsadComponents Używany Nieużywane Jeśli ustawiona jest flaga omit-ads, element adRenderId w elementach ads jest dostępny tylko w elementach browserSignals.prevWins ładunku. Parametr adRenderId zdefiniowany w pliku adComponents nie jest uwzględniany w ładunku.

Jeśli flaga omit-ads nie jest ustawiona, dostępna w plikach browserSignals.prevWins, interestGroup.adRenderIdsinterestGroup.adComponentRenderIds.

renderURL w ads i adComponents Używany Używany Nie
metadata w ads i adComponents Nieużywane Używany Nie
Identyfikatory w raportach w usłudze ads Używany Używany Nie
  • Pole auctionServerRequestFlags umożliwia ustawienie flag, które informują przeglądarkę o pomijaniu niektórych danych w danych licytacji B&A.
  • Wartość userBiddingSignals można zdefiniować w grupie zainteresowań, ale zalecamy pominięcie tych wartości za pomocą flagi omit-user-bidding-signals. Pomijane sygnały można przesyłać za pomocą usługi K/V.
  • Pole adRenderId jest ustawiane razem z powiązanym polem renderURL, ale tylko pole adRenderId będzie częścią ładunku aukcji B&A. Adres URL renderowania zwracany przez generateBid() później w czasie aukcji musi odpowiadać adresowi URL renderowania zdefiniowanemu w IG.
  • Identyfikatory raportowania są definiowane w interfejsie Google Ads, ale nie są uwzględniane w pliku danych aukcji B&A. Identyfikator raportowania zwrócony przez generateBid() później w czasie aukcji musi odpowiadać adresowi URL renderowania określonemu w IG.
  • Identyfikatory ad.metadata i raportowania nie są uwzględniane w pliku danych aukcji B&A. Zamiast tego są dostępne dzięki korzystaniu z usługi zaufanego klucza/wartości.

Pamiętaj, że adresy renderURL i identyfikatory raportowania w funkcji ads są nadal zdefiniowane w konfiguracji grupy zainteresowań, ale nie są uwzględniane w danych żądania aukcji, ponieważ przeglądarka sprawdza, czy adres URL renderowania i identyfikatory raportowania zwracane przez funkcję generateBid() usługi ustalania stawek są zgodne z wartościami zdefiniowanymi w grupie zainteresowań.

joinAdInterestGroup() zadanie

W przypadku spotkania joinAdInterestGroup() należy wykonać te czynności.

Ustawianie flag żądania serwera

Pole auctionServerRequestFlags w konfiguracji joinAdInterestGroup() akceptuje te flagi:

Flaga Opis
omit-user-bidding-signals Flaga omit-user-bidding-signals pomija obiekt userBiddingSignals w pliku danych aukcji.

Jeśli flaga nie jest ustawiona, wartość userBiddingSignals zdefiniowana w grupie zainteresowań będzie dostępna w elementach generateBid() usługi określania stawek.

omit-ads Flaga omit-ads informuje przeglądarkę, aby pomijała obiekty adsadComponents w ładunku aukcji.

Usługa adRenderId będzie dostępna w usłudze prevWins w koncie browserSignals.

Jeśli flaga nie jest ustawiona, pola adRenderIdsadComponentRenderIds w argumencie interestGroup funkcji generateBid() będą zawierać odpowiednie identyfikatory renderowania reklamy.

Zdecydowanie zalecamy, aby kupujący wybrali flagę omit-ads. W przyszłości przekazywanie identyfikatorów renderowania i identyfikatorów renderowania komponentów reklamy z klienta może zostać wycofane na rzecz dalszej optymalizacji danych.

Pomijane dane są przetwarzane przez udostępnienie odpowiednich informacji w trustedBiddingSignals. Flagi można używać osobno, nie muszą być używane razem.

Przykład użycia:

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

Ustawianie identyfikatorów renderowania reklam

Aby zmniejszyć rozmiar ładunku aukcji B&A, pomijamy obiekty adsadComponents grupy zainteresowań. W związku z tym te obiekty nie są dostępne w ramach funkcji generateBid() działającej w usłudze ustalania stawek.

Aby obsłużyć brakujące informacje o reklamach, kupujący zachowuje identyfikator (adRenderIdadComponentRenderId) powiązany z każdą reklamą w konfiguracji grupy zainteresowań. Identyfikator musi być ciągiem znaków DOM o długości nie większej niż 12 bajtów. Jeśli identyfikator jest zakodowany w formacie Base64, jego długość nie może przekraczać 12 bajtów.

Przykład grupy zainteresowań z identyfikatorami renderowania reklamy:

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

adRenderId powiązane z reklamami staną się dostępne w prevWins.browserSignalsgenerateBid().

Chociaż renderURL nie jest uwzględniony w ładunku żądania, zwrócony adres URL renderowania z generateBid() musi być zgodny z adresem URL renderowania zdefiniowanym w konfiguracji grupy zainteresowań. Firmy technologiczne zajmujące się reklamami mogą przesyłać metadane reklamy i inne informacje w ramach trustedBiddingSignals, aby podczas wykonywania generateBid() można było wygenerować adres URL renderowania reklamy i adres URL renderowania komponentu reklamy.

Ustawianie priorytetów grup zainteresowań

Chrome umożliwia kupującym ustalanie priorytetów grup zainteresowań. Jeśli zostanie osiągnięty limit rozmiaru danych dla kupującego ustawiony przez sprzedawcę, podczas generowania danych dla aukcji B&A dla sprzedawcy wartości priorytetów grup zainteresowań są używane do usuwania grup zainteresowań o niższym priorytecie dla pojedynczego kupującego. W przypadku grup zainteresowań między różnymi kupcami przeglądarka podejmuje decyzję na podstawie rozmiaru serializowanego ładunku. Domyślnie każdy kupujący ma przypisany ten sam rozmiar. Pamiętaj, że faktyczne ustalanie priorytetów odbywa się na serwerach B&A, a nie podczas generowania ładunku żądania.

Priorytet jest obliczany w momencie aukcji za pomocą wektorów priorytetów kupującego (priorityVector) i sygnałów priorytetów sprzedawcy (prioritySignals). Kupujący może zastąpić sygnały priorytetów sprzedawcy.

Właściwość Opis
Wektor priorytetów Kupujący podaje wektory jako wartość klucza priorityVector z usługi K/V.
Sygnały priorytetowe Sprzedawca dostarcza sygnały, ustawiając priority_signals konfiguracji aukcji
Zastąpienia sygnałów priorytetowych Kupujący podaje zastąpienie w polu priority_signals_overrides w elementach PerBuyerConfig w konfiguracji aukcji.

Podczas aukcji przeglądarka oblicza rzadki iloczyn punktowy kluczy dopasowujących w elementach priorityVectorprioritySignals, aby określić priorytet. Na diagramie poniżej priorytet jest obliczany na podstawie wartości (4 * 2) + (3 * -1), która jest zmniejszana do 8 + -3, więc priorytet tej grupy zainteresowań w momencie aukcji wynosi 5.

Każdy klucz w obiektach wektora priorytetów i sygnałów priorytetowych jest mnożony przez siebie, a potem wyniki są sumowane, aby obliczyć priorytet.
Rysunek 1.: Obliczanie priorytetu za pomocą wektorów kupującego i sygnałów sprzedawcy

Do ustalania priorytetów w sekcji Pytania i odpowiedzi można też używać dodatkowych sygnałów:

Sygnał Opis
deviceSignals.one Ta wartość zawsze wynosi 1 i jest przydatna do dodawania stałej do iloczynu skalarnego.
deviceSignals.ageInMinutes Wartość określa wiek grupy zainteresowań (czas od ostatniego dołączenia do grupy) w minutach jako liczbę całkowitą z zakresu 0–43 200.
deviceSignals.ageInMinutesMax60 Wartość ta jest taka sama jak sygnał ageInMinutes, ale nie przekracza 60. Jeśli grupa ma więcej niż 1 godzinę, zwracana jest wartość 60.
deviceSignals.ageInHoursMax24 Wartość ta określa wiek grupy zainteresowań w godzinach (maksymalnie 24 godziny). Jeśli grupa ma więcej niż 1 dzień, zwracana jest wartość 24.
deviceSignals.ageInDaysMax30 Ta wartość określa wiek grupy zainteresowań w dniach (maksymalnie 30 dni). Jeśli grupa ma więcej niż 30 dni, zwracana jest wartość 30.

Więcej informacji znajdziesz w artykule na GitHub.

Konfigurowanie zaufanych sygnałów ustalania stawek

Ponieważ niektóre dane zostaną pominięte w pliku danych aukcji B&A, możesz użyć usługi klucza/wartości, aby przesłać pomijane dane jako wiarygodne sygnały określania stawek do funkcji generateBid().

Usługa K/V może dostarczyć następujące pomijane dane:

  • userBiddingSignals jeśli kupujący używał produktu;
  • metadata powiązane z każdą reklamą
  • adRenderId powiązane z każdą reklamą
  • Identyfikator raportu
Pomięte dane z grupy zainteresowań mogą być wysyłane na serwer zbierania danych kupującego. Serwer kolekcji przesyła dane do usługi klucz-wartość, a później przeglądarka wczytuje te dane z usługi klucz-wartość.
Rysunek 2.: przykładowe ustawienie zaufanych sygnałów

Jednym z możliwych podejść jest uwzględnienie w kluczach sygnałów zaufanego określania stawek unikalnego identyfikatora, a następnie wysłanie powiązanych danych na serwer, aby można je było załadować do usługi klucz-wartość. Ostateczne wdrożenie zależy jednak od firmy technologicznej, a interfejs API nie narzuca żadnych wytycznych.

Ten przykład opisuje jedno z możliwych podejść:

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

W tym przykładzie zdefiniowano unikalny identyfikator dla IG, który staje się częścią klucza zaufanych sygnałów. Klucz do IG i powiązane z nim wartości są wysyłane na serwer, aby zostały załadowane do usługi kluczy/wartości. W późniejszym etapie aukcji przeglądarka pobiera zaufane sygnały i udostępnia je w funkcji generateBid() kupującego.

W razie potrzeby zwracanie sygnału dotyczącego aktualizacji grupy zainteresowań z K/V

Klucz updateIfOlderThanMs dla zaufanych sygnałów jest używany do aktualizowania grupy zainteresowań wcześniej niż w zwykłym interwale dobowym. Jeśli grupa zainteresowań nie została złączona ani zaktualizowana w czasie przekraczającym wartość zwracaną w milisekundach dla klucza updateIfOlderThanMs, zostanie zaktualizowana za pomocą mechanizmu updateURL. Pamiętaj, że Chrome nie będzie aktualizować grup zainteresowań częściej niż raz na 10 minut.

Jeśli aukcja B&A zwróci reklamę, która nie pasuje do żadnej z reklam zdefiniowanych w grupie zainteresowań przechowywanej w przeglądarce, przeglądarka nie przeprowadzi aukcji. Mechanizm updateIfOlderThanMs może się przydać, aby zapewnić zgodność przeglądarki i aukcji B&A co do zestawu reklam w grupie zainteresowań.

Aby dowiedzieć się więcej, przeczytaj ten artykuł.

generateBid() zadanie

W przypadku spotkania generateBid() należy wykonać te czynności.

Odczytywanie sygnałów z przeglądarki

Obiekt browserSignals przekazany do wywołania usługi B&A generateBid() ma postać:

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

W elementach browserSignals dostępne są te zmodyfikowane lub nowe właściwości:

Właściwość Opis
prevWins prevWins to tablica tuplaków czasu i reklamy. Czas to liczba sekund od ostatniego zwycięstwa powiązanej reklamy w ciągu ostatnich 30 dni.

Zamiast obiektu ad został użyty obiekt adRenderId.

wasmHelper Kompilowany obiekt kodu dostarczonego z biddingWasmHelperURL.
dataVersion Zaufany serwer może opcjonalnie dołączyć do odpowiedzi nagłówek Data-Version, który jest dostępny w pliku generateBid().

Aby dowiedzieć się więcej, przeczytaj informacje na ten temat na GitHubie.

Zwraca adres URL renderowania z generateBid()

Obiekt ads jest pomijany w danych aukcji B&A, dlatego URL renderowania zwracany przez generateBid() musi zostać ponownie utworzony. Sposób odtwarzania adresu URL renderowania zależy od implementacji, a zwrócony adres URL musi być zgodny z adresem URL renderowania zdefiniowanym w grupie zainteresowań.

Jednym z możliwych podejść jest zachowanie adresu URL podstawowego i wypełnianie szablonu informacjami z elementów interestGrouptrustedBiddingSignals.

W tym przykładzie definiujemy 4 reklamy na podstawie koloru i produktu:

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

Następnie wysyłamy ulubiony kolor użytkownika i informacje o produkcie, aby zostały załadowane do usługi klucz-wartość:

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

Później, gdy odbywa się aukcja, sygnały zaufanych stawek są dostępne w generateBid(). Można ich używać do odtwarzania adresu URL:

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

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

Zwraca identyfikatory raportowania z generateBid()

Identyfikatory raportowania nie są uwzględniane w pliku danych aukcji B&A, dlatego generateBid() otrzymuje je za pomocą sygnałów zaufanego określania stawek. Po ustaleniu, którego identyfikatora raportowania użyć, wybrany identyfikator raportowania zostanie zwrócony z elementu generateBid(). Zwrócone identyfikatory muszą być zgodne z identyfikatorami zdefiniowanymi w grupie zainteresowań.

W tym przykładzie wybrano reklamę 1, a jej powiązany identyfikator renderowania jest zwracany z generateBid():

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

Zwrócony identyfikator raportowania jest dostępny w okresie od reportWin() do buyerReportingSignals:

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

Jeśli zamiast buyerReportingId zwracana jest wartość generateBid(), w miejscu buyerReportingId w elementach buyerReportingSignals jest dostępna wartość interestGroupName.

Aby dowiedzieć się więcej, zapoznaj się z przewodnikiem dotyczącym identyfikatorów raportów.

Dalsze kroki

Dostępne są te zasoby

Więcej informacji

Masz pytania?