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
- Użytkownik odwiedza witrynę, która wyświetla reklamy.
- 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, czyliscoreAd()
. - 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.
- 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.
- 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.
- 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 reklamyreportResult()
– 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 identyfikatorarenderUrl
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 jakauctionConfig.sellerSignals
, ale przekazywany przy użyciu mechanizmudirectFromSellerSignals
. **auctionSignals
: jakauctionConfig.auctionSignals
, ale przekazywany za pomocą mechanizmudirectFromSellerSignals
.
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 funkcjiscoreAds()
.
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.
- 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. - 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. - Wyrenderuj zwycięską reklamę w obramowanej ramce lub elemencie iframe.
- 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 atrybutureportResult()
sprzedawcy opisanego wcześniej w tym przewodniku do raportowania na jego serwerze.