Integracja z B&A jako kupujący

Usługi określania stawek i aukcji to zestaw usług dla kupujących i sprzedających reklamy, które działają w zaufanym środowisku wykonawczym (TEE), aby ułatwić przeprowadzenie aukcji z użyciem Protected Audience (PA). Z tego przewodnika dla programistów dowiesz się, jak kupujący może zintegrować się z aukcją B&A PA w Chrome.

Przegląd

Aby wziąć udział w aukcji Protected Audience API z usługami B&A, kupujący aktualizuje grupę zainteresowań, aby zoptymalizować ładunek pod kątem mniejszego opóźnienia aukcji.

Kupujący wymaga wykonania tych zadań optymalizacji ładunku:

• joinAdInterestGroup() zadania
  • Ustawianie flag żądania serwera
  • Ustawianie identyfikatorów renderowania reklam
  • Ustawianie priorytetów grup zainteresowań
  • Konfigurowanie zaufanych sygnałów określania stawek
• generateBid() zadania
  • Odczytywanie sygnałów przeglądarki
  • Adres URL renderowania zwrotu
  • Identyfikator raportowania zwrotów

Grupa zainteresowań w przypadku B&A

Poniżej znajdziesz przykład konfiguracji grupy zainteresowań w przypadku aukcji B&A PA z zastosowaną 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 konfiguracjami grup zainteresowań w przypadku B&A i na urządzeniu:

• Pole auctionServerRequestFlags umożliwia ustawianie flag, które informują przeglądarkę, aby pominęła niektóre dane w ładunku aukcji B&A.
• Wartość userBiddingSignals można zdefiniować w grupie zainteresowań, ale zalecamy jej pominięcie za pomocą flagi omit-user-bidding-signals. Pominięte sygnały można dostarczyć za pomocą usługi K/V.
• Pole adRenderId jest ustawiane wraz z powiązanym polem renderURL, ale tylko pole adRenderId będzie częścią ładunku aukcji B&A. Adres URL renderowania zwrócony z generateBid() później, w trakcie aukcji, musi być zgodny z adresem URL renderowania zdefiniowanym w grupie zainteresowań.
• Identyfikatory raportowania są zdefiniowane w specyfikacji interfejsu B&A, ale nie są uwzględnione w ładunku aukcji B&A. Identyfikator raportowania zwrócony z funkcji generateBid() później, w trakcie aukcji, musi być zgodny z adresem URL renderowania zdefiniowanym w grupie zainteresowań.
• Identyfikatory ad.metadata i raportowania nie są uwzględniane w ładunku aukcji B&A. Zamiast tego dane te są udostępniane w ramach korzystania z usługi zaufanych par klucz-wartość.

Pamiętaj, że identyfikatory renderURL i raportowania w ads są nadal zdefiniowane w konfiguracji grupy zainteresowań, chociaż nie są uwzględniane w ładunku żądania aukcji, ponieważ przeglądarka sprawdza, czy adres URL renderowania i identyfikatory raportowania zwrócone z generateBid() funkcji usługi ustalania stawek pasują do wartości zdefiniowanych w grupie zainteresowań.

joinAdInterestGroup() zadania

W przypadku połączenia joinAdInterestGroup() należy wykonać te czynności.

Ustawianie flag żądania serwera

Pole auctionServerRequestFlags w konfiguracji joinAdInterestGroup() akceptuje te flagi:

Pominięte dane są przetwarzane przez udostępnianie odpowiednich informacji w trustedBiddingSignals. Flagi można stosować pojedynczo, 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, obiekty ads i adComponents grupy zainteresowań są pomijane, a w konsekwencji nie są dostępne w funkcji generateBid() działającej w usłudze ustalania stawek.

Aby poradzić sobie z brakiem informacji o reklamie, kupujący przechowuje identyfikator (adRenderId i adComponentRenderId) powiązany z każdą reklamą w konfiguracji grupy zainteresowań. Identyfikator musi być ciągiem DOMString o długości maksymalnie 12 bajtów. Jeśli identyfikator jest zakodowany w formacie Base64, jego długość musi wynosić maksymalnie 12 bajtów.

Przykładowa grupa zainteresowań z identyfikatorami renderowania reklam:

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 będą dostępne w usłudze prevWins.browserSignals w generateBid().

Chociaż w ładunku żądania nie ma parametru renderURL, zwrócony przez generateBid() adres URL renderowania musi być zgodny z adresem URL renderowania zdefiniowanym w konfiguracji grupy zainteresowań. Technologie reklamowe mogą odsyłać metadane reklamy i inne informacje w trustedBiddingSignals, dzięki czemu podczas wykonywania generateBid() można wygenerować adres URL renderowania reklamy i adres URL renderowania komponentu reklamy na potrzeby stawki.

Ustawianie priorytetów grup zainteresowań

Chrome umożliwia kupującym nadawanie priorytetów grupom zainteresowań. Jeśli zostanie osiągnięty limit rozmiaru ładunku dla poszczególnych kupujących określony przez sprzedawcę, do odrzucenia grup zainteresowań o niższym priorytecie w przypadku jednego kupującego podczas generowania ładunku aukcji B&A dla sprzedawcy używane są wartości priorytetu grup zainteresowań. Wybierając grupy zainteresowań spośród różnych kupujących, przeglądarka podejmuje decyzję na podstawie rozmiaru serializowanego ładunku. Domyślnie każdy kupujący ma taką samą wielkość. Pamiętaj, że rzeczywiste ustalanie priorytetów odbywa się na serwerach B&A, a nie podczas generowania ładunku żądania.

Priorytet jest obliczany w momencie aukcji na podstawie 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.

Podczas aukcji przeglądarka oblicza rzadki iloczyn skalarny pasujących kluczy w priorityVector i prioritySignals na potrzeby priorytetu. Na poniższym diagramie priorytet jest obliczany przez (4 * 2) + (3 * -1), co daje 8 + -3, więc priorytet tej grupy zainteresowań w momencie aukcji wynosi 5.

W przypadku B&A do ustalania priorytetów można też używać dodatkowych sygnałów:

Więcej informacji znajdziesz w wyjaśnieniu na GitHubie.

Konfigurowanie zaufanych sygnałów do określania stawek

Ponieważ niektóre dane zostaną pominięte w ładunku aukcji B&A, możesz użyć usługi klucz/wartość, aby dostarczyć pominięte dane jako zaufane sygnały do określania stawek do funkcji generateBid().

Usługa K/V może dostarczać te pominięte dane:

• userBiddingSignals jeśli jest używany przez kupującego.
• metadata powiązany z każdą reklamą.
• adRenderId powiązany z każdą reklamą.
• Identyfikator raportu

Jednym z możliwych rozwiązań jest umieszczenie unikalnego identyfikatora w kluczach sygnałów zaufanego określania stawek, a następnie wysłanie powiązanych danych na serwer, aby można je było załadować do usługi klucz/wartość. Jednak rzeczywista implementacja zależy od technologii reklamowej, a interfejs API nie jest normatywny.

Poniższy przykład opisuje jedno z możliwych rozwiązań:

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 dla grupy zainteresowań zdefiniowano unikalny identyfikator, który staje się częścią klucza zaufanych sygnałów. Klucz grupy zainteresowań i powiązane z nim wartości są wysyłane na Twój serwer, aby można je było załadować do usługi klucz/wartość. W późniejszym czasie podczas aukcji przeglądarka pobiera sygnały zaufane i udostępnia je w funkcji generateBid() kupującego.

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

updateIfOlderThanMs Klucz do sygnałów zaufanych jest używany do aktualizowania grupy zainteresowań wcześniej niż w przypadku zwykłego interwału dziennego. Jeśli grupa zainteresowań nie została dołączona ani zaktualizowana w okresie przekraczającym wartość w milisekundach zwróconą 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 zwycięską reklamę, która nie pasuje do żadnej z reklam zdefiniowanych w grupie zainteresowań przechowywanej w przeglądarce, przeglądarka zakończy aukcję niepowodzeniem. Mechanizm updateIfOlderThanMs może być przydatny w zapewnieniu, że przeglądarka i aukcja B&A są zgodne co do zestawu reklam w grupie zainteresowań.

Więcej informacji znajdziesz w tym wyjaśnieniu.

generateBid() zadania

W przypadku połączenia generateBid() należy wykonać te czynności.

Odczytywanie sygnałów przeglądarki

Obiekt browserSignals przekazywany do wywołania generateBid() B&A wygląda tak:

{
  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 browserSignals dostępne są te zmodyfikowane lub nowe właściwości:

Zwróć adres URL renderowania z generateBid()

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

Jednym z możliwych rozwiązań jest zachowanie podstawowego adresu URL i wypełnienie szablonu informacjami z pól interestGroup i trustedBiddingSignals.

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, które mają zostać 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 aukcja jest przeprowadzana, zaufane sygnały określania stawek stają się dostępne w generateBid(), a te informacje można wykorzystać do odtworzenia adresu URL:

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

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

Zwróć identyfikatory raportowania z generateBid()

Identyfikatory raportowania nie są uwzględniane w ładunku aukcji B&A, dlatego stają się dostępne dla generateBid() dzięki sygnałom licytowania zaufanego. Po ustaleniu, którego identyfikatora raportowania użyć, wybrany identyfikator raportowania jest zwracany z generateBid(). Zwrócone identyfikatory muszą być zgodne z identyfikatorami zdefiniowanymi w grupie zainteresowań.

W tym przykładzie wybrano reklamę 1, a powiązany z nią identyfikator renderowania został zwrócony z generateBid():

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

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

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

Jeśli funkcja generateBid() nie zwraca wartości buyerReportingId, wartość interestGroupName jest dostępna w buyerReportingSignals zamiast w buyerReportingId.

Więcej informacji znajdziesz w przewodniku po identyfikatorach raportowania.

Dalsze kroki

Dostępne są te zasoby:

Więcej informacji

• Dowiedz się więcej o konfiguracjach aukcji B&A w Chrome
• Przeprowadź eksperymenty z interfejsem Protected Audience API za pomocą platformy B&A, korzystając z ćwiczeń z programowania dotyczących kompleksowego testowania lokalnego.

Masz pytania?

• Jeśli masz pytanie dotyczące usług ustalania stawek i aukcji, zgłoś problem w repozytorium usług ustalania stawek i aukcji.