Generowanie raportów o wynikach aukcji interfejsu Protected Audience API

Przewodnik dla sprzedawców i kupujących dotyczący generowania raportów o aukcjach z użyciem Protected Audience API.

Ten artykuł zawiera informacje techniczne na temat generowania raportów o wygranych aukcjach w interfejsie Protected Audience API, które są używane w obecnej wersji eksperymentalnego interfejsu Protected Audience API.

Pełny cykl życia interfejsu Protected Audience API znajdziesz w przewodniku dla deweloperów. Szczegółowe omówienie raportowania na poziomie zdarzenia (tymczasowego) znajdziesz w wyjaśnieniu dotyczącym interfejsu Protected Audience API.

Nie jesteś deweloperem? Zapoznaj się z przeglądem interfejsu Protected Audience API.

Jakie dane są raportowane przez interfejs Protected Audience API?

Dostępne są 2 raporty dotyczące Protected Audience API:

  • Raport dla sprzedawcy: informuje sprzedawcę o zwycięzcy aukcji reklam.
  • Raport dla kupującego: dostępny tylko dla kupujących, którzy wygrali aukcję. Informuje o tym, że wygrali aukcję.

Długoterminowy plan zakłada umożliwienie przeglądarce raportowania wyników aukcji sprzedawcy i kupującym za pomocą interfejsów Private Aggregation API. Jako tymczasowy mechanizm raportowania na poziomie zdarzeń kod implementujący reportResult() w przypadku sprzedawcy i reportWin() w przypadku zwycięskiego oferenta może wywoływać funkcję sendReportTo(). Przyjmuje 1 argument: ciąg znaków reprezentujący adres URL, który jest pobierany po zakończeniu aukcji i który koduje informacje o zdarzeniu do raportowania.

Funkcje interfejsu API

Sprzedawca: reportResult()

Kod JavaScript sprzedawcy podany w decisionLogicUrl (który też udostępnia scoreAd()) może zawierać funkcję reportResult(), która raportuje wynik aukcji.

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

Argumenty przekazane do tej funkcji to:

auctionConfig

Obiekt konfiguracji aukcji przekazany do funkcji navigator.runAdAuction().

browserSignals

Obiekt utworzony przez przeglądarkę, który zawiera 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 przez tę funkcję jest używana jako argument sellerSignals funkcji reportWin() zwycięskiego oferenta.

Kupujący: reportWin()

Kod JavaScript zwycięskiego oferenta (który również dostarczył wartość generateBid()) może zawierać funkcję reportWin() do raportowania wyniku aukcji.

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

Argumenty przekazane do tej funkcji to:

auctionSignals i perBuyerSignals

Te same wartości przekazywane do parametru generateBid() w przypadku zwycięskiego reklamodawcy.

sellerSignals

Wartość zwracana przez reportResult(), która umożliwia sprzedawcy przekazywanie informacji kupującemu.

browserSignals

Obiekt utworzony przez przeglądarkę, który zawiera 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>
}

Tymczasowe wdrożenie raportowania

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

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

Każda z tych metod przyjmuje jeden argument: adres URL, który ma zostać pobrany po zakończeniu aukcji. Można je wywoływać wielokrotnie w przypadku scoreAd() i generateBid() z różnymi argumentami adresu URL.

Chrome wysyła raporty o utraconych lub wygranych aukcjach w trybie debugowania tylko wtedy, gdy aukcja zostanie zakończona. Jeśli aukcja zostanie anulowana (np. z powodu nowej nawigacji), nie będą generowane żadne raporty.

Te metody są domyślnie dostępne w Chrome, gdy włączysz wszystkie interfejsy Ad Privacy API w sekcji chrome://settings/adPrivacy. Jeśli uruchamiasz Chrome z flagami wiersza poleceń, aby włączyć interfejs Protected Audience API, musisz wyraźnie włączyć metody, dodając flagę BiddingAndScoringDebugReportingAPI. Jeśli flaga nie jest włączona, metody będą nadal dostępne, ale nie będą wykonywać żadnych działań.

Wszystkie odwołania do 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.