Licytowanie w aukcji w celu zakupu boksu reklamowego

Jako nabywca reklam (DSP i reklamodawcy) możesz wziąć udział w aukcji reklam z Protected Audience API w witrynie wydawcy, aby kierować reklamę na grupę zainteresowań określoną przez siebie w witrynie reklamodawcy. Dzięki udziałowi w aukcji z Protected Audience API możesz docierać do zidentyfikowanych klientów w innych witrynach w sposób zapewniający ochronę prywatności.

W aukcji z Protected Audience API podajesz reguły generowania stawki, a przeglądarka oblicza ją według tej logiki. W przeciwieństwie do innych architektur aukcji, w których stawki są podawane bezpośrednio, a nie tylko logicznie,

Logikę generowania stawek podajesz w funkcji JavaScript generateBid(), a plik jest hostowany na Twoim serwerze. Gdy dodajesz użytkownika do grupy zainteresowań, lokalizacja tego pliku jest przekazywana do konfiguracji grupy zainteresowań jako biddingLogicUrl.

Podczas aukcji przeglądarka pobiera Twoją logikę ustalania stawek określoną w polu biddingLogicUrl i wykonuje funkcję generateBid() dla każdej grupy zainteresowań w bezpiecznym, izolowanym środowisku, które ma ograniczoną komunikację z kontekstem zewnętrznym. Po wykonaniu funkcji generateBid() przeglądarka przekazuje do funkcji sygnały jako argumenty. Sygnały te zawierają różne informacje z różnych źródeł, m.in. dane własne wydawcy, sprzedawcy czy dane w czasie rzeczywistym. Na podstawie tych sygnałów możesz obliczyć stawkę, a wartość jest zwracana z wywołania generateBid(). Po przesłaniu ofert przeglądarka sprawdza każdą z nich zgodnie z logiką punktową sprzedawcy, aby obliczyć wynik atrakcyjności sprzedawcy.

Uwaga: w przypadku egzekwowania k-anonimowości funkcja generateBid będzie wywoływana po raz drugi, jeśli stawka z pierwszego wywołania nie była k-anonimowa. Jeśli zostanie wywołana po raz drugi, lista reklam w argumencie interestGroup będzie zawierać tylko reklamy k-anonimowe.

generateBid()

Poniżej opisujemy argumenty funkcji generateBid() i strukturę stawki zwracanej przez funkcję:

generateBid(interestGroup, auctionSignals, perBuyerSignals,
    trustedBiddingSignals, browserSignals, directFromSellerSignals) {
  return {
    ad: adObject,
    adCost: optionalAdCost,
    bid: bidValue,
    bidCurrency: 'USD',
    render: {
      url: renderURL,
      width: renderWidth,
      height: renderHeight
    },
    adComponents: [
      {url: adComponent1, width: componentWidth1, height: componentHeight1},
      {url: adComponent2, width: componentWidth2, height: componentHeight2},
      // ...
    ],
    allowComponentAuction: false,
    modelingSignals: 123 // 0-4095 integer (12-bits)
  };
}

Argumenty

Funkcja generateBid() przyjmuje następujące argumenty:

Argument	Rola
interestGroup	Obiekt przekazany do nabywcy reklamy. Do grupy zainteresowań można dodać atrybut dailyUpdateUrl.
auctionSignals	Właściwość argumentu konfiguracji aukcji przekazanej przez sprzedawcę do metody navigator.runAdAuction(). Zapewnia ono informacje o kontekście strony (np. rozmiar reklamy i identyfikator wydawcy), typ aukcji (pierwsza lub druga cena) oraz inne metadane.
perBuyerSignals	Właściwość argumentu konfiguracji aukcji przekazanej przez sprzedawcę. Może to dostarczać sygnały kontekstowe z serwera kupującego na temat strony, jeśli sprzedawcą jest SSP, który przeprowadza wywołanie określania stawek w czasie rzeczywistym do serwerów kupującego i przeprowadza odpowiedź z powrotem, lub jeśli strona wydawcy kontaktuje się bezpośrednio z serwerem kupującego. W takim przypadku kupujący może sprawdzić podpis kryptograficzny tych sygnałów w usłudze generateBid() w celu ochrony przed nieuprawnionymi modyfikacjami.
trustedBiddingSignals	Obiekt, którego klucze to interfejs trustedBiddingSignalsKeys grupy zainteresowań, a jego wartości są zwracane w żądaniu trustedBiddingSignals.
browserSignals	Obiekt utworzony przez przeglądarkę, który może zawierać informacje o kontekście strony (np. element hostname bieżącej strony, który w innym wypadku sprzedawca mógł sfałszować) i dane o samej grupie zainteresowań (np. zapis o tym, kiedy grupa wcześniej wygrała aukcję, aby umożliwić ograniczenie liczby wyświetleń na urządzeniu).
directFromSellerSignals	Sygnały, które muszą pochodzić od konkretnego sprzedawcy, w przeciwieństwie do sygnałów auctionSignals i sellerSignals, które mogą pochodzić od dowolnego uczestnika, który jest obecny w kontekście miejsca, w którym jest realizowana usługa runAdAuction.

Sygnały przeglądarki

Obiekt browserSignals ma te właściwości:

{
  topWindowHostname: 'publisher.example',
  seller: 'https://ssp.example',
  topLevelSeller: 'https://www.top-level-ssp.com',
  requestedSize: {width: 100, height: 200},  /* if specified in auction config */
  joinCount: 3,
  recency: 3600000,
  bidCount: 17,
  prevWinsMs: [[timeDeltaMs1,ad1],[timeDeltaMs2,ad2],...],
  wasmHelper: ...
  dataVersion: 1,
  adComponentsLimit: 40
}

Właściwość	Opis
topWindowHostname	Nazwa hosta, na którym przeprowadzono wywołanie runAdAuction().
seller	Sprzedawca, do którego została przesłana stawka. W aukcji komponentów ta wartość jest sprzedawcą komponentu.
topLevelSeller	Sprzedawca najwyższego poziomu bierze udział w aukcji składowej i bierze udział tylko w tej aukcji.
requestedSize	Właściwość requestedSize zaleca rozmiar klatki w aukcji. Sprzedawca ustawia żądany rozmiar w konfiguracji aukcji, a wartość ta staje się dostępna dla licytujących w generateBid(). Licytujący, którzy biorą udział w aukcji, mogą wybrać inny rozmiar treści dla reklamy, a wynikowy rozmiar zostanie skalowany tak, by pasował do rozmiaru kontenera elementu.
joinCount	Pole joinCount podaje, ile razy to urządzenie dołączyło do tej grupy zainteresowań w ciągu ostatnich 30 dni, gdy grupa zainteresowań była w dalszym ciągu przechowywana (czyli nie ma żadnych luk w pamięci urządzenia na urządzeniu z powodu rezygnacji lub wygaśnięcia subskrypcji).
recency	Pole recency zawiera czas (w minutach) od momentu, gdy urządzenie dołączyło do grupy zainteresowań do teraz
bidCount	Liczba razy, gdy grupa zainteresowań przesłała stawkę.
prevWinsMs	Pole prevWinMs zawiera listę zwycięskich reklam danej grupy zainteresowań oraz podany w milisekundach czas, który upłynął od wygranej w przypadku danej grupy zainteresowań. Pamiętaj, że obiekt reklamy zawiera tylko pola renderURL i metadane.
wasmHelper	obiekt WebAssembly.Module na podstawie obiektu biddingWasmHelperURL grupy zainteresowań.
dataVersion	Wartość wersji danych z odpowiedzi usługi kluczy i wartości kupującego.
adComponentsLimit	Maksymalna liczba komponentów reklamy, które może zwrócić generateBid()

Obliczanie stawki

Aby obliczyć wartość stawki, kod w tabeli generateBid() może używać właściwości parametrów funkcji.

Na przykład:

function generateBid(interestGroup, auctionSignals, perBuyerSignals,
    trustedBiddingSignals, browserSignals) {
  return {
   //  ...
    bid: auctionSignals.is_above_the_fold ? perBuyerSignals.atf_value : perBuyerSignals.btf_value,
    // ...
  }
}

Zwracanie stawki

generateBid() zwraca obiekt o tych właściwościach:

Właściwość	Rola
ad	arbitralne metadane dotyczące reklamy, np. informacje, które sprzedawca może się spodziewać po uzyskaniu informacji o stawce lub kreacji reklamy; Sprzedawca wykorzystuje te informacje w procesie aukcji i decyzji.
adCost	Wartość liczbowa używana do przekazywania raportowania kosztu kliknięcia lub konwersji reklamodawcy z usługi generateBid do raportu reportWin. Dokładność tej liczby jest ograniczona do 8-bitowej mantysy i 8-bitowego wykładnika, przy czym zaokrąglanie odbywa się stochastycznie.
adComponents	Opcjonalna lista maksymalnie 20 komponentów reklam złożonych z wielu elementów pobranych z właściwości adComponents w argumencie grupy zainteresowań przekazanej do navigator.joinAdInterestGroup().
allowComponentAuction	Wartość logiczna wskazująca, czy stawki można użyć w aukcji komponentu. Domyślna wartość to „false” (fałsz). jeśli nie określono żadnej wartości.
bid	Stawka liczbowa, która weźmie udział w aukcji. Sprzedawca musi mieć możliwość porównywania stawek różnych kupujących, dlatego stawki muszą być podane w wybranej przez niego jednostce (np. „PLN za tysiąc”). Jeśli stawka wynosi zero lub jest ujemna, dana grupa zainteresowań w ogóle nie weźmie udziału w aukcji sprzedawcy. Przy użyciu tego mechanizmu kupujący może stosować dowolne reguły reklamodawcy określające, gdzie jego reklamy mogą się pojawiać lub nie.
bidCurrency	Waluta stawki używana do currency-checking.
render	Słownik opisujący kreację, która powinna zostać wyrenderowana, jeśli ta stawka wygra aukcję. Obejmuje to m.in.: url: adres URL kreacji. width: szerokość kreacji. Ten rozmiar zostanie dopasowany do deklaracji w danej grupie zainteresowań i zastąpione wszystkimi makrami rozmiaru reklamy znajdującymi się w adresie URL kreacji. Podczas wczytywania reklamy w ramce ogrodzonej jej wewnętrzna ramka (rozmiar widoczny dla reklamy) zostaje zablokowany height: wysokość kreacji. Zobacz bardziej szczegółowe informacje w języku: width.
modelingSignals	Liczba całkowita o wartości od 0 do 4095 (12 bitów) przekazywana do funkcji reportWin() z szumem, zgodnie ze schematem szumów i zasobników. Nieprawidłowe wartości, takie jak wartości ujemne, nieskończone i wartości NaN, będą ignorowane i nie zostaną przekazane. Przekazywane jest tylko 12 najniższych bitów. Kupujący może wykorzystać sygnały dostępne w funkcji generateBid(), w tym dane z własnych kupujących zebrane podczas tworzenia grupy zainteresowań w userBiddingSignals, aby uzyskać wartość, która jest przekazywana do funkcji raportowania wygranej kupującego, aby można było trenować modele ML.