Debugowanie raportów w ramach Protected Audience API

Raportowanie debugowania w ramach Protected Audience API umożliwia deweloperom technologii reklamowych deklarowanie zdalnych adresów URL, aby otrzymywać z urządzeń żądanie GET w przypadku wygranej lub przegranej aukcji. Pozwala to na korzystanie z tych funkcji:

  • Otrzymuj raporty dotyczące wygranych i przegranych aukcji.
  • Dowiedz się, dlaczego aukcje przegrywają. Na przykład: sprawdź, czy jest to problem z implementacją skryptu określania stawek lub punktacji, czy też z podstawowym problemem logicznym.
  • Wykrywanie problemów w przypadku aktualizacji logiki JavaScript

Raportowanie debugowania na poziomie zdarzenia jest dostępne do testowania w wersji przedpremierowej dla programistów Piaskownicy prywatności w wersji 9. Raportowanie debugowania jest obsługiwane na wszystkich urządzeniach, na których dostępny jest identyfikator AdId.

Plan długoterminowy polega na umożliwieniu platformie raportowania wyników aukcji za pomocą usługi agregacji prywatnej. Dzięki temu nie można korzystać z raportów po fakcie do łączenia niestandardowych list odbiorców poszczególnych użytkowników z aplikacją wydawcy. Raportowanie na poziomie zdarzenia jest tymczasowe, dopóki nie zostanie wprowadzony odpowiedni sposób raportowania.

Dowiedz się więcej o raportowaniu debugowania w pierwotnej ofercie Chrome dotyczącej testowania origin FLEDGE.

Wykorzystanie

Raportowanie debugowania jest wdrażane za pomocą poniższych interfejsów API JavaScript, które przyjmują argumenty w postaci ciągu znaków adresu URL:

  • forDebuggingOnly.reportAdAuctionWin(String url)
  • forDebuggingOnly.reportAdAuctionLoss(String url)

W przykładzie poniżej zgłoszono przegraną w aukcji reklam ze zwycięską stawką i zmienną wewnętrzną. Dane te mogą zostać później użyte do debugowania.

let someDebuggableVariable = 123;
const url = "https://example.com/reportLoss?winningBid=${winningBid}&someDebuggableVariable=" + someDebuggableVariable;
forDebuggingOnly.reportAdAuctionLoss(url);

Po zakończeniu aukcji szablon ${winningBid} jest zastępowany rzeczywistą wartością.

Sprzedawcy mogą opcjonalnie zwrócić rejectReason ze swojej funkcji scoreAds:

function scoreAd(ad, bid, auction_config, seller_signals,
                 trusted_scoring_signals, contextual_signal,
                 custom_audience_signal) {
  let score = ...
  return {
    'status': 0,
    'score': score,
    'rejectReason': 'blocked-by-publisher'
  }
}

Jeśli sprzedawca nie poda powodu odrzucenia, zamiast tego wysyłany jest not-available.

Zmienne adresów URL

Zmienne, które można dodawać do adresu URL debugowania odpowiadają ich odpowiednikom w Chrome (chociaż ${topLevelWinningBid} i ${topLevelMadeWinningBid} są niedostępne, ponieważ w Androidzie nie ma pojęcia o aukcjach komponentów).

Nazwa zmiennej Opis
winningBid Wartość zwycięskiej stawki.
madeWinningBid Wartość logiczna wskazująca, czy kupujący korzystający z niestandardowych list odbiorców zaproponował najlepszą stawkę – przez tę niestandardową listę odbiorców czy przez inną niestandardową listę odbiorców z tym samym kupującym.
highestScoringOtherBid Wartość stawki, która została oceniona jako druga pod względem wysokości przez skrypt ScoreAd sprzedawcy. Pamiętaj, że nie musi to być druga najwyższa wartość stawki, ponieważ wyniki i stawki mogą być niezależne.
madeHighestScoringOtherBid Wartość logiczna wskazująca, czy kupujący korzystający z tej niestandardowej listy odbiorców zaoferował stawkę ${highestScoringOtherBid} w ramach tej niestandardowej listy odbiorców czy innej niestandardowej grupy odbiorców z tym samym kupującym.
rejectReason Ciąg znaków (opcjonalnie) ustawiony przez sprzedawcę i wyjaśniający, dlaczego odrzucił stawkę. Może mieć dowolną z tych wartości:

  • not-available
  • invalid-bid
  • bid-below-auction-floor
  • pending-approval-by-exchange
  • disapproved-by-exchange
  • blocked-by-publisher
  • language-exclusions
  • category-exclusions

Ograniczenia

  • Host URL musi być zgodny z zarejestrowaną domeną Piaskownicy prywatności.
  • Adres URL nie może mieć więcej niż 4096 znaków, w tym nazwa domeny, prefiks https:// i podstawione dane aukcji.
  • W kolejnych wersjach pingi debugowania będą wysyłane tylko po połączeniu z Wi-Fi.

Zachowanie na urządzeniu

W środowiskach mobilnych ochrona pamięci i wykorzystania sieci jest priorytetem. Dlatego raporty debugowania są tworzone partiami.

Te właściwości systemowe sterują szybkością i rozmiarem wsadu, które można dostosować do niższych wartości na potrzeby programowania:

  • fledge_event_level_debug_reporting_batching_rate
  • fledge_event_level_debug_reporting_batch_size

Spodziewany czas oczekiwania na raport debugowania to 15–60 minut od zakończenia aukcji.

Nie ma sztywnych gwarancji kompletności raportów debugowania. Jeśli urządzenie uruchomi się ponownie lub proces usług reklamowych ulegnie awarii przed wysłaniem wywołań do serwera, te zdarzenia zostaną pominięte.

W przypadku każdej technologii reklamowej obowiązuje limit 75 zarejestrowanych adresów URL do debugowania na aukcję. Adresy URL zarejestrowane po osiągnięciu limitu są dyskretnie usuwane.

Raporty debugowania są wysyłane, jeśli użytkownik wyłączył parametr AdId. Ta funkcja nie jest zaimplementowana w wersji przedpremierowej dla programistów w wersji 9, ale zostanie wdrożona w kolejnych wersjach.

Działanie serwera technologii reklamowych

Na potrzeby raportowania debugowania serwery technologii reklamowych powinny działać w taki sposób:

  • Urządzenie wysyła żądania GET do serwera określonego za pomocą interfejsów API forDebuggingOnly.*.
  • Każde żądanie odpowiada jednemu raportowi debugowania na poziomie zdarzenia: 1 wygrana na aukcji reklam lub przegrana aukcji.
  • Żadne żądanie nie ma treści. Wszystkie dane są zawarte w parametrach zapytania.
  • Duże ładunki odpowiedzi mogą negatywnie wpływać na wydajność i użycie danych, dlatego są ignorowane.