Prowadzenie aukcji w przeglądarce z jednym sprzedawcą

W tym dokumencie znajdziesz ogólny opis przeprowadzania aukcji z użyciem danych Protected Audience dla jednego sprzedawcy, tak jak to ma miejsce 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 jednym sprzedawcą jest nazywana „aukcją komponentową”, która może dostarczać kandydatów do wyświetlenia reklamy na „aukcji najwyższego poziomu”, w której uczestniczy wielu sprzedawców.

Pełny cykl życia interfejsu Protected Audience API znajdziesz w przewodniku dla programistów, a szczegółowe omówienie sposobu przeprowadzania aukcji na urządzeniu przez sprzedawców znajdziesz w wyjaśnieniu dotyczącym interfejsu Protected Audience API.

6 etapów aukcji reklamowej z użyciem Protected Audience API

1. Użytkownik odwiedza witrynę, w której wyświetlają się reklamy.
2. Kod sprzedawcy jest wykonywanynavigator.runAdAuction(). Określa, która przestrzeń reklamowa jest na sprzedaż i kto może składać oferty. Sprzedawcy muszą też dodać skrypt, który ocenia każdą stawkę, scoreAd().
3. Kod zaproszonego kupującego jest wykonywany w celu wygenerowania stawki, adresu URL odpowiedniego kreacji reklamy i innych danych. Skrypt określania stawek może wysyłać zapytania o dane w czasie rzeczywistym, takie jak pozostały budżet kampanii reklamowej, do usługi klucz/wartość kupującego.
4. Kod sprzedawcy ocenia każdą stawkę i wybiera zwycięzcę. Ta logika wykorzystuje wartość stawki i inne dane, aby określić, jak pożądana jest stawka. Reklamy, które nie mogą pokonać zwycięzcy kontekstowego, są odrzucane. Sprzedawca może używać własnej usługi klucz/wartość do przesyłania danych w czasie rzeczywistym.
5. Zwycięska reklama jest zwracana jako nieprzezroczysta wartość, która wyświetla się w ramce ograniczonej. Ani sprzedawca, ani wydawca nie będą mogli wyświetlić tej wartości.
6. Informacja o aukcji jest przekazywana sprzedawcy i kupującym, którzy wygrali.

Aukcja może się odbyć, gdy użytkownik przejdzie na stronę, na której wyświetla się reklama. Aukcje mogą być przeprowadzane z wyprzedzeniem, aby kreacja reklamowa była gotowa, gdy pojawi się miejsce na reklamę.

Sprzedawcy inicjują aukcję reklam, oceniają kandydatów do wyświetlenia reklam za pomocą niestandardowej logiki dostarczonej jako funkcja scoreAd() i są odpowiedzialni za raportowanie wyników aukcji sobie oraz zwycięskiemu kupującemu. Sprzedawcy mogą też egzekwować reguły wydawcy i filtrować reklamy pod kątem jakości za pomocą funkcji scoreAd().

Sprzedawca może odnosić się do:

• wydawcy treści, którzy działają we własnym imieniu, aby hostować treści reklamowe w swojej witrynie;
• Platformy dostawców reklam (SSP), które współpracują z wydawcą reklam i świadczą inne usługi.
• Skrypty firm zewnętrznych działające w imieniu wydawców, aby umożliwić im udział w aukcjach reklam.

Wymagania wstępne dotyczące przeprowadzenia aukcji

Aby przeprowadzić aukcję, sprzedawca musi zdefiniować 2 funkcje JavaScript:

• scoreAd(), który ocenia proponowaną reklamę.
• reportResult(), który przekazuje sprzedawcy wynik aukcji.

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

scoreAd()

Sprzedawca musi zdefiniować scoreAd() funkcję, która jest obsługiwana z należącego do niego punktu końcowego. Punkt końcowy jest określony w konfiguracji aukcji jako decisionLogicUrl. Funkcja scoreAd() ma ten podpis:

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

Parametry scoreAd() to:

• adMetaData, czyli dowolne metadane dotyczące kreacji reklamy, które są podawane przez kupującego. Jest to obiekt, który można serializować w formacie JSON. Sprzedawcy i kupujący muszą zdefiniować jego strukturę i uzgodnić ją.
• bid, czyli wartość liczbowa reprezentująca stawkę.
• auctionConfig, czyli konfiguracja aukcji używana do jej przeprowadzania.
• trustedScoringSignals, czyli sygnały odczytywane w momencie aukcji z serwera klucz/wartość sprzedawcy. Platforma użyje renderUrl reklamy kandydującej jako klucza do tego wyszukiwania.
• browserSignals, czyli obiekt utworzony przez przeglądarkę, który zawiera informacje znane przeglądarce i które skrypt aukcyjny sprzedawcy może chcieć zweryfikować.
• directFromSellerSignals to obiekt, który może zawierać te pola: ** sellerSignals: podobne do auctionConfig.sellerSignals, ale przekazywane za pomocą mechanizmu directFromSellerSignals. ** auctionSignals: podobnie jak auctionConfig.auctionSignals, ale przekazywane za pomocą mechanizmu directFromSellerSignals.

Poniżej znajdziesz przykład właściwości browserSignals. Pamiętaj, że renderUrl reklamy kandydującej jest dostępny w tych sygnałach:

{ '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ć reportResult() funkcję, która jest obsługiwana z należącego do niego punktu końcowego. Punkt końcowy jest określony w konfiguracji aukcji jako decisionLogicUrl. Funkcja reportResult() ma tę sygnaturę:

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

Parametry reportResult() to:

• auctionConfig, czyli konfiguracja aukcji używana do jej przeprowadzania.
• browserSignals, czyli obiekt utworzony przez przeglądarkę, który zawiera informacje znane przeglądarce i które skrypt aukcyjny sprzedawcy może chcieć zweryfikować. Jest to ten sam obiekt, który jest przekazywany do funkcji scoreAds().

reportResult() zwraca signalsForWinner, czyli dowolny obiekt JSON, który jest przekazywany do funkcji raportowania zwycięskiego kupującego. Powinny one zawierać wszelkie istotne informacje o aukcji, które sprzedawca może przekazać kupującemu na potrzeby raportowania.

Przeprowadzanie aukcji z użyciem Protected Audience API

Aby przeprowadzić aukcję, sprzedawca musi wykonać 4 główne kroki. Pamiętaj, że te kroki zakładają, że sprzedawca ma skonfigurowany punkt końcowy, który zwraca wymagany kod JavaScript wspomniany wcześniej w tym przewodniku.

1. Skonfiguruj aukcję. Ten krok obejmuje utworzenie obiektu auctionConfig. Umożliwia to sprzedawcy określenie, którzy kupujący powinni brać udział w aukcji, a także przekazywanie sygnałów, które mogą być istotne podczas generowania stawek lub oceniania reklam.
2. Przeprowadź aukcję, wywołując funkcję navigator.runAdAuction() i przekazując konfigurację utworzoną w poprzednim kroku. Rozpoczyna to proces generowania stawek przez kupujących, a następnie ich oceniania. Wynikiem tego kroku jest kandydat na reklamę, który może zostać wyrenderowany w celu wyświetlenia reklamy.
3. Wyświetl zwycięską reklamę w ramce ograniczonej lub ramce iframe.
4. raportować wynik aukcji. Istnieje funkcja navigator.sendReportTo(), która rozpocznie raportowanie. Sprzedawca zawsze otrzyma raport z wynikami aukcji. Raport otrzyma tylko kupujący, który wygrał aukcję. W tym celu używa reportResult() opisanych wcześniej w tym przewodniku, aby wysyłać raporty na serwer sprzedawcy.