Generowanie raportów o wynikach aukcji interfejsu Protected Audience API

Generowanie raportów o aukcjach przy użyciu interfejsu Protected Audience API – przewodnik dla sprzedawców i kupujących.

Ten artykuł zawiera informacje techniczne na temat generowania raportów na temat wygranych aukcji w ramach Protected Audience API, wykorzystywane w obecnej wersji eksperymentalnego interfejsu Protected Audience API.

Przeczytaj przewodnik dla programistów, aby poznać cały cykl życia interfejsu Protected Audience API, a w objaśnieniu dotyczącym tego interfejsu znajdziesz szczegółowe informacje o raportowaniu na poziomie zdarzenia (tymczasowym).

Nie jesteś programistą? Więcej informacji znajdziesz w artykule Omówienie interfejsu Protected Audience API.

Co raportuje interfejs Protected Audience API?

Dostępne są 2 raporty interfejsu Protected Audience API:

  • Raport o sprzedawcy: zawiera informacje o sprzedawcy, który wygrał aukcję reklam.
  • Raport o kupujących: dostępny tylko dla kupujących, którzy wygrali aukcję.

Plan długoterminowy polega na umożliwieniu przeglądarce raportowania wyników aukcji dotyczących sprzedawcy i kupujących za pomocą interfejsów API Private Aggregation API. Jako tymczasowy mechanizm raportowania na poziomie zdarzenia kod implementujący reportResult() w przypadku sprzedawcy i reportWin() w przypadku zwycięskiego licytującego może wywoływać funkcję sendReportTo(). Bierze on jeden argument: ciąg reprezentujący adres URL pobrany po zakończeniu aukcji, który koduje zgłaszane informacje na poziomie zdarzenia.

Funkcje interfejsu API

Sprzedawca: reportResult()

Kod JavaScript sprzedawcy w dyrektywie decisionLogicUrl (który zawiera też scoreAd()) może zawierać funkcję reportResult(), która służy do raportowania wyniku aukcji.

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

Argumenty przekazywane do tej funkcji to:

auctionConfig

Obiekt konfiguracji aukcji został przekazany do navigator.runAdAuction().

browserSignals

Obiekt utworzony przez przeglądarkę i dostarczający informacje o aukcji. Na przykład:

  {
    'topWindowHostname': 'publisher.example',
    'interestGroupOwner': 'https://dsp.example',
    'renderUrl': 'https://cdn.example/url-of-winning-creative.wbn',
    'bid': <bidValue>,
    'desirability': <winningAdScore>
  }

Wartość zwracana tej funkcji jest używana jako argument sellerSignals dla funkcji reportWin() zwycięskiego licytującego.

Kupujący: reportWin()

Kod JavaScript zwycięskiego licytującego (zawierający również generateBid()) może zawierać funkcję reportWin() do raportowania wyniku aukcji.

reportWin(auctionSignals, perBuyerSignals, sellerSignals, browserSignals) {
  ...
}

Argumenty przekazywane do tej funkcji to:

auctionSignals i perBuyerSignals

Te same wartości przekazywane do generateBid() w przypadku zwycięskiego licytującego.

sellerSignals

Zwrócona wartość reportResult(), co umożliwia sprzedawcy przekazanie informacji kupującemu.

browserSignals

Obiekt utworzony przez przeglądarkę i dostarczający informacje o aukcji. Na przykład:

{
  'topWindowHostname': 'publisher.example',
  'seller': 'https://ssp.example',
  'interestGroupOwner': 'https://dsp.example',
  'interestGroupName': 'custom-bikes',
  'renderUrl': 'https://cdn.example/winning-creative.wbn',
  'bid': <bidValue>
}

Tymczasowa implementacja raportów

W Chrome są tymczasowo dostępne 2 metody raportowania aukcji:

  • forDebuggingOnly.reportAdAuctionLoss()
  • forDebuggingOnly.reportAdAuctionWin()

Każda z tych metod przyjmuje jeden argument: adres URL do pobrania po zakończeniu aukcji. Można je wywoływać wielokrotnie za pomocą różnych argumentów w adresie URL (zarówno w scoreAd(), jak i w generateBid()).

Chrome wysyła raporty o utracie/wygranych podczas debugowania dopiero po zakończeniu aukcji. Jeśli aukcja zostanie anulowana (np. z powodu nowej nawigacji), nie zostaną wygenerowane żadne raporty.

Te metody są domyślnie dostępne w Chrome, gdy włączona jest zasada chrome://flags/#privacy-sandbox-ads-apis. Jeśli jednak używasz Chrome z flagami wiersza poleceń, które włączają Protected Audience API, musisz jednoznacznie włączyć te metody, dodając flagę BiddingAndScoringDebugReportingAPI. Jeśli flaga nie jest włączona, metody nadal będą dostępne, ale nie będą podejmować żadnych działań.

Wszystkie materiały referencyjne interfejsu Protected Audience API

Dostępne są przewodniki po interfejsach API:

Wyjaśnienie interfejsu Protected Audience API zawiera też szczegółowe informacje o obsłudze i ograniczeniach funkcji.

Co dalej?

Chcemy wspólnie z Tobą rozmawiać, aby mieć pewność, że stworzyliśmy interfejs API dla wszystkich użytkowników.

Omów interfejs API

Podobnie jak inne interfejsy API Piaskownicy prywatności, ten interfejs API jest udokumentowany i omawiany publicznie.

Eksperymentuj z interfejsem API

Możesz eksperymentować i uczestniczyć w rozmowach na temat interfejsu Protected Audience API.