Przeprowadzanie aukcji w przeglądarce z jednym sprzedawcą

W tym dokumencie znajdziesz ogólny opis przebiegu aukcji z wykorzystaniem danych z Protected Audience API w przypadku pojedynczego sprzedawcy, używanych w obecnej wersji interfejsu Protected Audience API. Aukcja z jednym sprzedawcą może być przeprowadzana w ramach bardziej złożonej aukcji z udziałem wielu sprzedawców. W takim przypadku aukcja z pojedynczym sprzedawcą jest nazywana „aukcją komponentów”, która może przekazywać kandydatów reklam na „aukcję najwyższego poziomu”, w której bierze udział wielu sprzedawców.

Przeczytaj przewodnik dla programistów, aby poznać cały cykl życia interfejsu Protected Audience API, i zapoznaj się z objaśnieniem interfejsu Protected Audience API, aby dowiedzieć się, jak sprzedawcy przeprowadzają aukcje na urządzeniu.

6 etapów aukcji reklam Protected Audience API

6 etapów aukcji reklam Protected Audience API
Ten diagram przedstawia każdy etap aukcji reklam w ramach Protected Audience API.
  1. Użytkownik odwiedza witrynę, która wyświetla reklamy.
  2. Kod sprzedawcy jest uruchamiany navigator.runAdAuction(). Określa, która przestrzeń reklamowa jest na sprzedaż i kto może licytować. Sprzedawcy muszą też uwzględnić skrypt, który przyznaje punkty każdej stawce, czyli scoreAd().
  3. Kod zaproszonego kupującego jest uruchamiany, aby wygenerować stawkę, adres URL odpowiedniej kreacji reklamy i inne dane. Skrypt ustalania stawek może wysyłać zapytania o dane w czasie rzeczywistym, takie jak pozostały budżet kampanii reklamowej, z usługi klucz-wartość kupującego.
  4. Kod sprzedawcy nadaje punkty każdej stawce i wybiera zwycięzcę. Ta logika wykorzystuje wartość stawki i inne dane zwracają oczekiwaną wartość stawki. Reklamy, które nie będą lepsze od zwycięskiej kontekstowej, są odrzucane. Sprzedawca może używać własnej usługi kluczy/wartości do obsługi danych w czasie rzeczywistym.
  5. Zwycięska reklama jest zwracana jako wartość nieprzezroczysta, która pojawia się w ramce otoczonej ramką. Ani sprzedawca, ani wydawca nie będą mogli zobaczyć tej wartości.
  6. Informacje o aukcji są przekazywane sprzedawcy i kupującym, którzy wygrają.

Aukcja może odbywać się, gdy użytkownik przejdzie na stronę, na której wyświetla się reklama. Aukcje mogą być prowadzone z wyprzedzeniem, aby kreacja była gotowa, gdy pojawia się boks reklamowy.

Sprzedawcy inicjują aukcję reklam, oceniają reklamy kandydujące za pomocą niestandardowej logiki dostępnej w ramach funkcji scoreAd() i odpowiadają za zgłaszanie wyników aukcji sobie oraz kupującemu, który wygra. Sprzedawcy mogą też egzekwować reguły wydawcy i filtrować reklamy pod kątem jakości za pomocą funkcji scoreAd().

Sprzedawca może powoływać się na:

  • wydawców treści, którzy samodzielnie hostują treść reklam w swoich witrynach;
  • platformy dostawców reklam (SSP), współpraca z wydawcami reklam i świadczenie innych usług;
  • skrypty innych firm umożliwiające wzięcie udziału w aukcjach reklam w imieniu wydawców.

Wymagania wstępne dotyczące prowadzenia aukcji

Aby przeprowadzić aukcję, sprzedawca potrzebuje 2 funkcji JavaScriptu:

  • scoreAd() – ocenę kandydata reklamy
  • reportResult() – samodzielnie zgłasza wyniki aukcji sprzedawcy;

Skrypty te muszą być udostępniane z jednego punktu końcowego należącego do sprzedawcy.

scoreAd()

Sprzedawca musi zdefiniować funkcję scoreAd() obsługiwaną z punktu końcowego, którego jest właścicielem. Punkt końcowy jest określony w konfiguracji aukcji jako decisionLogicUrl. Funkcja scoreAd() ma taki podpis:

scoreAd(
  adMetadata,
  bid,
  auctionConfig,
  trustedScoringSignals,
  browserSignals,
  directFromSellerSignals)

Parametry scoreAd():

  • adMetaData, czyli arbitralne metadane dotyczące kreacji dostarczone przez kupującego. Jest to zserializowany obiekt JSON, który sprzedawcy i kupujący muszą zdefiniować i uzgodnić strukturę.
  • bid, który jest wartością liczbową określającą stawkę.
  • auctionConfig, czyli konfiguracja aukcji używana do jej przeprowadzenia.
  • trustedScoringSignals, czyli sygnały odczytywane w czasie aukcji z serwera klucz-wartość sprzedawcy. Platforma użyje identyfikatora renderUrl reklamy kandydata jako klucza podczas tego wyszukiwania.
  • browserSignals, który jest obiektem utworzonym przez przeglądarkę i zawiera informacje dostępne dla przeglądarki oraz informacje, które skrypt aukcji sprzedawcy chce zweryfikować.
  • directFromSellerSignals to obiekt, który może zawierać te pola:** sellerSignals: taki jak auctionConfig.sellerSignals, ale przekazywany przy użyciu mechanizmu directFromSellerSignals. ** auctionSignals: jak auctionConfig.auctionSignals, ale przekazywany za pomocą mechanizmu directFromSellerSignals.

Oto przykład właściwości browserSignals. Wartość renderUrl reklamy kandydata jest dostępna na podstawie tych sygnałów:

{ 'topWindowHostname': 'www.example-publisher.com',
  'interestGroupOwner': 'https://www.example-buyer.com',
  'renderURL': 'https://cdn.com/render_url_of_bid',
  'renderSize': {width: 100, height: 200}, /* if specified in the bid */
  'adComponents': ['https://cdn.com/ad_component_of_bid',
                   'https://cdn.com/next_ad_component_of_bid',
                   ...],
  'biddingDurationMsec': 12,
  'bidCurrency': 'USD', /* bidCurrency returned by generateBid, or '???' if none */
  'dataVersion': 1, /* Data-Version value from the trusted scoring signals server's response */
}

reportResult()

Sprzedawca musi zdefiniować funkcję reportResult() obsługiwaną z punktu końcowego, którego jest właścicielem. Punkt końcowy jest określony w konfiguracji aukcji jako decisionLogicUrl. Funkcja reportResult() ma taki podpis:

reportResult(auctionConfig, browserSignals) {
  ...
  return signalsForWinner;
}

Parametry reportResult():

  • auctionConfig, czyli konfiguracja aukcji używana do jej przeprowadzenia.
  • browserSignals, który jest obiektem utworzonym przez przeglądarkę i zawiera informacje dostępne dla przeglądarki oraz informacje, które skrypt aukcji sprzedawcy chce zweryfikować. To ten sam obiekt przekazany do funkcji scoreAds().

reportResult() zwraca wartość signalsForWinner, czyli dowolny obiekt JSON przekazywany do funkcji raportowania zwycięskiego kupującego. Powinny one zawierać wszystkie istotne informacje o aukcji, które sprzedawca może podać w raportach.

Przeprowadzanie aukcji interfejsu Protected Audience API

Aby przeprowadzić aukcję, sprzedawca musi wykonać 4 główne kroki. Pamiętaj, że w tych krokach przyjęto, że sprzedawca ma skonfigurowany punkt końcowy, aby zwracać wymagany kod JavaScript, który został wcześniej wspomniany w tym przewodniku.

  1. Skonfiguruj aukcję. W tym kroku utworzysz obiekt auctionConfig. Dzięki temu sprzedawca może określić, którzy kupujący powinni uczestniczyć w aukcji, a także dostarczać sygnały, które mogą być istotne podczas generowania stawek lub oceny reklamy.
  2. Uruchom aukcję, wywołując navigator.runAdAuction() i przekazując konfigurację utworzoną w poprzednim kroku. To zainicjuje łańcucha kupujących, w których stawki są ustalane, a następnie oceniają. Efektem tego etapu jest reklama kandydująca, która może zostać wyrenderowana do wyświetlenia.
  3. Wyrenderuj zwycięską reklamę w obramowanej ramce lub elemencie iframe.
  4. Raportować wynik aukcji. Dostępna jest funkcja navigator.sendReportTo(), która rozpocznie raportowanie. Sprzedawca zawsze otrzymuje raport o wynikach aukcji. Raport ten otrzyma tylko kupujący, który wygrał aukcję. Spowoduje to użycie atrybutu reportResult() sprzedawcy opisanego wcześniej w tym przewodniku do raportowania na jego serwerze.