Debug-Berichte für Protected Audience

Mit Protected Audience-Debug-Berichten können Entwickler von Anzeigentechnologien Remote-URLs deklarieren, um bei gewonnenen oder verlorenen Auktionen einen GET-Request von Geräten zu erhalten. Dies ermöglicht die folgenden Anwendungsfälle:

  • Berichte zu gewonnenen und verlorenen Auktionsergebnissen erhalten
  • Gründe für verlorene Auktionen Beispiel: Sie möchten herausfinden, ob es sich um ein Problem mit der Implementierung eines Gebots- oder Scoring-Scripts oder um ein Problem mit der Kernlogik handelt.
  • Probleme erkennen, wenn die JavaScript-Logik aktualisiert wird

Berichte auf Ereignisebene für das Debugging sind für Tests in Privacy Sandbox Developer Preview 9 verfügbar. Die Debug-Berichterstellung wird auf allen Geräten unterstützt, auf denen die AdID verfügbar ist.

Langfristig soll die Plattform Auktionsergebnisse mit dem Dienst „Private Aggregation“ melden können. So wird verhindert, dass die nachträglichen Berichte verwendet werden, um die benutzerdefinierten Zielgruppen einzelner Nutzer mit der App des Publishers zu verknüpfen. Berichte auf Ereignisebene sind vorübergehend, bis ein geeignetes Berichtsframework veröffentlicht wird.

[Weitere Informationen zum Debugging-Bericht im ursprünglichen FLEDGE-Testzeitraumvorschlag für Chrome][10]

Nutzung

Die Fehlerbehebung wird mit den folgenden JavaScript-APIs implementiert, die beide ein URL-String-Argument verwenden:

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

Im folgenden Beispiel wird ein Verlust bei einer Anzeigenauktion mit dem Höchstgebot und einer internen Variablen gemeldet. Diese Daten können dann zur Fehlerbehebung verwendet werden.

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

Die Vorlage ${winningBid} wird nach Abschluss der Auktion durch den tatsächlichen Wert ersetzt.

Verkäufer können optional einen rejectReason aus ihrer scoreAds-Funktion zurückgeben:

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'
  }
}

Wenn ein Verkäufer keinen Ablehnungsgrund angibt, wird stattdessen not-available gesendet.

URL-Variablen

Die Variablen, die der Debug-URL hinzugefügt werden können, entsprechen ihren Pendants in Chrome. ${topLevelWinningBid} und ${topLevelMadeWinningBid} sind jedoch nicht verfügbar, da es auf Android keine Komponentenauktionen gibt.

Variablenname Beschreibung
winningBid Der Wert des erfolgreichen Gebots.
madeWinningBid Ein boolescher Wert, der angibt, ob der Käufer dieser benutzerdefinierten Zielgruppe das erfolgreiche Gebot abgegeben hat, entweder über diese benutzerdefinierte Zielgruppe oder über eine andere benutzerdefinierte Zielgruppe mit demselben Käufer.
highestScoringOtherBid Der Wert des Gebots, das vom scoreAd-Script des Verkäufers als zweithöchstes Gebot eingestuft wurde. Das muss nicht das zweithöchste Gebot sein, da Werte und Gebote unabhängig voneinander sein können.
madeHighestScoringOtherBid Ein boolescher Wert, der angibt, ob der Käufer dieser benutzerdefinierten Zielgruppe das ${highestScoringOtherBid}-Gebot abgegeben hat, entweder über diese benutzerdefinierte Zielgruppe oder über eine andere benutzerdefinierte Zielgruppe mit demselben Käufer.
rejectReason Ein String, der optional von einem Verkäufer festgelegt wird, um zu erklären, warum er ein Gebot abgelehnt hat. Mögliche Werte:

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

Einschränkungen

  • Der URL-Host muss mit Ihrer registrierten Privacy Sandbox-Domain übereinstimmen.
  • Die URL darf einschließlich der Domain, des Präfixes https:// und der substituierten Auktionsdaten nicht länger als 4.096 Zeichen sein.
  • In zukünftigen Releases werden Debug-Pings nur gesendet, wenn eine WLAN-Verbindung besteht.

Verhalten auf dem Gerät

In einer mobilen Umgebung ist der Schutz von Arbeitsspeicher und Netzwerkressourcen von höchster Priorität. Daher werden Debug-Berichte in Batches erstellt.

Die folgenden Systemeigenschaften steuern die Batchrate und -größe, die für die Entwicklung auf niedrigere Werte angepasst werden können:

  • fledge_event_level_debug_reporting_batching_rate
  • fledge_event_level_debug_reporting_batch_size

Die erwartete Latenz eines Debug-Berichts liegt zwischen 15 und 60 Minuten nach Abschluss einer Auktion.

Es gibt keine Garantie für die Vollständigkeit von Debug-Berichten. Wenn das Gerät neu gestartet wird oder der adservices-Prozess abstürzt, bevor Aufrufe an den Server gesendet werden, werden diese Ereignisse verworfen.

Für jede Ad-Tech-Lösung gilt ein Limit von maximal 75 registrierten Debug-URLs pro Auktion. URLs, die nach Erreichen dieses Limits registriert werden, werden ohne Benachrichtigung verworfen.

Wenn der Nutzer AdId deaktiviert hat, werden Debug-Berichte gesendet. Dies ist in der Developer Preview 9 noch nicht implementiert, wird aber in zukünftigen Versionen implementiert.

Verhalten von Ad-Tech-Servern

Ad-Tech-Server sollten für Debug-Berichte die folgenden Verhaltensweisen aufweisen:

  • Das Gerät sendet GET-Anfragen an den Server, den Sie mit den forDebuggingOnly.*-APIs angeben.
  • Jede Anfrage steht für einen einzelnen Debug-Bericht auf Ereignisebene: einen einzelnen Auktionsgewinn oder ‑verlust.
  • Jede Anfrage hat keinen Text. Alle Daten befinden sich in den Abfrageparametern.
  • Große Antwortnutzlasten können sich negativ auf die Leistung und die Datennutzung auswirken und werden ignoriert.