Generowanie raportów o wynikach aukcji interfejsu Protected Audience API

Przewodnik dla sprzedawców i kupujących dotyczące generowania raportów aukcji interfejsu Protected Audience API.

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

Przeczytaj przewodnik dla programistów, aby poznać pełny cykl życia interfejsu Protected Audience API, i zapoznaj się z wyjaśnieniem na temat tego interfejsu, aby szczegółowo poznać raportowanie na poziomie zdarzenia (tymczasowe).

Nie jesteś programistą? Zapoznaj się z omówieniem interfejsu Protected Audience API.

Co zawiera raport Protected Audience API?

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

  • Raport sprzedawcy: informuje sprzedawcę o zwycięzcy aukcji reklam.
  • Raport o kupującym: informacje dostępne tylko dla zwycięskich kupujących. Dzięki nim można się dowiedzieć, że wygrali aukcję.

Planem długoterminowym jest umożliwienie przeglądarce raportowania wyników aukcji dla sprzedawców i kupujących za pomocą interfejsów 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(). Chodzi o 1 argument: ciąg znaków reprezentujący adres URL pobierany po zakończeniu aukcji, który koduje informacje na poziomie zdarzenia do uwzględnienia w raportach.

Funkcje interfejsu API

Sprzedawca: reportResult()

JavaScript sprzedawcy udostępniony w decisionLogicUrl (który zawiera również scoreAd()) może zawierać funkcję reportResult() do raportowania wyników aukcji.

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

Argumenty przekazywane do tej funkcji to:

auctionConfig

Obiekt konfiguracji aukcji przekazany do navigator.runAdAuction().

browserSignals

Obiekt utworzony przez przeglądarkę, który dostarcza informacji 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ść zwrotna tej funkcji jest używana jako argument sellerSignals w funkcji reportWin() zwycięskiego licytującego.

Kupujący: reportWin()

Kod JavaScript zwycięskiego licytującego (który również zawiera element 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 funkcji generateBid() w przypadku zwycięskiego licytującego.

sellerSignals

Zwrot wartości reportResult(), który umożliwia sprzedawcy przekazanie informacji kupującemu.

browserSignals

Obiekt utworzony przez przeglądarkę, który dostarcza informacji 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 na potrzeby raportowania aukcji są tymczasowo dostępne 2 metody:

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

Każda z tych metod wymaga jednego argumentu: adresu URL, który zostanie pobrany po zakończeniu aukcji. Można je wywoływać wiele razy (zarówno w parametrze scoreAd(), jak i generateBid()) przy użyciu różnych argumentów adresu URL.

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

Te metody są domyślnie dostępne w Chrome po włączeniu wszystkich interfejsów API prywatności w reklamach w sekcji chrome://settings/adPrivacy. Jeśli używasz Chrome z flagami wiersza poleceń, aby włączyć interfejs Protected Audience API, musisz samodzielnie włączyć te metody, dodając flagę BiddingAndScoringDebugReportingAPI. Jeśli flaga nie jest włączona, metody nadal będą dostępne, ale nie wymagają ż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.