Ausrichtung auf benutzerdefinierte Zielgruppen mit der Protected Audience API unterstützen

Letzte Updates

• Es wurden Informationen zum Planen von Aktualisierungen benutzerdefinierter Zielgruppen hinzugefügt.
• Integration von Attributionsberichten in Protected Audiences
• Zeitachse der Funktionen für geschützte Zielgruppen
• FLEDGE wurde in Protected Audience API umbenannt.
• Vorschlag für die Delegierung von benutzerdefinierten Zielgruppen hinzugefügt.
• Die Anforderung für die k-Anonymität für die URL für die tägliche Aktualisierung wurde entfernt.

Protected Audience befindet sich in der Betaphase und ist für die Entwicklung verfügbar.

Mit Protected Audience haben Sie folgende Möglichkeiten:

• Benutzerdefinierte Zielgruppen basierend auf bisherigen Nutzeraktionen verwalten
• On-Device-Auktionen mit Unterstützung für die Vermittlung durch einen einzelnen Verkäufer oder eine Vermittlungsabfolge starten.
• Impressionsberichte nach der Anzeigenauswahl erstellen

Lesen Sie sich als Erstes den Entwicklerleitfaden für Protected Audience durch. Wir freuen uns über Ihr Feedback, damit wir Protected Audience weiter verbessern können.

Zeitachse

In den kommenden Monaten werden wir weitere Funktionen veröffentlichen. Die genauen Veröffentlichungstermine variieren je nach Funktion. Diese Tabelle wird mit Links zu Dokumentationen aktualisiert, sobald diese verfügbar sind.

Übersicht

Bei mobiler Werbung müssen Werbetreibende häufig Anzeigen für potenziell interessierte Nutzer ausliefern, je nachdem, wie sie zuvor mit der App des Werbetreibenden interagiert haben. Der Entwickler der SportingGoodsApp möchte beispielsweise Nutzern, die noch Artikel im Einkaufswagen haben, Anzeigen präsentieren, die sie daran erinnern, den Kauf abzuschließen. In der Branche wird diese allgemeine Idee häufig mit Begriffen wie „Remarketing“ und „Targeting auf benutzerdefinierte Zielgruppen“ beschrieben.

Derzeit werden diese Anwendungsfälle in der Regel durch die Weitergabe von kontextbezogenen Informationen zur Auslieferung der Anzeige (z. B. der Name der App) und privaten Informationen wie Zielgruppenlisten an Plattformen für Anzeigentechnologien implementiert. Anhand dieser Informationen können Werbetreibende auf ihren Servern relevante Anzeigen auswählen.

Die Protected Audience API auf Android (früher FLEDGE) umfasst die folgenden APIs für AdTech-Plattformen und Werbetreibende, um gängige interaktionsbasierte Anwendungsfälle so zu unterstützen, dass die Weitergabe von IDs zwischen Apps und die Weitergabe von Informationen zu App-Interaktionen eines Nutzers an Dritte eingeschränkt wird:

1. Custom Audience API: Diese API basiert auf der Abstraktion „benutzerdefinierte Zielgruppe“, die eine vom Werbetreibenden festgelegte Zielgruppe mit gemeinsamen Absichten darstellt. Zielgruppeninformationen werden auf dem Gerät gespeichert und können mit relevanten Anzeigen für die Zielgruppe und beliebigen Metadaten wie Gebotssignalen verknüpft werden. Die Informationen können für Werbetreibendengebote, Anzeigenfilterung und ‑rendering verwendet werden.
2. Ad Selection API: Diese API bietet ein Framework, mit dem die Workflows von Anzeigentechnologie-Plattformen orchestriert werden, die On-Device-Signale verwenden, um eine „gewinnende“ Anzeige zu ermitteln. Dabei werden lokal gespeicherte Anzeigenvorschläge berücksichtigt und Anzeigenvorschläge, die eine Anzeigentechnologie-Plattform an das Gerät zurückgibt, werden zusätzlich verarbeitet.

Die Integration funktioniert im Groben so:

1. SportingGoodsApp möchte seine Nutzer daran erinnern, Artikel zu kaufen, die noch in ihrem Einkaufswagen sind, wenn sie den Kauf nicht innerhalb von zwei Tagen abgeschlossen haben. SportingGoodsApp verwendet die Custom Audience API, um den Nutzer der Zielgruppenliste „Produkte im Einkaufswagen“ hinzuzufügen. Die Plattform verwaltet und speichert diese Zielgruppenliste auf dem Gerät und schränkt die Weitergabe an Dritte ein. SportingGoodsApp arbeitet mit einer Anzeigentechnologieplattform zusammen, um Nutzern in seiner Zielgruppenliste Anzeigen zu präsentieren. Die Anzeigentechnologie-Plattform verwaltet Metadaten für Zielgruppenlisten und stellt Anzeigenvorschläge bereit, die für den Workflow zur Anzeigenauswahl zur Verfügung gestellt werden. Die Plattform kann so konfiguriert werden, dass regelmäßig aktualisierte, auf Zielgruppen basierende Anzeigen im Hintergrund abgerufen werden. So bleibt die Liste der passenden Zielgruppen-Anzeigen aktuell und nicht mit Anfragen korreliert, die während der Anzeigenbereitstellung an Ad-Server von Drittanbietern gesendet werden (d.h. Anfragen für kontextbezogene Anzeigen).

2. Wenn der Nutzer das FrisbeeGame auf demselben Gerät spielt, wird ihm möglicherweise eine Anzeige angezeigt, in der er daran erinnert wird, den Kauf der Artikel abzuschließen, die im Einkaufswagen der SportingGoodsApp liegen. Dazu ruft FrisbeeGame (mit einem integrierten Anzeigen-SDK) die Anzeigenauswahl API auf, um eine Anzeigenauslieferung für den Nutzer basierend auf einer beliebigen Zielgruppenliste auszuwählen, zu der er gehört. In diesem Beispiel ist das die benutzerdefinierte Zielgruppe „Produkte im Einkaufswagen“, die von SportingGoodsApp erstellt wurde. Der Workflow für die Anzeigenauswahl kann so eingerichtet werden, dass neben On-Device-Anzeigen, die mit den benutzerdefinierten Zielgruppen verknüpft sind, auch Anzeigen berücksichtigt werden, die von den Servern von Anzeigentechnologieplattformen abgerufen werden, sowie andere On-Device-Signale. Der Workflow kann auch von der AdTech-Plattform und dem Anzeigen-SDK mit benutzerdefinierten Gebots- und Bewertungslogiken angepasst werden, um die entsprechenden Werbeziele zu erreichen. Mit diesem Ansatz können die Interessen oder App-Interaktionsdaten der Nutzer für die Anzeigenauswahl herangezogen werden, während die Weitergabe dieser Daten an Dritte eingeschränkt wird.

3. Das SDK der App oder Anzeigentechnologie-Plattform für die Anzeigenbereitstellung rendert die ausgewählte Anzeige.

4. Die Plattform erleichtert die Erstellung von Berichten zu Impressionen und Ergebnissen der Anzeigenauswahl. Diese Berichtsfunktion ergänzt die Attribution Reporting API. Anbieter von Anzeigentechnologien können die Berichte je nach Berichtsanforderungen anpassen.

Zugriff auf Protected Audience über Android APIs erhalten

Anbieter von Anzeigentechnologien müssen sich registrieren, um auf die Protected Audience API zugreifen zu können. Weitere Informationen finden Sie unter Privacy Sandbox-Konto registrieren.

Verwaltung benutzerdefinierter Zielgruppen

Benutzerdefinierte Zielgruppe

Eine benutzerdefinierte Zielgruppe besteht aus einer vom Werbetreibenden festgelegten Gruppe von Nutzern mit gemeinsamen Absichten oder Interessen. In einer App oder einem SDK kann eine benutzerdefinierte Zielgruppe verwendet werden, um eine bestimmte Zielgruppe anzugeben, z. B. Nutzer, die „Artikel im Einkaufswagen gelassen“ oder „die Anfängerlevel eines Spiels abgeschlossen“ haben. Die Plattform verwaltet und speichert Zielgruppeninformationen lokal auf dem Gerät und gibt nicht preis, zu welchen benutzerdefinierten Zielgruppen der Nutzer gehört. Benutzerdefinierte Zielgruppen unterscheiden sich von den Interessengruppen für Protected Audience in Chrome und können nicht für das Web und Apps gemeinsam verwendet werden. So wird die Weitergabe von Nutzerdaten eingeschränkt.

Eine App eines Werbetreibenden oder das integrierte SDK kann eine benutzerdefinierte Zielgruppe beitreten oder verlassen, z. B. basierend auf dem Nutzer-Engagement in einer App.

Metadaten für benutzerdefinierte Zielgruppen

Jede benutzerdefinierte Zielgruppe enthält die folgenden Metadaten:

• Owner:Paketname der Eigentümer-App. Dieser wird implizit auf den Paketnamen der aufrufenden App festgelegt.
• Käufer:Käufernetzwerk, das Anzeigen für diese benutzerdefinierte Zielgruppe verwaltet. Der Käufer ist auch die Partei, die auf die benutzerdefinierte Zielgruppe zugreifen und relevante Anzeigeninformationen abrufen kann. Der Käufer wird im Format „eTLD+1“ angegeben.
• Name:Ein beliebiger Name oder eine beliebige Kennung für die benutzerdefinierte Zielgruppe, z. B. „Nutzer, die den Einkaufswagen ohne Kauf verlassen haben“. Dieses Attribut kann beispielsweise als eines der Targeting-Kriterien in den Werbekampagnen des Werbetreibenden oder als Suchstring in der URL zum Abrufen des Gebotscodes verwendet werden.
• Aktivierungszeit und Ablaufzeit:In diesen Feldern wird der Zeitraum definiert, in dem diese benutzerdefinierte Zielgruppe aktiv ist. Die Plattform verwendet diese Informationen, um die Mitgliedschaft in einer benutzerdefinierten Zielgruppe aufzuheben. Die Gültigkeitsdauer darf ein maximales Zeitfenster nicht überschreiten, um die Lebensdauer einer benutzerdefinierten Zielgruppe zu begrenzen.
• URL für die tägliche Aktualisierung:Die URL, über die die Plattform fortlaufend Anzeigenvorschläge und andere Metadaten abruft, die in den Feldern „Signale für Gebote von Nutzern“ und „Signale für vertrauenswürdige Gebote“ definiert sind. Weitere Informationen finden Sie im Abschnitt zum Abrufen von Anzeigenvorschlägen für benutzerdefinierte Zielgruppen.
• Signale für Gebote von Nutzern:Plattformspezifische Signale für Anzeigentechnologien für Gebote für Remarketing-Anzeigen. Beispiele für Signale sind der ungefähre Standort oder die bevorzugte Sprache des Nutzers.
• Vertrauenswürdige Gebotsdaten:Anzeigentechnologie-Plattformen nutzen Echtzeitdaten, um die Anzeigenabruf- und -bewertung zu optimieren. Beispielsweise kann das Budget für eine Anzeige aufgebraucht sein und die Auslieferung muss sofort beendet werden. Eine Anzeigentechnologie kann einen URL-Endpunkt definieren, von dem diese Echtzeitdaten abgerufen werden können, und die Schlüssel, für die die Echtzeitsuche durchgeführt werden muss. Der Server, der diese Anfrage verarbeitet, ist ein vertrauenswürdiger Server, der von der AdTech-Plattform verwaltet wird.
• URL der Gebotslogik:Die URL, über die die Plattform Gebotscode von der Demand-Side-Plattform abruft. Die Plattform führt diesen Schritt aus, wenn eine Anzeigenauktion gestartet wird.
• Anzeigen:Eine Liste der Anzeigen, die für die benutzerdefinierte Zielgruppe infrage kommen. Dazu gehören plattformspezifische Anzeigenmetadaten und eine URL zum Rendern der Anzeige. Wenn eine Auktion für die benutzerdefinierte Zielgruppe gestartet wird, wird diese Liste mit Anzeigenmetadaten berücksichtigt. Diese Liste wird nach Möglichkeit über den Endpunkt für die tägliche Aktualisierung der URL aktualisiert. Aufgrund von Ressourceneinschränkungen auf Mobilgeräten ist die Anzahl der Anzeigen, die in einer benutzerdefinierten Zielgruppe gespeichert werden können, begrenzt.

Delegierung von benutzerdefinierten Zielgruppen

Der etablierte Ansatz zur Definition und Konfiguration benutzerdefinierter Zielgruppen basiert in der Regel auf serverseitigen Technologien und Integrationen, die von AdTech-Unternehmen in Zusammenarbeit mit Agentur- und Werbetreibenden-Kunden und -Partnern entwickelt werden. Mit der Protected Audience API können Sie benutzerdefinierte Zielgruppen definieren und konfigurieren und gleichzeitig die Privatsphäre der Nutzer schützen. Wenn Käufer-Werbetechnologien, die kein SDK in Apps haben, eine benutzerdefinierte Zielgruppe verwenden möchten, müssen sie mit Werbetechnologien zusammenarbeiten, die On-Device-Technologien nutzen, z. B. mobile Analysepartner (MMPs) und Supply-Side-Plattformen (SSPs). Die Protected Audience API soll diese SDKs unterstützen, indem sie flexible Lösungen für die Verwaltung benutzerdefinierter Zielgruppen bietet. So können On-Device-Caller im Namen von Käufern benutzerdefinierte Zielgruppen erstellen. Dieser Vorgang wird als Delegierung von benutzerdefinierten Zielgruppen bezeichnet. So konfigurieren Sie die Deaktivierung benutzerdefinierter Zielgruppen:

Benutzerdefinierte Zielgruppen zusammenführen

Es gibt zwei Möglichkeiten, einer benutzerdefinierten Zielgruppe beizutreten:

joinCustomAudience()

Eine App oder ein SDK kann den Beitritt zu einer benutzerdefinierten Zielgruppe anfordern, indem joinCustomAudience() aufgerufen wird, nachdem das CustomAudience-Objekt mit den erwarteten Parametern instanziiert wurde. Hier ein Beispiel für ein Code-Snippet:

CustomAudience audience = new CustomAudience(
    Buyer = "example-dsp.com",
    Name = "running-shoes",
    ActivationTime = now(),
    ExpirationTime = ActivationTime.plus(30 days),
    DailyUpdateURL = Uri.parse("https://..."),
    UserBiddingSignals = new JSONObject("{...}"),
    TrustedBiddingURL = Uri.parse("https://..."),
    TrustedBiddingKeys = {'key1","key2", ...,"key n"},
    BiddingLogicURL =  Uri.parse("https://..."),
    Ads = [new AdData(renderUrl = Uri.parse("https://..."),
           metadata = new JSONObject("{...}"), ...];

// Invoke ad services API to join a custom audience.
joinCustomAudience(audience);

fetchAndJoinCustomAudience()

Eine App oder ein SDK kann im Namen einer Anzeigentechnologie, die nicht auf dem Gerät vorhanden ist, die Aufnahme in eine benutzerdefinierte Zielgruppe beantragen. Dazu wird fetchAndJoinCustomAudience() mit den erwarteten Parametern aufgerufen, wie im folgenden Beispiel:

FetchAndJoinCustomAudienceRequest fetchRequest = new FetchAndJoinCustomAudienceRequest(
    // Example: Optional verification token passed inside the fetch URL
    FetchURI = Uri.parse("https://example-dsp.com/...?mytoken=arbitrary1234"),
    // All the following parameters are optional
    Name = "running-shoes",
    ActivationTime = now(),
    ExpirationTime = ActivationTime.plus(30 days),
    UserBiddingSignals = new JSONObject("{...}")
);

fetchAndJoinCustomAudience(fetchRequest);

Der URL-Endpunkt des Käufers antwortet mit einem CustomAudience-JSON-Objekt im Antworttext. Die Felder „Buyer“ und „Owner“ der benutzerdefinierten Zielgruppe werden ignoriert und von der API automatisch ausgefüllt. Außerdem wird durch die API erzwungen, dass die URL für die tägliche Aktualisierung mit der eTLD+1 des Käufers übereinstimmt.

{
 "name": "running-shoes",
 "activation_time": 1680603133000,
 "expiration_time": 1680803133000,
 "user_bidding_signals" : {"signal1": "value"},
 "trusted_bidding_data": {
    "trusted_bidding_uri": "https://example-dsp.com/.."
    "trusted_bidding_keys": ["k1", "k2"],
 },
 "bidding_logic_uri": "https://example-dsp.com/...",
 "daily_update_uri": "https://example-dsp.com/...",
 "ads": [
   {
     "render_uri": "https://example-dsp.com/...",
     "metadata": {},
     "ad_filters": {
       "frequency_cap": {
         "win": [
           {
             "ad_counter_key": 1,
             "max_count": 2,
             "interval_in_seconds": 60
           },
         ],
         "view": [
           {
             "ad_counter_key": 2,
             "max_count": 10,
             "interval_in_seconds": 3600
           },
         ]
       },
       "app_install": {
         "package_names": [
           "package.name.one",
           "package.name.two", ...
         ]
       }
     }
   },
   ...
 ]
}

Die fetchAndJoinCustomAudience() API bestimmt die Identität des Käufers anhand der eTLD+1 von fetchUri. Die Identität des CustomAudience-Käufers wird verwendet, um dieselben Registrierungs- und App-Autorisierungsüberprüfungen durchzuführen, die auch von joinCustomAudience() durchgeführt werden. Sie kann nicht durch die Abrufantwort geändert werden. Der CustomAudience-Inhaber ist der Paketname der aufrufenden Anwendung. Für fetchUri gibt es keine andere Validierung als die eTLD+1-Prüfung. Insbesondere gibt es keine k-anon-Prüfung. Die fetchAndJoinCustomAudience() API sendet eine HTTP-GET-Anfrage an fetchUri und erwartet ein JSON-Objekt, das die benutzerdefinierte Zielgruppe darstellt. Auf die Antwort werden dieselben obligatorischen, optionalen Einschränkungen und Standardwerte für die Felder des Objekts „Benutzerdefinierte Zielgruppe“ angewendet. Aktuelle Anforderungen und Einschränkungen finden Sie in unserem Entwicklerhandbuch.

Jede HTTP-Fehlerantwort des Käufers führt zu einem Fehler bei fetchAndJoinCustomAudience. Insbesondere blockiert eine HTTP-Statusantwort 429 („Zu viele Anfragen“) Anfragen von der aktuellen Anwendung für einen zu definierenden Zeitraum. Der API-Aufruf schlägt auch fehl, wenn die Antwort des Käufers fehlerhaft ist. Fehler werden an den API-Aufrufer gemeldet, der bei vorübergehenden Fehlern (z. B. wenn der Server nicht antwortet) noch einmal versuchen oder bei dauerhaften Fehlern (z. B. bei Datenvalidierungsfehlern oder anderen nicht vorübergehenden Fehlern bei der Kommunikation mit dem Server) entsprechende Maßnahmen ergreifen muss.

Mit dem CustomAudienceFetchRequest-Objekt kann der API-Aufrufer einige Informationen für die benutzerdefinierte Zielgruppe definieren. Dazu verwendet er die optionalen Eigenschaften, die im Beispiel gezeigt werden. Wenn diese Werte in der Anfrage festgelegt sind, können sie nicht durch die vom Käufer empfangene Antwort überschrieben werden. Die Protected Audience API ignoriert die Felder in der Antwort. Wenn sie nicht in der Anfrage festgelegt sind, müssen sie in der Antwort festgelegt werden, da diese Felder zum Erstellen einer benutzerdefinierten Zielgruppe erforderlich sind. Eine JSON-Darstellung des Inhalts der CustomAudience, wie sie teilweise vom API-Aufrufer definiert wurde, ist in der GET-Anfrage an fetchUri in einem speziellen Header X-CUSTOM-AUDIENCE-DATA enthalten. Die Größe der serialisierten Form der für die benutzerdefinierte Zielgruppe angegebenen Daten ist auf 8 KB begrenzt. Wenn die Größe überschritten wird, schlägt der fetchAndJoinCustomAudience API-Aufruf fehl.

Da keine k-anon-Prüfung durchgeführt wird, können Sie fetchUri zur Überprüfung von Käufern und zum Freigeben von Informationen zwischen Käufer und SDK verwenden. Um die Überprüfung benutzerdefinierter Zielgruppen zu erleichtern, kann der Käufer ein Bestätigungstoken angeben. Das On-Device-SDK sollte dieses Token in fetchUri einschließen, damit der vom Käufer gehostete Endpunkt den Inhalt der benutzerdefinierten Zielgruppe abrufen und mithilfe des Bestätigungstokens prüfen kann, ob die fetchAndJoinCustomAudience()-Operation dem Käufer entspricht und von einem vertrauenswürdigen On-Device-Partner stammt. Wenn der Käufer Daten freigeben möchte, kann er dem On-Device-Caller zustimmen, dass einige der Informationen, die zum Erstellen der benutzerdefinierten Zielgruppe verwendet werden, der fetchUri als Abfrageparameter hinzugefügt werden. So können Käufer die Aufrufe prüfen und feststellen, ob ein Bestätigungstoken von einer schädlichen Anzeigentechnologie verwendet wurde, um mehrere verschiedene benutzerdefinierte Zielgruppen zu erstellen.

Hinweis zur Definition und Speicherung von Bestätigungstokens

• Das Bestätigungstoken wird von der Protected Audience API nicht verwendet und ist optional.

  • Mit dem Bestätigungstoken kann der Käufer prüfen, ob die erstellten Zielgruppen in seinem Namen erstellt werden.
  • Im Vorschlag für die Protected Audience API wird weder ein Format für das Bestätigungstoken noch angegeben, wie der Käufer das Bestätigungstoken an den Aufrufer übergibt. Das Bestätigungstoken kann beispielsweise im SDK oder Backend des Eigentümers vorab geladen oder vom SDK des Eigentümers in Echtzeit vom Server des Käufers abgerufen werden.

Benutzerdefinierte Zielgruppe verlassen

Der Inhaber einer benutzerdefinierten Zielgruppe kann sie verlassen, indem er leaveCustomAudience() aufruft, wie in diesem Code-Snippet dargestellt:

// Invoke ad services API to leave a custom audience.
leaveCustomAudience(buyer, name);

Um die Nutzung von Speicherplatz und anderen Geräteressourcen zu sparen, laufen benutzerdefinierte Zielgruppen nach einem bestimmten Zeitraum ab und werden aus dem On-Device-Speicher entfernt. Der Standardwert ist noch nicht festgelegt. Der Inhaber kann diesen Standardwert überschreiben.

Nutzersteuerung

• Mit dem Vorschlag soll Nutzern die Liste der installierten Apps angezeigt werden, für die mindestens eine benutzerdefinierte Zielgruppe erstellt wurde.
• Nutzer können Apps aus dieser Liste entfernen. Dadurch werden alle mit den Apps verknüpften benutzerdefinierten Zielgruppen gelöscht und die Apps können nicht mehr zu neuen benutzerdefinierten Zielgruppen hinzugefügt werden.
• Nutzer können die Protected Audience API vollständig zurücksetzen. In diesem Fall werden alle vorhandenen benutzerdefinierten Zielgruppen auf dem Gerät gelöscht.
• Nutzer können die Privacy Sandbox unter Android vollständig deaktivieren, einschließlich der Protected Audience API. Wenn der Nutzer die Privacy Sandbox deaktiviert hat, schlägt die Protected Audience API stillschweigend fehl.

Das Design dieser Funktion befindet sich noch in der Entwicklungsphase. Die Details werden in einem späteren Update veröffentlicht.

Geplante Updates

Bei den zuvor beschriebenen Lösungen müssen die APIs vom App- oder Anzeigentechnologie-SDK aufgerufen werden, während sich die App im Vordergrund befindet, und die vollständigen Eigenschaften der benutzerdefinierten Zielgruppe entweder direkt oder durch Delegierung zur Verfügung gestellt werden. Es ist jedoch nicht immer möglich, dass Werbetreibende und Anbieter von Anzeigentechnologien in Echtzeit festlegen, zu welchen Zielgruppen ein Nutzer gehört, während er die App verwendet.

Dazu kann die scheduleCustomAudienceUpdate() API aufgerufen werden. Mit dieser API kann der Aufrufer eine Verzögerung für den API-Aufruf angeben. Dadurch hat die antwortende Anzeigentechnologie mehr Zeit, Ereignisse auf App-Ebene zu verarbeiten und zu bestimmen, welchen geschützten Zielgruppen der Nutzer beitreten oder aus denen er entfernt werden soll.

/**
* API To schedule delayed update events for Custom Audience
*
* @param request Criteria that determine when and where to trigger a call to a
* DSP endpoint to update one or more Custom Audiences
*/

public void scheduleCustomAudienceUpdate(
    @NonNull ScheduleCustomAudienceUpdateRequest request,
    @NonNull @CallBackExecutor Executor executor,
    @NonNull AdServicesOutcomeReceiver<Object, Exception> receiver)

ScheduleCustomAudienceUpdateRequest

public final class ScheduleCustomAudienceUpdateRequest {
  // Required Field
  @NonNull public Uri getUpdateUri() {
    return mUpdateUri;
  }

  // Required Field
  @NonNull public Duration getMinDelay() {
    return mMinDelay;
  }

  //  Required Field
  @NonNull public List<PartialCustomAudience> getPartialCustomAudienceList() {
    return mPartialCustomAudiences;
  }

  //  Optional Field (default false)
  public boolean shouldReplacePendingUpdates () {
    return mShouldReplacePendingUpdates;
  }
}

Die ScheduleCustomAudienceUpdateRequest enthält die Informationen, die zum Registrieren eines verzögerten Jobs erforderlich sind, der auf der Plattform ausgeführt werden soll. Nach der angegebenen Verzögerung wird regelmäßig ein Hintergrundjob ausgeführt und die Anfrage(n) gesendet. ScheduleCustomAudienceUpdateRequest kann die folgenden Informationen enthalten:

• UpdateUri: URI-Endpunkt, an den ein GET-Aufruf gesendet wird, um das Update abzurufen. Die Identität des Käufers wird aus der eTLD+1 abgeleitet und muss nicht explizit angegeben werden. Sie kann auch nicht durch die Antwort auf die Aktualisierung geändert werden. Die GET-Anfrage erwartet ein JSON-Objekt mit einer Liste von customAudience-Objekten als Rückgabe.
• DelayTime: Zeit, die zwischen dem scheduleCustomAudienceUpdate() API-Aufruf und der Planung der Aktualisierung vergeht.

• PartialCustomAudience: Über die API kann das On-Device-SDK auch eine Liste teilweise erstellter benutzerdefinierter Zielgruppen senden. So können die In-App-SDKs je nach Partnerschaft mit DSPs die vollständige oder teilweise Verwaltung von benutzerdefinierten Zielgruppen übernehmen.

  • Dadurch ist diese API auch mit der fetchAndJoinCustomAudience() API kompatibel, die eine ähnliche Freigabe von Informationen ermöglicht.

• ShouldReplacePendingUpdates: Boolescher Wert, der angibt, ob ausstehende geplante Updates abgebrochen und durch das in der aktuellen ScheduleCustomAudienceUpdateRequest beschriebene Update ersetzt werden sollen. Wenn dieser Wert auf false festgelegt ist und zuvor angeforderte Updates für denselben Käufer in derselben App noch ausstehen, schlägt ein Aufruf von scheduleCustomAudienceUpdate mit dieser ScheduleCustomAudienceUpdateRequest fehl. Die Standardeinstellung ist false.

App-Berechtigungen und -Steuerung

Mit dem Vorschlag soll es Apps möglich sein, ihre benutzerdefinierten Zielgruppen zu steuern:

• Eine App kann ihre Verknüpfungen mit benutzerdefinierten Zielgruppen verwalten.
• Eine App kann Drittanbieter-Werbetechnologieplattformen Berechtigungen erteilen, benutzerdefinierte Zielgruppen in ihrem Namen zu verwalten.

Das Design dieser Funktion befindet sich noch in der Entwicklungsphase. Die Details werden in einem späteren Update veröffentlicht.

Einstellung für AdTech-Plattform

In diesem Vorschlag werden Möglichkeiten beschrieben, wie Anbieter von Anzeigentechnologien ihre benutzerdefinierten Zielgruppen verwalten können:

• Anbieter von Anzeigentechnologien registrieren sich in der Privacy Sandbox und geben eine eTLD+1-Domain an, die mit allen URLs für eine benutzerdefinierte Zielgruppe übereinstimmt.
• Anbieter von Anzeigentechnologien können mit Apps oder SDKs zusammenarbeiten, um Bestätigungstokens bereitzustellen, die zum Bestätigen der Erstellung einer benutzerdefinierten Zielgruppe verwendet werden. Wenn dieser Vorgang an einen Partner delegiert wird, kann die Erstellung benutzerdefinierter Zielgruppen so konfiguriert werden, dass eine Bestätigung durch die Anzeigentechnologie erforderlich ist.
• Anbieter von Anzeigentechnologien können joinCustomAudience-Aufrufe in ihrem Namen deaktivieren und nur der fetchAndJoinCustomAudience API erlauben, alle benutzerdefinierten Zielgruppen für Aufrufe zu aktivieren. Die Einstellung kann während der Privacy Sandbox-Registrierung aktualisiert werden. Hinweis: Mit dieser Einstellung können entweder alle oder keine Anzeigentechnologien zugelassen werden. Aufgrund von Plattformeinschränkungen können Delegierungsberechtigungen nicht pro AdTech-Anbieter festgelegt werden.

Antwort mit Anzeigen- und Metadaten für die Anzeigenauswahl

Von einer Käuferplattform zurückgegebene Anzeigen und Metadaten müssen die folgenden Felder enthalten:

• Metadaten:Käuferseitige, anbieterspezifische Anzeigenmetadaten. Dazu gehören beispielsweise Informationen zur Werbekampagne und Targeting-Kriterien wie Standort und Sprache.
• Render-URL:Endpunkt für das Rendern des Creatives.
• Filter:Optionale Informationen, die für die Protected Audience API erforderlich sind, um Anzeigen anhand von On-Device-Daten zu filtern. Weitere Informationen finden Sie im Abschnitt zur Filterlogik auf Käuferseite.

Workflow für die Anzeigenauswahl

Mit diesem Vorschlag soll der Datenschutz verbessert werden. Dazu wird die Anzeigenauswahl-API eingeführt, die die Auktionsausführung für AdTech-Plattformen koordiniert.

Auf AdTech-Plattformen werden Gebote und Anzeigenauswahl in der Regel ausschließlich auf ihren Servern durchgeführt. Bei diesem Vorschlag sind benutzerdefinierte Zielgruppen und andere vertrauliche Nutzersignale wie Informationen zu verfügbaren installierten Paketen nur über die Ad Selection API zugänglich. Zusätzlich werden für den Remarketing-Anwendungsfall Anzeigenvorschläge außerhalb des Bandes abgerufen (d.h. nicht im Kontext, in dem Anzeigen ausgeliefert werden). Anbieter von Anzeigentechnologien müssen sich darauf vorbereiten, dass einige Teile ihrer aktuellen Auktions- und Anzeigenauswahllogik auf dem Gerät bereitgestellt und ausgeführt werden. Anbieter von Anzeigentechnologien können die folgenden Änderungen an ihrem Workflow für die Anzeigenauswahl in Betracht ziehen:

• Wenn auf dem Server keine Informationen zu installierten Paketen verfügbar sind, können Anbieter von Anzeigentechnologien mehrere kontextbezogene Anzeigen an das Gerät zurücksenden und den Workflow für die Anzeigenauswahl aufrufen, um die Wahrscheinlichkeit zu erhöhen, dass eine relevante Anzeige ausgeliefert wird.
• Da Remarketing-Anzeigen nicht über das normale Auktionssystem abgerufen werden, müssen die aktuellen Gebotsmodelle möglicherweise aktualisiert werden. Anbieter von Anzeigentechnologien können Gebotsuntermodelle erstellen (die Implementierung kann auf einem Muster basieren, das als Two-Tower-Modell bezeichnet wird), die Anzeigenfunktionen und Kontextsignale separat verarbeiten und die Ausgaben der Untermodelle auf dem Gerät kombinieren, um Gebote vorherzusagen. Dabei können sowohl serverseitige Auktionen als auch Auktionen für eine bestimmte Anzeigenbereitstellung genutzt werden.

So können die Daten zu App-Interaktionen des Nutzers bei der Anzeigenauswahl berücksichtigt werden, während die Weitergabe dieser Daten an Dritte eingeschränkt wird.

Bei diesem Workflow für die Anzeigenauswahl wird die On-Device-Ausführung von von der Anzeigentechnologie bereitgestelltem JavaScript-Code anhand der folgenden Abfolge orchestriert:

1. Ausführung der Gebotslogik auf Käuferseite
2. Anzeigenfilterung und ‑verarbeitung auf Käuferseite
3. Ausführung der Entscheidungslogik auf Verkäuferseite

Bei Anzeigenauswahlen mit benutzerdefinierten Zielgruppen ruft die Plattform den von der Buy-Side bereitgestellten JavaScript-Code basierend auf dem öffentlichen URL-Endpunkt ab, der in den Metadaten „URL der Gebotslogik“ der benutzerdefinierten Zielgruppe definiert ist. Der URL-Endpunkt für den entscheidungsseitigen Code wird ebenfalls als Eingabe übergeben, um den Workflow für die Anzeigenauswahl zu starten.

Die Entwicklung von Anzeigenausschlüssen ohne benutzerdefinierte Zielgruppen ist in vollem Gange.

Workflow für die Anzeigenauswahl starten

Wenn in einer App eine Anzeige ausgeliefert werden muss, kann das SDK der Anzeigentechnologieplattform den Workflow zur Anzeigenauswahl initiieren, indem es die Methode selectAds() aufruft, nachdem das AdSelectionConfig-Objekt mit den erwarteten Parametern instanziiert wurde:

• Verkäufer: Kennung für die Sell-Side-Werbeplattform im Format „eTLD+1“
• URL der Entscheidungslogik: Wenn eine Anzeigenauktion gestartet wird, ruft die Plattform über diese URL JavaScript-Code von der Sell-Side-Plattform ab, um die Gewinneranzeige zu ermitteln.
• Käufer mit benutzerdefinierten Zielgruppen: Eine Liste von Buy-Side-Plattformen mit benutzerdefinierter, auf Zielgruppen basierender Nachfrage für diese Auktion im Format „eTLD+1“.
• Signale für die Anzeigenauswahl: Informationen zur Auktion (Anzeigengröße, Anzeigenformat usw.).
• Verkäufersignale: Sell-Side-Plattform-spezifische Signale.
• URL für vertrauenswürdige Bewertungssignale: URL-Endpunkt eines vertrauenswürdigen Signals der Sell-Side, von dem aus kreative Echtzeitinformationen abgerufen werden können.
• Per-Buyer-Signale: Teilnehmende Nachfrageseiten können diesen Parameter verwenden, um Eingaben für die Auktion bereitzustellen. Dieser Parameter kann beispielsweise umfassende Kontextinformationen enthalten, die für die Gebotsbestimmung nützlich sind.

Im folgenden Code-Snippet wird ein SDK einer Anzeigentechnologieplattform dargestellt, das den Anzeigenauswahl-Workflow initiiert, indem zuerst AdSelectionConfig definiert und dann selectAds aufgerufen wird, um die ausgewählte Anzeige zu erhalten:

AdSelectionConfig myAdSelectionConfig = new AdSelectionConfig {
    Seller = "example-ssp1.com",
    DecisionLogicURL = Uri.parse("https://..."),
    CustomAudienceBuyerList = Arrays.asList("example-dsp1.com","bexample-dsp2.com"),
    AdSelectionSignals = "{"min_price": 10,"auction_attempts": 3}"
    SellerSignals = "{"seller_type": "news", "content_category": "sports","mature_ads_accepted" :"false"}"
    PerBuyerSignals = " {"buyer1Name": {"key1" : "value1"},
                         "buyer2Name": {"key1" : "value1", "key2" : "value2" }"
};

// Invoke ad services API to initiate ad selection workflow.
Ad winningAd = selectAds(myAdSelectionConfig);

Logik für Gebote auf der Buy-Side

Die Gebotslogik wird in der Regel von Buy-Side-Plattformen bereitgestellt. Der Code dient dazu, Gebote für infrage kommende Anzeigen zu bestimmen. Es kann zusätzliche Geschäftslogik zur Bestimmung des Ergebnisses angewendet werden.

Die Plattform verwendet die Metadaten „URL der Gebotslogik“ der benutzerdefinierten Zielgruppe, um den JavaScript-Code abzurufen. Dieser sollte die folgende Funktionssignatur enthalten:

generateBid(ad, auction_signals, per_buyer_signals, trusted_bidding_signals,
        contextual_signals, user_signals, custom_audience_signals) {
    // ...
    return {'bid': ...};
}

Die Methode generateBid() gibt den berechneten Gebotsbetrag zurück. Die Plattform ruft diese Funktion nacheinander für alle Anzeigen (kontextbezogen oder Remarketing) auf. Wenn es mehrere Anbieter von Gebotslogik gibt, kann das System die Ausführungsreihenfolge der Anbieter nicht garantieren.

Die Funktion erwartet die folgenden Parameter:

• Anzeige: Die Anzeige, die vom Code für Gebote auf der Buy-Side berücksichtigt wird. Das ist eine Anzeige aus einer geeigneten benutzerdefinierten Zielgruppe.
• Auktionssignale: Plattformspezifische Signale auf Verkäuferseite.
• Per-Buyer-Signale: Teilnehmende Nachfrageseiten können diesen Parameter verwenden, um Eingaben für die Auktion bereitzustellen. Dieser Parameter kann beispielsweise umfassende Kontextinformationen enthalten, die für die Gebotsbestimmung nützlich sind.
• Vertrauenswürdige Gebotsignale: Anzeigentechnologie-Plattformen nutzen Echtzeitdaten, um die Anzeigenabfrage und -bewertung zu optimieren. Beispielsweise kann das Budget einer Werbekampagne aufgebraucht sein und die Anzeigenauslieferung muss sofort beendet werden. Eine Anzeigentechnologie kann einen URL-Endpunkt definieren, von dem diese Echtzeitdaten abgerufen werden können, und die Schlüssel, für die die Echtzeitsuche durchgeführt werden muss. Der verwaltete Server der Anzeigentechnologieplattform, der diese Anfrage ausführt, ist ein vertrauenswürdiger Server, der von der Anzeigentechnologieplattform verwaltet wird.
• Kontextsignale: Dazu gehören grobe Zeitstempel, ungefähre Standortinformationen oder Kosten pro Anzeigenklick.
• Nutzersignale: Dazu gehören unter anderem Informationen zu verfügbaren installierten Paketen.

Werbekosten

Zusätzlich zum Gebot haben Plattformen auf Käuferseite die Möglichkeit, den Cost-per-Click als Teil von generateBid() zurückzugeben. Beispiel:

generateBid(ad, auction_signals, per_buyer_signals, trusted_bidding_signals,
        contextual_signals, user_signals, custom_audience_signals) {
    // ...
    return {'bid': ..., 'adCost': ...,};
}

Wenn diese Anzeige ausgewählt wird, wird adCost aus Datenschutzgründen stochastisch auf 8 Bit gerundet. Der gerundete Wert von adCost wird dann in den Parameter contextual_signals in reportWin in Berichten zu Impressionen übergeben.

Buy-Side-Filterlogik

Auf der Buy-Side können Anzeigen anhand zusätzlicher On-Device-Signale gefiltert werden, die während der Anzeigenauswahlphase verfügbar sind. Beispielsweise können Anbieter von Anzeigentechnologien hier Funktionen für das Frequency Capping implementieren. Wenn es mehrere Filteranbieter gibt, kann das System die Ausführungsreihenfolge der Anbieter nicht garantieren.

Die Filterlogik auf Käuferseite kann als Teil der Gebotslogik implementiert werden, indem für eine bestimmte Anzeige ein Gebotswert von 0 zurückgegeben wird.

Außerdem können Buy-Side-Plattformen signalisieren, dass eine bestimmte Anzeige basierend auf zusätzlichen On-Device-Signalen gefiltert werden soll, die für Protected Audience verfügbar sind und das Gerät nicht verlassen. Sobald wir die Designs der zusätzlichen Filterlogik fertiggestellt haben, folgen auch Kaufplattformen dieser Struktur, um anzuzeigen, dass die Filterung erfolgen soll.

Sell-Side-Bewertungslogik

Die Bewertungslogik wird in der Regel von der Sell-Side-Plattform bereitgestellt. Der Code dient dazu, anhand der Gebotlogik-Ausgaben die Anzeigen auszuwählen, die ausgeliefert werden sollen. Es kann sein, dass zusätzliche Geschäftslogik zur Bestimmung des Ergebnisses angewendet wird. Wenn es mehrere Anbieter von Entscheidungslogik gibt, kann das System die Ausführungsreihenfolge der Anbieter nicht garantieren. Die Plattform verwendet den Eingabeparameter „URL der Entscheidungslogik“ der selectAds() API, um den JavaScript-Code abzurufen, der die folgende Funktionssignatur enthalten sollte:

scoreAd(ad, bid, auction_config, trusted_scoring_signals,
        contextual_signals, user_signals, custom_audience_signals) {
    // ...
    return score_for_this_ad;
}

Die Funktion erwartet die folgenden Parameter:

• Anzeigen: Die zu bewertende Anzeige; Ausgabe der Funktion generateBid().
• Gebot: Gebotsbetrag, der von der Funktion generateBid() ausgegeben wird.
• Auktionskonfiguration: Eingabeparameter für die selectAds()-Methode.
• Vertrauenswürdige Bewertungssignale: Anzeigentechnologie-Plattformen nutzen Echtzeitdaten für die Anzeigenfilterung und -bewertung. Ein App-Publisher kann beispielsweise verhindern, dass Anzeigen einer Werbekampagne in der App ausgeliefert werden. Diese Daten werden aus dem URL-Parameter für vertrauenswürdige Bewertungssignale der Auktionskonfiguration abgerufen. Der Server, der diese Anfrage ausführt, sollte ein von der Anzeigentechnologie verwalteter vertrauenswürdiger Server sein.
• Kontextsignal: Dazu können grobe Zeitstempel oder ungefähre Standortinformationen gehören.
• Nutzersignal: Dazu gehören möglicherweise Informationen wie der App-Shop, über den die Installation der App gestartet wurde.
• Signal für benutzerdefinierte Zielgruppen: Wenn die benotete Anzeige aus einer benutzerdefinierten Zielgruppe auf dem Gerät stammt, enthält sie Informationen wie den Leser und den Namen der benutzerdefinierten Zielgruppe.

Laufzeit des Anzeigenauswahlcodes

Im Gebot ruft das System den von der AdTech-Plattform bereitgestellten Auktionscode von konfigurierbaren URL-Endpunkten ab und führt ihn auf dem Gerät aus. Aufgrund der Ressourceneinschränkungen auf Mobilgeräten muss Auktionscode den folgenden Richtlinien entsprechen:

• Die Ausführung des Codes sollte innerhalb einer vordefinierten Zeit abgeschlossen sein. Diese Grenze gilt einheitlich für alle Werbenetzwerke von Käufern. Details zu dieser Begrenzung werden in einem späteren Update bekannt gegeben.
• Der Code muss in sich geschlossen sein und keine externen Abhängigkeiten haben.

Da der Auktionscode, z. B. die Gebotslogik, möglicherweise Zugriff auf private Nutzerdaten wie App-Installationsquellen benötigt, stellt die Laufzeit keinen Netzwerk- oder Speicherzugriff bereit.

Programmiersprache

Der von der AdTech-Plattform bereitgestellte Auktionscode muss in JavaScript geschrieben sein. So können Anbieter von Anzeigentechnologien beispielsweise Gebotskode für Plattformen freigeben, die die Privacy Sandbox unterstützen.

Erfolgreiches Anzeigen-Rendering

Die Anzeige mit der höchsten Punktzahl gilt als Gewinner der Auktion. In diesem ersten Vorschlag wird die Gewinneranzeige zum Rendern an das SDK übergeben.

Wir planen, die Lösung so weiterzuentwickeln, dass Informationen zur Zugehörigkeit zu einer benutzerdefinierten Zielgruppe oder zum App-Interaktionsverlauf eines Nutzers nicht über Informationen zur ausgelieferten Anzeige von der App oder dem SDK ermittelt werden können (ähnlich dem Fenced Frames-Vorschlag von Chrome).

Berichte zu Impressionen und Ereignissen

Sobald die Anzeige gerendert wurde, kann die erfolgreiche Impression an die teilnehmenden Plattformen auf Käufer- und Verkäuferseite zurückgemeldet werden. So können Käufer und Verkäufer Informationen aus der Auktion, z. B. das Gebot oder den Namen der benutzerdefinierten Zielgruppe, in den Bericht zur gewonnenen Impression aufnehmen. Außerdem haben die Plattform auf Verkäuferseite und die Gewinnerplattform auf Käuferseite Anspruch auf zusätzliche Berichte auf Ereignisebene zur Gewinneranzeige. So können Sie Informationen zur Auktion (Gebot, Name der benutzerdefinierten Zielgruppe usw.) mit Klicks, Aufrufen und anderen Anzeigenereignissen verknüpfen. Die Plattform ruft die Berichtslogik in der folgenden Reihenfolge auf:

1. Berichte für die Sell-Side
2. Berichte für die Käuferseite

So können Buy-Side- und Sell-Side-Plattformen wichtige On-Device-Informationen an die Server zurücksenden, um Funktionen wie Echtzeitbudgetierung, Aktualisierungen des Gebotsmodells und genaue Abrechnungsabläufe zu ermöglichen. Diese Unterstützung für Impressionsberichte ergänzt die Attribution Reporting API.

Für die Unterstützung von Ereignisberichten sind zwei Schritte erforderlich: Sell-Side- und Buy-Side-JavaScript muss registrieren, für welches Ereignis Ereignisberichte empfangen werden sollen, und die Sell-Side ist für die Berichterstellung auf Ereignisebene verantwortlich.

Protected Audience bietet einen Mechanismus, mit dem Sie zukünftige Ereignisse im Zusammenhang mit einer Gewinner-Auktion abonnieren können, indem Sie Beacons registrieren. In der reportResult()-JavaScript-Funktion eines Verkäufers können Plattformen auf Verkäuferseite Beacons mithilfe der registerAdBeacon()-Funktion der Plattform registrieren. Ebenso können Buy-Side-Plattformen die registerAdBeacon()-Methode über ihre reportWin()-JavaScript-Funktion aufrufen.

registerAdBeacon(beacons)

Eingabe:

• event_key: Ein String, der angibt, für welchen Interaktionstyp eine Registrierung erfolgen soll. Dieser Wert wird als Schlüssel verwendet, um den Endpunkt abzurufen, den die Plattform anpingt, während sie die Ergebnisse der Auktion meldet.
• reporting_url: Die URL der AdTech-Plattform, über die das Ereignis verarbeitet wird.

Ereignisschlüssel sind String-IDs, die zum SDK auf der Sell-Side gehören, das für die Berichterstellung der Auktionsergebnisse verantwortlich ist. Damit ein Callback ausgeführt werden kann, müssen Anbieter von Anzeigentechnologien Beacons mit Schlüsseln registrieren, die mit den Schlüsseln übereinstimmen, die die Sell-Side-Anbieter beim Melden der Ereignisse verwenden. Sie müssen nicht k-anonym sein. Es gibt jedoch Einschränkungen hinsichtlich der Anzahl und Länge der Schlüssel, die für eine bestimmte benutzerdefinierte Zielgruppe registriert werden können. Wenn reportEvent() aufgerufen wird, können Plattformen auf der Sell-Side, die die Auktion durchgeführt haben, diese Ereignisberichte immer erhalten. Nur die ausgewählte Buy-Side-Plattform kann diese Berichte erhalten.

Berichte für die Sell-Side

Die Plattform ruft die JavaScript-Funktion reportResult() im von der Angebotsseite bereitgestellten Code auf, der über den Parameter Decision logic URL des Verkäufers für die selectAds() API heruntergeladen wurde:

reportResult(render_url, bid, auction_config, contextual_signals) {
    // ...
    beacons = {"click":clickUri}
    registerAdBeacon(beacons)
    return {
      "status": 0,
      "results": {"reporting_url": reporting_url,
                  "signals_for_buyer": signals_for_buyer}};
}

Ausgabe: Ein JSON-Objekt mit

• Status: 0 für Erfolg, jeder andere Wert für Fehler.
• Berichts-URL: Die Plattform ruft diese URL auf, die von der Funktion zurückgegeben wird.
• Signale für Käufer: Ein JSON-Objekt, das an die reportWin-Funktion des Käufers übergeben wird.

Die Angebotsseite kann relevante Signale in die Berichts-URL codieren, um weitere Informationen zur Auktion und zur Gewinneranzeige zu erhalten. Beispiele für solche Signale:

• URL für das Rendern der Anzeige
• Betrag des erfolgreichen Gebots
• App-Name
• Abfrage-IDs
• Signale für Käufer: Zur Unterstützung der Datenfreigabe zwischen Angebots- und Nachfrageseite gibt die Plattform diesen Rückgabewert als Eingabeparameter an den Berichtscode für die Nachfrageseite weiter.

Berichte für Käufer

Die Plattform ruft die reportWin()-JavaScript-Funktion im von der Nachfrageseite bereitgestellten Code auf, der aus den Metadaten der URL der Gebotslogik der benutzerdefinierten Zielgruppe heruntergeladen wurde, die mit der Auktion verknüpft ist.

reportWin(render_url, bid, auction_signals, per_buyer_signals,
        signals_for_buyer, contextual_signals, custom_audience_signals) {
    // ...
    beacons = {"click":clickUri}
    registerAdBeacon(beacons)
    return {
      "status": 0,
      "results": {"reporting_uri": reporting_uri}};
}

Eingabe:

• auction_signals und per_buyer_signals werden aus AuctionConfig abgerufen. Alle Informationen, die die Buy-Side-Plattform an die Berichts-URL übergeben muss, können aus diesem Datum stammen.
• signals_for_buyer ist das Ergebnis des Berichts „Sell-Side ReportResult“. So kann die Sell-Side-Plattform Daten zu Berichtszwecken mit der Buy-Side-Plattform teilen.
• contextual_signals enthält Informationen wie den App-Namen und custom_audience_signals die Informationen zur benutzerdefinierten Zielgruppe. Weitere Informationen werden möglicherweise in Zukunft hinzugefügt.

Ausgabe:

• Status: 0 für Erfolg, jeder andere Wert für Fehler.
• Berichts-URL: Die Plattform ruft diese URL auf, die von der Funktion zurückgegeben wird.

Ereignisse melden

Ereignisse können erst dann erfasst werden, wenn die Impressionsberichte für die Auktion abgeschlossen sind. Das Sell-Side-SDK ist für die Berichterstellung zu allen Ereignissen verantwortlich. Die Plattform stellt eine API bereit, die eine ReportEventRequest annimmt, in der die kürzlich durchgeführte Auktion, der gemeldete Ereignisschlüssel, die mit diesem Schlüssel verknüpften Daten, ob der Bericht an den Käufer oder den Verkäufer (oder beide) gesendet werden soll, und ein optionales Eingabeereignis für Anzeigenereignisse angegeben werden. Der Kunde definiert den Ereignisschlüssel und die Datenerhebung, die erfasst werden sollen.

ReportEventRequest request = new ReportEventRequest(
  AdSelectionId = ad_selection_id,
  event_key = "view"
  event_data = "{ "viewTimeInSeconds" :1 }",
  reporting_destinations =
    FLAG_REPORTING_DESTINATION_SELLER |
      FLAG_REPORTING_DESTINATION_BUYER,
  input_event = clickInputEvent // or null for view
  )

reportEvent(request)

Eingabe:

• ad_selection_id muss ein AdSelectionId einer kürzlich durchgeführten Auktion sein, das aus der AdSelectionOutcome abgerufen wurde.
• event_key ist ein von der Sell-Side definierter String, der das Interaktionsereignis beschreibt.
• event_data ist ein String, der die mit event_key verknüpften Daten darstellt.
• reporting_destinations ist eine Bitmaske, die mithilfe von Flags der Plattform festgelegt wird. Es kann entweder FLAG_REPORTING_DESTINATION_SELLER oder FLAG_REPORTING_DESTINATION_BUYER oder beides sein.
• input_event (optional) wird für die Integration mit der Attribution Reporting API verwendet. Es ist entweder ein InputEvent-Objekt (für ein Klickereignis) oder „null“ (für ein Aufrufereignis). Weitere Informationen zu diesem Parameter finden Sie unter Attribution Reporting API-Integration.

Nachdem das SDK auf der Sell-Side reportEvent aufgerufen hat, versucht die Plattform je nach reporting_destinations-Flag, die event_key mit den von Käufern und Verkäufern in ihren reportWin- und reportResult-JavaScript-Funktionen registrierten Schlüsseln abzugleichen. Wenn eine Übereinstimmung vorliegt, POSTet die Plattform die event_data an die zugehörige reporting_url. Die content type der Anfrage ist reiner Text und der Textkörper ist die event_data. Diese Anfrage wird nach dem Best-Effort-Prinzip gesendet und schlägt bei einem Netzwerk- oder Serverfehler oder wenn keine übereinstimmenden Schlüssel gefunden wurden, stillschweigend fehl.

Integration der Attribution Reporting API

Um Käufer zu unterstützen, die an einer Protected Audience-Auktion teilnehmen, bieten wir API-übergreifende Funktionen für die Protected Audience API und die Attribution Reporting API (ARA). Mit dieser Funktion können Anbieter von Anzeigentechnologien ihre Attributionsleistung für verschiedene Remarketing-Taktiken bewerten, um zu ermitteln, mit welchen Zielgruppentypen der höchste ROI erzielt wird.

Durch diese API-übergreifende Integration haben Anbieter von Anzeigentechnologien folgende Möglichkeiten:

• Erstellen Sie eine Schlüssel/Wert-Zuordnung von URIs, die sowohl für 1) Berichte zu Anzeigeninteraktionen als auch für 2) die Quellenregistrierung verwendet werden soll.
• Fügen Sie Auktionsdaten aus der Protected Audience-Auktion in die Quellschlüsselzuordnung für aggregierte Zusammenfassungsberichte ein (mit der Attribution Reporting API). Weitere Informationen finden Sie im ARA-Designvorschlag.

Wenn ein Nutzer eine Anzeige sieht oder darauf klickt:

• Die URL, über die diese Ereignisinteraktionen mithilfe der Protected Audience API erfasst werden, enthält die erforderlichen Daten, mit denen der Käufer einen Aufruf oder Klick als berechtigte Quelle über die Attribution Reporting API registrieren kann.
• Die Anzeigentechnologie kann CustomAudience (oder andere relevante kontextbezogene Informationen zur Anzeige wie Anzeigen-Placement oder Wiedergabedauer) über diese URL übergeben, damit diese Metadaten in Zusammenfassungsberichte übernommen werden, wenn die Anzeigentechnologie die Gesamtleistung der Kampagne überprüft.

Quellenregistrierung aktivieren

reportEvent() akzeptiert einen neuen optionalen Parameter InputEvent. Gewonnene Käufer, die Anzeigen-Beacons registrieren, können auswählen, welche reportEvent-Berichte bei Attribution Reporting APIs als registrierte Quelle registriert werden. Der Anfrageheader „Attribution-Reporting-Eligible“ wird allen Ereignisberichtsanfragen hinzugefügt, die von reportEvent() gesendet werden. Alle Antworten mit entsprechenden ARA-Headern werden wie jede andere reguläre Antwort auf die Registrierung einer ARA-Quelle geparst. Informationen zum Registrieren einer Quell-URL

Da ARA auf Android-Geräten Aufruf- und Klickereignisse unterstützt, wird InputEvents verwendet, um zwischen den beiden Typen zu unterscheiden. Genau wie bei der Registrierung von ARA-Quellen wird von der reportEvent() API ein von der Plattform verifiziertes InputEvent als Klickereignis interpretiert. Wenn InputEvent fehlt, null ist oder ungültig ist, wird die Quellregistrierung als Datenansicht betrachtet.

Hinweis: Die eventData nach der Auktion kann vertrauliche Daten enthalten. Daher wird die eventData in Anfragen zur Registrierung von weitergeleiteten Quellen von der Plattform entfernt.

Beispiel für Berichte zu Interaktionen und Conversions

In diesem Beispiel betrachten wir die Situation aus der Perspektive eines Käufers, der die Daten aus der Auktion, der gerenderten Anzeige und der Conversion-App verknüpfen möchte.

Bei diesem Workflow koordiniert der Käufer mit dem Verkäufer, dass eine eindeutige ID an die Auktion gesendet wird. Während der Auktion sendet der Käufer diese eindeutige ID mit den Auktionsdaten. Während des Renderings und der Conversion werden die Daten aus der gerenderten Anzeige ebenfalls mit derselben eindeutigen ID gesendet. Später können Sie diese Berichte anhand der eindeutigen ID verknüpfen.

Ablauf: Vor Beginn der Auktion sendet der Käufer im Rahmen seiner programmatischen Gebotsantwort für Echtzeitgebote („RTB“) eine eindeutige ID an den Verkäufer. Die ID kann als Variable wie auctionId festgelegt werden. Die ID wird im auctionConfig als perBuyerSignals übergeben und ist in der Gebotslogik des Käufers verfügbar.

1. Während der Ausführung von reportWin kann der Käufer ein Anzeigen-Beacon registrieren, das beim Rendern der Anzeige und bei bestimmten Interaktionsereignissen (registerAdBeacon()) ausgelöst wird. Wenn Sie Auktionssignale mit einem Anzeigenereignis verknüpfen möchten, legen Sie auctionId als Suchparameter der Beacon-URL fest.
2. Während der Anzeigendarstellung können die Beacons, die Sie während der Auktion registriert haben, ausgelöst oder mit Daten auf Ereignisebene ergänzt werden. Der Verkäufer muss reportEvent() auslösen und die Daten auf Ereignisebene übergeben. Die Plattform sendet einen Ping an die registrierte Anzeigen-Beacon-URL des Käufers, die mit der ausgelösten reportEvent() übereinstimmt.
3. Der Käufer registriert die Anzeige bei der Attribution Reporting API, indem er auf die Anzeigen-Beacon-Anfragen mit dem Attribution-Reporting-Register-Source-Header antwortet. Wenn Sie Auktionssignale für ein Conversion-Ereignis verknüpfen möchten, setzen Sie die auctionId in der Register source URL.

Am Ende dieses Prozesses hat der Käufer einen Auktionsbericht, einen Interaktionsbericht und einen Conversion-Bericht, die anhand der eindeutigen ID miteinander in Beziehung gesetzt werden können.

Ein ähnlicher Workflow gilt für einen Verkäufer, wenn er Zugriff auf Attributionsdaten benötigt. Der Verkäufer kann auch eine eindeutige ID verwenden, die mit registerAdBeacon() gesendet wird. Der reportEvent()-Aufruf enthält eine Ziel-Property, mit der der Bericht sowohl an den Käufer als auch an den Verkäufer gesendet werden kann.

Von der Anzeigentechnologieplattform verwalteter vertrauenswürdiger Server

Für die Anzeigenauswahllogik werden derzeit Echtzeitinformationen wie der Status der Budgetausschöpfung benötigt, um zu bestimmen, ob Anzeigen für die Auktion ausgewählt werden sollen. Sowohl Demand-Side- als auch Sell-Side-Plattformen können diese Informationen von den von ihnen betriebenen Servern abrufen. Um das Risiko von Datenlecks auf diesen Servern zu minimieren, sieht der Vorschlag die folgenden Einschränkungen vor:

• Das Verhalten dieser Server, das weiter unten in diesem Abschnitt beschrieben wird, würde keine Nutzerdaten preisgeben.
• Die Server erstellen keine pseudonymen Profile anhand der Daten, die sie sehen. Sie müssen also „vertraulich“ sein.

Buy-Side: Sobald die Buy-Side-Gebotslogik initiiert wurde, führt die Plattform einen HTTP-Abruf von vertrauenswürdigen Gebotsdaten vom vertrauenswürdigen Server aus. Die URL wird durch Anhängen der URL und Schlüssel erstellt, die in den Metadaten der Trusted Bidding-Signale der verarbeiteten benutzerdefinierten Zielgruppe enthalten sind. Diese Abfrage erfolgt nur bei der Verarbeitung von Anzeigen aus den benutzerdefinierten Zielgruppen auf dem Gerät. In dieser Phase können Käuferseite-Nutzer Budgets erzwingen, den Status der Kampagnenunterbrechung prüfen, das Targeting vornehmen usw.

Dies ist eine Beispiel-URL zum Abrufen von Daten für vertrauenswürdige Gebote, die auf Metadaten von Signalen für vertrauenswürdige Gebote aus der benutzerdefinierten Zielgruppe basieren:

https://www.kv-server.example/getvalues?keys=key1,key2

Die Antwort des Servers sollte ein JSON-Objekt mit den Schlüsseln „Schlüssel1“, „Schlüssel2“ usw. sein, deren Werte den Gebotsfunktionen des Käufers zur Verfügung gestellt werden.

Sell-Side: Ähnlich wie bei diesem Ablauf auf der Buy-Side kann die Sell-Side-Seite Informationen zu Creatives abrufen, die bei der Auktion berücksichtigt werden. Ein Publisher kann beispielsweise aus Gründen der Markensicherheit festlegen, dass bestimmte Creatives in seiner App nicht ausgeliefert werden dürfen. Diese Informationen können abgerufen und der Auktionslogik auf der Sell-Side zur Verfügung gestellt werden. Ähnlich wie bei der Suche nach vertrauenswürdigen Servern auf Käuferseite erfolgt auch die Suche nach vertrauenswürdigen Servern auf Verkäuferseite über einen HTTP-Abruf. Die URL wird gebildet, indem an die URL für vertrauenswürdige Bewertungssignale die Render-URLs der Creatives angehängt werden, für die die Daten abgerufen werden müssen.

Im Folgenden finden Sie eine Beispiel-URL, mit der Sie Informationen zu Creatives abrufen können, die bei der Auktion berücksichtigt werden. Die Informationen basieren auf den Creative-Render-URLs:

https://www.kv-server.example/getvalues?renderUrls=render_url1,render_url2

Die Antwort vom Server sollte ein JSON-Objekt sein, dessen Schlüssel die in der Anfrage gesendeten Render-URLs sind.

Diese Server würden auf vertrauenswürdige Weise betrieben und bieten mehrere Vorteile in Bezug auf Sicherheit und Datenschutz:

• Der Rückgabewert des Servers für jeden Schlüssel basiert nur auf diesem Schlüssel.
• Auf dem Server wird kein Logging auf Ereignisebene durchgeführt.
• Auf dem Server treten aufgrund dieser Anfragen keine anderen Nebenwirkungen auf.

Als vorübergehenden Mechanismus können Käufer und Verkäufer diese Gebotssignale von einem beliebigen Server abrufen, auch von einem von ihnen selbst betriebenen. In der Releaseversion wird die Anfrage jedoch nur an einen vertrauenswürdigen Server vom Typ „Schlüssel/Wert“ gesendet.

Käufer und Verkäufer könnten einen gemeinsamen vertrauenswürdigen Server vom Typ „Schlüssel/Wert“ für Plattformen verwenden, die mit der Privacy Sandbox für Android und das Web kompatibel sind.