Debug-Berichte für Protected Audience

Mit Protected Audience Debug-Berichten können AdTech-Entwickler Remote-URLs so deklarieren, dass sie eine GET-Anfrage von Geräten erhalten, wenn eine Auktion gewonnen oder verloren wird. Dies ermöglicht folgende Anwendungsfälle:

  • Berichte zu gewonnenen und verlorenen Auktionsergebnissen erhalten
  • Verstehen, warum Auktionen verloren gehen Sie können beispielsweise herausfinden, ob es sich um ein Problem mit der Implementierung eines Gebots- oder Bewertungsskripts oder um ein grundlegendes Logikproblem handelt.
  • Probleme erkennen, wenn die JavaScript-Logik aktualisiert wird

Debug-Berichte auf Ereignisebene sind zum Testen in der Privacy Sandbox-Entwicklervorschau 9 verfügbar. Debug-Berichte werden auf allen Geräten unterstützt, auf denen AdId verfügbar ist.

Langfristig planen wir, es der Plattform zu ermöglichen, Auktionsergebnisse mit dem privaten Aggregationsdienst zu melden. So ist sichergestellt, dass nachträgliche Berichte nicht dazu verwendet werden können, die benutzerdefinierten Zielgruppen einzelner Nutzer mit der App des Publishers zusammenzuführen. Berichte auf Ereignisebene sind temporär, bis ein ausreichendes Framework für die Berichterstellung verfügbar ist.

Weitere Informationen zur Fehlerbehebung bei Berichten im ursprünglichen Vorschlag für FLEDGE-Ursprungstests von Chrome

Nutzung

Debug-Berichte werden mithilfe der folgenden JavaScript-APIs implementiert, die beide ein URL-Stringargument verwenden:

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

Im folgenden Beispiel wird ein Verlust der Anzeigenauktion mit dem erfolgreichen Gebot und einer internen Variablen erfasst. Diese Daten können dann zum Debugging 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.

Optional können Verkäufer eine rejectReason von 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 angegeben hat, wird stattdessen not-available gesendet.

URL-Variablen

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

Variablenname Beschreibung
winningBid Wert des erfolgreichen Gebots
madeWinningBid Ein boolescher Wert, der angibt, ob der Käufer dieser benutzerdefinierten Zielgruppe das erfolgreiche Gebot abgegeben hat, entweder von dieser oder von einer anderen benutzerdefinierten Zielgruppe mit demselben Käufer.
highestScoringOtherBid Der Wert des Gebots, das vom ScoreAd-Skript des Verkäufers als zweithöchste bewertet wurde. Dies ist möglicherweise nicht der zweithöchste Gebotswert, da Bewertungen und Gebote voneinander unabhängig sein können.
madeHighestScoringOtherBid Ein boolescher Wert, der angibt, ob der Käufer dieser benutzerdefinierten Zielgruppe das Gebot ${highestScoringOtherBid} abgegeben hat, entweder von dieser oder von einer anderen benutzerdefinierten Zielgruppe mit demselben Käufer.
rejectReason Ein von einem Verkäufer optional festgelegter String, in dem erläutert wird, warum ein Gebot abgelehnt wurde. Kann einen der folgenden Werte sein:

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

Einschränkung

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

Verhalten auf dem Gerät

In einer mobilen Umgebung hat der Schutz des Arbeitsspeichers und der Netzwerknutzung oberste Priorität. Debug-Berichte werden daher gebündelt 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 feste Garantie für die Vollständigkeit von Debug-Berichten. Wenn das Gerät neu startet oder der Adservices-Prozess abstürzt, bevor Aufrufe an den Server gesendet werden, werden diese Ereignisse verworfen.

Für jede Anzeigentechnologie dürfen pro Auktion maximal 75 registrierte Debug-URLs verwendet werden. URLs, die nach Erreichen dieses Limits registriert wurden, werden ohne Rückmeldung verworfen.

Wenn der Nutzer AdId deaktiviert hat, werden Debug-Berichte gesendet. Dies wurde in der Entwicklervorschau 9 nicht implementiert, wird jedoch in zukünftigen Versionen implementiert.

Verhalten des AdTech-Servers

Für AdTech-Server sollten folgende Verhaltensweisen vorliegen:

  • Das Gerät sendet GET-Anfragen an den Server, den Sie mit den forDebuggingOnly.* APIs angeben.
  • Jede Anfrage stellt einen Debug-Bericht auf Ereignisebene dar: 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 Datennutzung auswirken und werden ignoriert.