Debugowanie raportów w ramach Protected Audience API

Raportowanie debugowania Protected Audience API umożliwia deweloperom technologii reklamowych deklarowanie zdalnych adresów URL, aby otrzymywać z urządzeń żądanie GET, gdy aukcja zostanie wygrana lub przegrana. Umożliwia to następujące przypadki użycia:

  • Otrzymuj raporty o wygranych i przegranych aukcjach.
  • Dowiedz się, dlaczego przegrywasz aukcje. Na przykład: sprawdź, czy problem dotyczy implementacji skryptu ustalania stawek lub oceniania, czy też podstawowej logiki.
  • Wykrywanie problemów po zaktualizowaniu logiki JavaScript

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

Długoterminowy plan zakłada umożliwienie platformie raportowania wyników aukcji za pomocą usługi Private Aggregation. Dzięki temu raportowanie po fakcie nie może być używane do łączenia niestandardowych list odbiorców poszczególnych użytkowników z aplikacją wydawcy. Raportowanie na poziomie zdarzenia jest tymczasowe i będzie dostępne do czasu udostępnienia odpowiednich ram raportowania.

Dowiedz się więcej o [raportowaniu debugowania w pierwotnej propozycji testowania origin FLEDGE w Chrome][10].

Wykorzystanie

Raportowanie debugowania jest realizowane za pomocą tych interfejsów API JavaScript, z których każdy przyjmuje argument w postaci ciągu znaków URL:

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

W przykładzie poniżej zgłaszana jest przegrana aukcja reklamy ze zwycięską stawką i zmienną wewnętrzną. Dane te mogą być następnie wykorzystywane do debugowania.

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

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

Sprzedawcy mogą opcjonalnie zwrócić wartość rejectReason z 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 przyczyny odrzucenia, zamiast niej zostanie wysłany kod not-available.

Zmienne adresu URL

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

Nazwa zmiennej Opis
winningBid Wartość zwycięskiej stawki.
madeWinningBid Wartość logiczna określająca, czy kupujący tę niestandardową listę odbiorców złożył zwycięską stawkę, korzystając z tej listy lub innej niestandardowej listy odbiorców z tym samym kupującym.
highestScoringOtherBid Wartość stawki, która została oceniona jako druga najwyższa przez skrypt scoreAd sprzedawcy. Pamiętaj, że nie musi to być druga najwyższa stawka, ponieważ wyniki i stawki mogą być od siebie niezależne.
madeHighestScoringOtherBid Wartość logiczna określająca, czy kupujący tych odbiorców niestandardowych złożył stawkę ${highestScoringOtherBid}, korzystając z tych odbiorców niestandardowych lub innych odbiorców niestandardowych z tym samym kupującym.
rejectReason Ciąg znaków opcjonalnie ustawiany przez sprzedawcę, który wyjaśnia, dlaczego odrzucił on stawkę. Może przyjmować 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 adresu URL musi być zgodny z zarejestrowaną domeną Privacy Sandbox.
  • Adres URL nie może przekraczać 4096 znaków, w tym domeny, prefiksu https:// i zastąpionych danych aukcji.
  • W przyszłych wersjach pingi debugowania będą wysyłane tylko po połączeniu z Wi-Fi.

Działanie na urządzeniu

W środowisku mobilnym ochrona pamięci i wykorzystania sieci jest priorytetem. Dlatego raporty debugowania są generowane partiami.

Te właściwości systemowe kontrolują szybkość i rozmiar 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

Oczekiwane opóźnienie raportu debugowania wynosi od 15 do 60 minut po zakończeniu aukcji.

Nie ma gwarancji, że raporty debugowania będą kompletne. Jeśli urządzenie zostanie ponownie uruchomione lub proces adservices ulegnie awarii przed wysłaniem wywołań do serwera, te zdarzenia zostaną odrzucone.

Każda platforma reklamowa może zarejestrować maksymalnie 75 adresów URL debugowania na aukcję. Adresy URL zarejestrowane po osiągnięciu tego limitu są dyskretnie odrzucane.

Jeśli użytkownik wyłączył AdId, wysyłane są raporty debugowania. Ta funkcja nie jest zaimplementowana w wersji deweloperskiej 9, ale zostanie dodana w przyszłych wersjach.

Sposób działania serwera technologii reklamowej

W przypadku raportowania debugowania serwery technologii reklamowych powinny działać w ten sposób:

  • Urządzenie wysyła żądania GET do serwera określonego za pomocą interfejsów forDebuggingOnly.* API.
  • Każde żądanie reprezentuje pojedynczy raport debugowania na poziomie zdarzenia: wygraną lub przegraną w pojedynczej aukcji reklamowej.
  • Każde żądanie nie ma treści. Wszystkie dane znajdują się w parametrach zapytania.
  • Duże ładunki odpowiedzi mogą negatywnie wpływać na wydajność i użycie danych, dlatego są ignorowane.