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

Letzte Updates

• Informationen zum Planen von Aktualisierungen benutzerdefinierter Zielgruppen hinzugefügt
• Attribution Reporting-Integration mit Protected Audiences hinzugefügt
• Wir haben eine Zeitachse für Protected Audience-Funktionen veröffentlicht.
• FLEDGE wurde in Protected Audience API umbenannt.
• Es wurde ein Vorschlag für die Delegierung benutzerdefinierter Zielgruppen hinzugefügt.
• Die Anforderung zur k-Anonymität für die URL für tägliche Updates 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 auf Grundlage früherer Nutzeraktionen verwalten
• On-Device-Auktionen mit Unterstützung für einen einzelnen Verkäufer oder Waterfall-Vermittlung starten
• Berichterstellung zu Trainingseindrücken nach der Anzeigenauswahl.

Lesen Sie zuerst den Entwicklerleitfaden für Protected Audience. Wir freuen uns über Ihr Feedback, da wir Protected Audience weiterentwickeln.

Zeitachse

In den kommenden Monaten werden wir neue Funktionen einführen. Die genauen Veröffentlichungsdaten variieren je nach Funktion. Diese Tabelle wird mit Links zur Dokumentation aktualisiert, sobald sie verfügbar ist.

Übersicht

Bei mobiler Werbung müssen Werbetreibende häufig Anzeigen für Nutzer schalten, die möglicherweise Interesse haben, basierend darauf, wie sie zuvor mit der App des Werbetreibenden interagiert haben. Der Entwickler von SportingGoodsApp möchte beispielsweise Anzeigen für Nutzer schalten, die Artikel im Einkaufswagen belassen haben, um sie daran zu erinnern, den Kauf abzuschließen. In der Branche wird dieses allgemeine Konzept häufig mit Begriffen wie „Remarketing“ und „Targeting auf benutzerdefinierte Zielgruppen“ beschrieben.

Derzeit werden diese Anwendungsfälle in der Regel durch die Weitergabe von Kontextinformationen zur Anzeigenauslieferung (z. B. App-Name) und privaten Informationen wie Zielgruppenlisten an Ad-Tech-Plattformen umgesetzt. Anhand dieser Informationen können Werbetreibende relevante Anzeigen auf ihren Servern auswählen.

Die Protected Audience API für Android (früher FLEDGE) umfasst die folgenden APIs für Ad-Tech-Plattformen und Werbetreibende, um gängige interaktionsbasierte Anwendungsfälle zu unterstützen und gleichzeitig die Weitergabe von Kennungen zwischen Apps und von Informationen zur App-Interaktion eines Nutzers an Dritte einzuschränken:

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 infrage kommenden Anzeigen für die Zielgruppe und beliebigen Metadaten wie Gebotssignalen verknüpft werden. Die Informationen können für Gebote von Werbetreibenden, das Filtern von Anzeigen und das Rendering verwendet werden.
2. Ad Selection API: Diese API bietet ein Framework, das die Workflows von Ad-Tech-Plattformen orchestriert, die On-Device-Signale verwenden, um eine „Gewinneranzeige“ zu ermitteln. Dabei werden lokal gespeicherte Kandidatenanzeigen berücksichtigt und zusätzliche Verarbeitungsschritte für Kandidatenanzeigen durchgeführt, die eine Ad-Tech-Plattform an das Gerät zurückgibt.

Auf übergeordneter Ebene funktioniert die Integration so:

1. SportingGoodsApp möchte Nutzer daran erinnern, Merchandising-Artikel in ihrem Einkaufswagen zu kaufen, 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, wodurch die Weitergabe an Dritte eingeschränkt wird. SportingGoodsApp arbeitet mit einer Ad-Tech-Plattform zusammen, um Nutzern in der Zielgruppenliste Anzeigen zu präsentieren. Die Ad-Tech-Plattform verwaltet Metadaten für Zielgruppenlisten und stellt infrage kommende Anzeigen bereit, die im Workflow zur Anzeigenauswahl berücksichtigt werden. Die Plattform kann so konfiguriert werden, dass regelmäßig aktualisierte zielgruppenbasierte Anzeigen im Hintergrund abgerufen werden. So bleibt die Liste der zielgruppenbasierten Kandidatenanzeigen aktuell und unabhängig von Anfragen, die während der Anzeigenmöglichkeit an Ad-Server von Drittanbietern gesendet werden (z.B. kontextbezogene Anzeigenanfrage).

2. Wenn der Nutzer das FrisbeeGame auf demselben Gerät spielt, wird ihm möglicherweise eine Anzeige präsentiert, in der er daran erinnert wird, den Kauf der Artikel im Einkaufswagen der SportingGoodsApp abzuschließen. Dies kann erreicht werden, indem FrisbeeGame (mit einem integrierten Ads SDK) die Ad Selection API aufruft, um eine Gewinneranzeige für den Nutzer basierend auf einer beliebigen Zielgruppenliste auszuwählen, der er angehört (in diesem Beispiel die benutzerdefinierte Zielgruppe „Produkte im Warenkorb“, die von SportingGoodsApp erstellt wurde). Der Workflow für die Anzeigenauswahl kann so eingerichtet werden, dass Anzeigen berücksichtigt werden, die von den Servern von Ad-Tech-Plattformen abgerufen werden. Dies gilt zusätzlich zu On-Device-Anzeigen, die mit den benutzerdefinierten Zielgruppen verknüpft sind, sowie anderen On-Device-Signalen. Der Workflow kann auch von der Ad-Tech-Plattform und dem Ads SDK mit benutzerdefinierten Gebots- und Scoring-Logiken angepasst werden, um geeignete Werbeziele zu erreichen. Mit diesem Ansatz können die Interessen des Nutzers oder Daten zu App-Interaktionen zur Auswahl von Anzeigen verwendet werden, während die Weitergabe dieser Daten an Dritte eingeschränkt wird.

3. Das SDK der App zur Anzeigenbereitstellung oder der Ad-Tech-Plattform rendert die ausgewählte Anzeige.

4. Die Plattform erleichtert die Berichterstellung zu Impressionen und Ergebnissen der Anzeigenauswahl. Diese Berichtsfunktion ergänzt die Attribution Reporting API. Anzeigentechnologieplattformen können die Anpassung entsprechend ihren Berichtsanforderungen vornehmen.

Zugriff auf die Protected Audience on Android APIs

Ad-Tech-Plattformen müssen sich registrieren, um auf die Protected Audience API zugreifen zu können. Weitere Informationen

Verwaltung benutzerdefinierter Zielgruppen

Benutzerdefinierte Zielgruppe

Eine benutzerdefinierte Zielgruppe besteht aus einer Gruppe von Nutzern, die vom Werbetreibenden festgelegt wird und gemeinsame Absichten oder Interessen hat. Eine App oder ein SDK kann eine benutzerdefinierte Zielgruppe verwenden, um eine bestimmte Zielgruppe anzugeben, z. B. Nutzer, die „Artikel im Einkaufswagen gelassen haben“ 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 der Protected Audience API von Chrome und können nicht für Web und Apps freigegeben werden. So wird die Weitergabe von Nutzerinformationen eingeschränkt.

Eine Werbetreibenden-App oder das integrierte SDK kann einer benutzerdefinierten Zielgruppe beitreten oder sie verlassen, z. B. basierend auf der Nutzerinteraktion in einer App.

Benutzerdefinierte Zielgruppenmetadaten

Jede benutzerdefinierte Zielgruppe enthält die folgenden Metadaten:

• Inhaber:Paketname der Inhaber-App. Dieser wird implizit auf den Paketnamen der aufrufenden App festgelegt.
• Käufer:Das Käufer-Werbenetzwerk, 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 verlassen haben“. Dieses Attribut kann beispielsweise als eines der Targeting-Kriterien in den Werbekampagnen des Werbetreibenden oder als Abfragestring in der URL zum Abrufen von Gebotscode 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 aus einer benutzerdefinierten Zielgruppe zu entfernen. Die Ablaufzeit darf ein maximales Zeitfenster nicht überschreiten, um die Lebensdauer einer benutzerdefinierten Zielgruppe zu begrenzen.
• URL für tägliche Aktualisierung:Die URL, die von der Plattform verwendet wird, um regelmäßig Kandidatenanzeigen und andere Metadaten abzurufen, die in den Feldern „Gebotssignale für Nutzer“ und „Vertrauenswürdige Gebotssignale“ definiert sind. Weitere Informationen finden Sie im Abschnitt zum Abrufen von infrage kommenden Anzeigen für benutzerdefinierte Zielgruppen.
• Gebotssignale für Nutzer:Anzeigentechnologieplattform-spezifische Signale 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:AdTech-Plattformen sind auf Echtzeitdaten angewiesen, um Anzeigen abzurufen und zu bewerten. So kann es beispielsweise sein, dass das Budget einer Anzeige aufgebraucht ist und die Auslieferung sofort beendet werden muss. Eine Ad-Tech-Plattform kann einen URL-Endpunkt definieren, von dem diese Echtzeitdaten abgerufen werden können, sowie die Gruppe von Schlüsseln, für die die Echtzeitsuche durchgeführt werden muss. Der Server, der diese Anfrage verarbeitet, ist ein vertrauenswürdiger Server, der von der Ad-Tech-Plattform verwaltet wird.
• URL für Gebotslogik:Die URL, die von der Plattform verwendet wird, um Gebotscode von der Demand-Side-Plattform abzurufen. Die Plattform führt diesen Schritt aus, wenn eine Anzeigenauktion gestartet wird.
• Anzeigen:Eine Liste mit infrage kommenden Anzeigen für die benutzerdefinierte Zielgruppe. Dazu gehören werbetechnologieplattformspezifische 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 von Anzeigen wird nach Möglichkeit über den Endpunkt für die tägliche Aktualisierungs-URL aktualisiert. Aufgrund von Ressourcenbeschränkungen auf Mobilgeräten ist die Anzahl der Anzeigen, die in einer benutzerdefinierten Zielgruppe gespeichert werden können, begrenzt.

Delegierung benutzerdefinierter 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 Werbetreibendenkunden und ‑partnern entwickelt werden. Mit der Protected Audience API können benutzerdefinierte Zielgruppen definiert und konfiguriert werden, ohne die Privatsphäre der Nutzer zu gefährden. Um einer benutzerdefinierten Zielgruppe beizutreten, müssen Buyer-Ad-Tech-Unternehmen, die kein SDK in Apps haben, mit Ad-Tech-Unternehmen zusammenarbeiten, die auf dem Gerät präsent sind, z. B. mobile Measurement-Partner (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. Dazu können Aufrufer auf dem Gerät die Erstellung benutzerdefinierter Zielgruppen im Namen von Käufern aufrufen. Dieser Vorgang wird als Delegierung benutzerdefinierter Zielgruppen bezeichnet. So konfigurieren Sie die Delegierung benutzerdefinierter Zielgruppen:

Einer benutzerdefinierten Zielgruppe beitreten

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 eines Ad-Tech-Unternehmens, das nicht auf dem Gerät vorhanden ist, den Beitritt zu einer benutzerdefinierten Zielgruppe anfordern. 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, der dem Käufer gehört, antwortet mit einem CustomAudience-JSON-Objekt im Antworttext. Die Felder „Käufer“ und „Eigentümer“ der benutzerdefinierten Zielgruppe werden ignoriert und von der API automatisch ausgefüllt. Die API erzwingt außerdem, dass die URL für das tägliche Update 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 Identität des Käufers wird über die fetchAndJoinCustomAudience() API anhand der eTLD+1 von fetchUri ermittelt. Die Identität des Käufers CustomAudience wird verwendet, um dieselben Registrierungs- und App-Autorisierungsprüfungen durchzuführen, die von joinCustomAudience() durchgeführt werden. Sie kann durch die Abrufantwort nicht geändert werden. Der CustomAudience-Inhaber ist der Paketname der aufrufenden Anwendung. Es gibt keine andere Validierung von fetchUri als die eTLD+1-Prüfung und insbesondere keine k-anonym-Prüfung. Die fetchAndJoinCustomAudience() API sendet eine HTTP-GET-Anfrage an fetchUri und erwartet ein JSON-Objekt, das die benutzerdefinierte Zielgruppe darstellt. Für die Antwort gelten dieselben obligatorischen und optionalen Einschränkungen sowie Standardwerte für die Felder des benutzerdefinierten Zielgruppenobjekts. Informationen zu den aktuellen Anforderungen und Einschränkungen finden Sie in unserem Entwicklerleitfaden.

Jede HTTP-Fehlerantwort des Käufers führt zu einem Fehler bei fetchAndJoinCustomAudience. Insbesondere eine HTTP-Statusantwort von 429 (Zu viele Anfragen) blockiert Anfragen der aktuellen Anwendung für einen noch 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 für Wiederholungsversuche bei vorübergehenden Fehlern (z. B. wenn der Server nicht reagiert) oder für die Behandlung von dauerhaften Fehlern (z. B. Datenvalidierungsfehler oder andere nicht vorübergehende Fehler bei der Kommunikation mit dem Server) verantwortlich ist.

Mit dem CustomAudienceFetchRequest-Objekt kann der API-Aufrufer einige Informationen für die benutzerdefinierte Zielgruppe definieren. Dazu werden die optionalen Eigenschaften verwendet, die im Beispiel gezeigt werden. Wenn diese Werte in der Anfrage festgelegt sind, können sie nicht durch die Käuferantwort überschrieben werden, die die Plattform erhält. Die Protected Audience API ignoriert die Felder in der Antwort. Wenn sie in der Anfrage nicht 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 von CustomAudience, die teilweise vom API-Aufrufer definiert wird, 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-anonyme Prüfung erfolgt, können Sie fetchUri für die Käuferbestätigung verwenden und die gemeinsame Nutzung von Informationen zwischen Käufer und SDK ermöglichen. Um die Überprüfung benutzerdefinierter Zielgruppen zu erleichtern, kann der Käufer ein Bestätigungstoken bereitstellen. Das On-Device-SDK sollte dieses Token in fetchUri einfügen, damit der vom Käufer gehostete Endpunkt die Inhalte der benutzerdefinierten Zielgruppe abrufen und mit dem Bestätigungstoken bestätigen kann, dass der Vorgang fetchAndJoinCustomAudience() dem Käufer entspricht und von einem vertrauenswürdigen On-Device-Partner stammt. Um Informationen weiterzugeben, kann der Käufer mit dem Anrufer auf dem Gerät vereinbaren, dass einige der Informationen, die zum Erstellen der benutzerdefinierten Zielgruppe verwendet werden, als Abfrageparameter in fetchUri aufgenommen werden. So kann der Käufer die Aufrufe prüfen und erkennen, ob ein Validierungstoken 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.

  • Der Käufer kann das Bestätigungstoken verwenden, um zu überprü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 die Art und Weise angegeben, wie der Käufer das Bestätigungstoken an den Aufrufer überträgt. Das Bestätigungstoken kann beispielsweise im SDK oder Backend des Inhabers vorab geladen oder in Echtzeit vom SDK des Inhabers vom Server des Käufers abgerufen werden.

Benutzerdefinierte Zielgruppe verlassen

Der Inhaber einer benutzerdefinierten Zielgruppe kann die Zielgruppe verlassen, indem er leaveCustomAudience() aufruft, wie in diesem beispielhaften Code-Snippet gezeigt wird:

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

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

Kontrolle durch Nutzer

• Mit dem Vorschlag soll Nutzern die Liste der installierten Apps angezeigt werden, die mindestens eine benutzerdefinierte Zielgruppe erstellt haben.
• Nutzer können Apps aus dieser Liste entfernen. Durch das Entfernen werden alle benutzerdefinierten Zielgruppen, die mit den Apps verknüpft sind, gelöscht und die Apps können nicht mehr 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 auf Android, einschließlich der Protected Audience API, vollständig deaktivieren. Wenn der Nutzer die Privacy Sandbox deaktiviert hat, schlägt die Protected Audience API ohne Fehlermeldung fehl.

Das Design dieser Funktion ist noch in Arbeit. Die Details werden in einem späteren Update bekannt gegeben.

Geplante Updates

Bei den zuvor beschriebenen Lösungen muss die App oder das Ad-Tech-SDK die APIs aufrufen, während die App im Vordergrund ist, und die vollständigen Eigenschaften der benutzerdefinierten Zielgruppe entweder direkt oder über die Delegierung bereitstellen. Es ist jedoch nicht immer möglich, dass Werbetreibende und Ad-Tech-Anbieter in Echtzeit festlegen, welchen Zielgruppen ein Nutzer angehört, während er die App verwendet.

Dazu kann die scheduleCustomAudienceUpdate() API von Ad-Tech-Unternehmen aufgerufen werden. Mit dieser API kann der Aufrufer eine Verzögerung für den API-Aufruf festlegen. So bleibt mehr Zeit für die Verarbeitung von App-Ereignissen durch die antwortende Ad-Tech-Plattform und für die Entscheidung, welchen Protected Audiences der Nutzer beitreten oder aus welchen 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;
  }
}

ScheduleCustomAudienceUpdateRequest enthält die Informationen, die zum Registrieren eines verzögerten Jobs für die Ausführung auf der Plattform erforderlich sind. Nach der angegebenen Verzögerung wird regelmäßig ein Hintergrundjob ausgeführt, der die Anfrage(n) sendet. Die 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 automatisch aus der eTLD+1 abgeleitet. Sie muss nicht explizit angegeben werden und kann durch die Aktualisierungsantwort nicht geändert werden. Die GET-Anfrage erwartet als Antwort ein JSON-Objekt mit einer Liste von customAudience-Objekten.
• DelayTime: Die Zeit, die zwischen dem Zeitpunkt des scheduleCustomAudienceUpdate()-API-Aufrufs zum Planen des Updates und dem Zeitpunkt des Updates liegt.

• PartialCustomAudience: Mit der API kann das On-Device-SDK auch eine Liste mit teilweise erstellten benutzerdefinierten Zielgruppen senden. So können die In-App-SDKs je nach Partnerschaft mit DSPs eine doppelte Rolle übernehmen, von der vollständigen bis zur teilweisen Kontrolle über die Verwaltung benutzerdefinierter Zielgruppen.

  • Dadurch bleibt diese API auch mit der fetchAndJoinCustomAudience()-API kompatibel, die einen ähnlichen Informationsaustausch ermöglicht.

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

App-Berechtigungen und Einstellungen

Mit dem Vorschlag soll Apps die Kontrolle über ihre benutzerdefinierten Zielgruppen gegeben werden:

• Eine App kann ihre Verknüpfungen mit benutzerdefinierten Zielgruppen verwalten.
• Eine App kann Drittanbieter-Werbetechnologieplattformen Berechtigungen erteilen, damit diese in ihrem Namen benutzerdefinierte Zielgruppen verwalten können.

Das Design dieser Funktion ist noch in Arbeit. Die Details werden in einem späteren Update bekannt gegeben.

Einstellungen für AdTech-Plattformen

In diesem Vorschlag werden Möglichkeiten für Anzeigentechnologie-Anbieter beschrieben, ihre benutzerdefinierten Zielgruppen zu verwalten:

• Anbieter von Anzeigentechnologien registrieren sich für die Privacy Sandbox und geben eine eTLD+1-Domain an, die mit allen URLs für eine benutzerdefinierte Zielgruppe übereinstimmt.
• Ad-Tech-Unternehmen können mit Apps oder SDKs zusammenarbeiten, um Bestätigungstokens bereitzustellen, die zur Bestätigung der Erstellung einer benutzerdefinierten Zielgruppe verwendet werden. Wenn dieser Prozess an einen Partner delegiert wird, kann für das Erstellen benutzerdefinierter Zielgruppen eine Bestätigung durch die Anzeigentechnologie erforderlich sein.
• Ein Ad-Tech-Unternehmen kann joinCustomAudience-Aufrufe in seinem Namen deaktivieren und nur die fetchAndJoinCustomAudience API verwenden, um alle benutzerdefinierten Zielgruppen für Anrufe zu aktivieren. Die Kontrollgruppe kann während der Registrierung für die Privacy Sandbox aktualisiert werden. Mit dieser Einstellung können entweder alle Anzeigentechnologien oder keine zugelassen werden. Aufgrund von Plattformbeschränkungen können Delegierungsberechtigungen nicht auf Ad-Tech-Basis erteilt werden.

Antwort zu Kandidatenanzeigen und ‑Metadaten

Kandidatenanzeigen und Metadaten, die von einer Käuferplattform zurückgegeben werden, sollten die folgenden Felder enthalten:

• Metadaten:Metadaten für Anzeigen, die für Ad-Tech-Unternehmen auf der Kaufseite spezifisch sind. Dazu können beispielsweise Informationen zur Werbekampagne und Targeting-Kriterien wie Standort und Sprache gehören.
• Render-URL:Endpunkt zum Rendern des Anzeigen-Creatives.
• Filter:Optionale Informationen, die für die Protected Audience API erforderlich sind, um Anzeigen anhand von Daten auf dem Gerät zu filtern. Weitere Informationen finden Sie im Abschnitt zur Logik für die Filterung auf der Käuferseite.

Workflow für die Anzeigenauswahl

Mit diesem Vorschlag soll der Datenschutz verbessert werden. Dazu wird die Ad Selection API eingeführt, mit der die Ausführung von Auktionen für Ad-Tech-Plattformen koordiniert wird.

Auf AdTech-Plattformen werden Gebote und die Anzeigenauswahl heute in der Regel ausschließlich auf ihren Servern ausgeführt. Mit diesem Vorschlag sind benutzerdefinierte Zielgruppen und andere vertrauliche Nutzersignale wie Informationen zu installierten Paketen nur über die Ad Selection API zugänglich. Zusätzlich werden für den Remarketing-Anwendungsfall Kandidatenanzeigen out-of-band abgerufen, d.h. nicht im Kontext, in dem Anzeigen ausgeliefert werden. Anzeigentechnologie-Plattformen müssen sich darauf vorbereiten, dass einige Teile ihrer aktuellen Auktions- und Anzeigenauswahl-Logik auf dem Gerät bereitgestellt und ausgeführt werden. Anzeigentechnologieplattformen 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, senden Ad-Tech-Plattformen möglicherweise mehrere kontextbezogene Anzeigen an das Gerät und rufen den Workflow für die Anzeigenauswahl auf, um die Filterung auf Grundlage von App-Installationen zu ermöglichen und so die Wahrscheinlichkeit zu maximieren, dass eine relevante Anzeige ausgeliefert wird.
• Da Remarketing-Anzeigen Out-of-Band abgerufen werden, müssen aktuelle Gebotsmodelle möglicherweise aktualisiert werden. Anzeigentechnologieplattformen können Gebotsuntermodelle erstellen (die Implementierung kann auf einem Muster namens Two-Tower-Modell basieren), die separat für Anzeigenfunktionen und kontextbezogene Signale verwendet werden können. Die Ausgaben der Untermodelle werden dann auf dem Gerät kombiniert, um Gebote vorherzusagen. Das kann sowohl bei serverseitigen Auktionen als auch bei Auktionen für jede Anzeigenmöglichkeit von Vorteil sein.

So können die Daten zu den App-Interaktionen des Nutzers zur Auswahl von Anzeigen verwendet werden, ohne dass diese Daten an Dritte weitergegeben werden.

Dieser Workflow für die Anzeigenauswahl orchestriert die On-Device-Ausführung von JavaScript-Code von Ad-Tech-Anbietern in der folgenden Reihenfolge:

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

Bei der Auswahl von Anzeigen, bei denen benutzerdefinierte Zielgruppen zum Einsatz kommen, ruft die Plattform den von der Käuferseite bereitgestellten JavaScript-Code basierend auf dem öffentlichen URL-Endpunkt ab, der in den Metadaten der benutzerdefinierten Zielgruppe unter „URL für Gebotslogik“ definiert ist. Der URL-Endpunkt für den sell-side-Entscheidungscode wird ebenfalls als Eingabe übergeben, um den Workflow für die Anzeigenauswahl zu starten.

Die Gestaltung von Anzeigenauswahlen ohne benutzerdefinierte Zielgruppen ist in Arbeit.

Workflow für die Anzeigenauswahl starten

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

• Verkäufer: Kennung für die Sell-Side-Anzeigenplattform im Format eTLD+1
• URL für Entscheidungslogik: Wenn eine Anzeigenauktion gestartet wird, ruft die Plattform über diese URL JavaScript-Code von der Sell-Side-Plattform ab, um eine Gewinneranzeige zu ermitteln.
• Käufer benutzerdefinierter Zielgruppen: Eine Liste von Buy-Side-Plattformen mit Nachfrage für diese Auktion basierend auf benutzerdefinierten Zielgruppen im Format „eTLD+1“.
• Signale für die Anzeigenauswahl: Informationen zur Auktion (Anzeigengröße, Anzeigenformat usw.).
• Verkäufersignale: SSP-spezifische Signale.
• URL für vertrauenswürdige Scoring-Signale: URL-Endpunkt für vertrauenswürdige Signale auf der Verkäuferseite, von dem kreaturspezifische Echtzeitinformationen abgerufen werden können.
• Signale pro Käufer: Die teilnehmenden Nachfrageseiten können diesen Parameter verwenden, um Eingaben für die Auktion zu liefern. Dieser Parameter kann beispielsweise umfassende Kontextinformationen enthalten, die für die Festlegung von Geboten nützlich sind.

Das folgende Beispiel-Code-Snippet zeigt, wie das SDK einer Ad-Tech-Plattform den Workflow zur Anzeigen-Auswahl initiiert, indem zuerst AdSelectionConfig definiert und dann selectAds aufgerufen wird, um die Gewinneranzeige 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);

Gebotslogik auf der Buy Side

Die Gebotslogik wird in der Regel von Käuferplattformen bereitgestellt. Der Code dient dazu, Gebote für infrage kommende Anzeigen zu ermitteln. Möglicherweise wird zusätzliche Geschäftslogik angewendet, um das Ergebnis zu ermitteln.

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

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 sequenziell für alle Anzeigen (kontextbezogen oder Remarketing) auf. Wenn es mehrere Anbieter für die Gebotslogik gibt, kann die Ausführungsreihenfolge nicht garantiert werden.

Die Funktion erwartet die folgenden Parameter:

• Anzeige: Die Anzeige, die vom Buy-Side-Gebotscode berücksichtigt wird. Anzeige aus einer zulässigen benutzerdefinierten Zielgruppe
• Auktionssignale: Sell-Side-Signale, die für die jeweilige Plattform spezifisch sind.
• Signale pro Käufer: Die teilnehmenden Nachfrageseiten können diesen Parameter verwenden, um Eingaben für die Auktion zu liefern. Dieser Parameter kann beispielsweise umfassende Kontextinformationen enthalten, die für die Festlegung von Geboten nützlich sind.
• Vertrauenswürdige Gebotssignale: AdTech-Plattformen nutzen Echtzeitdaten, um das Abrufen und Bewerten von Anzeigen zu optimieren. Beispiel: Das Budget einer Werbekampagne ist aufgebraucht und die Auslieferung muss sofort beendet werden. Eine Ad-Tech-Plattform kann einen URL-Endpunkt definieren, über den diese Echtzeitdaten abgerufen werden können, sowie die Gruppe von Schlüsseln, für die die Echtzeitsuche durchgeführt werden muss. Der verwaltete Server der Ad-Tech-Plattform, der diese Anfrage verarbeitet, ist ein vertrauenswürdiger Server, der von der Ad-Tech-Plattform verwaltet wird.
• Kontextbezogene Signale: Dazu können grob gerundete Zeitstempel oder ungefähre Standortinformationen oder Kosten pro Anzeigenklick gehören.
• Nutzersignale: Dazu können Informationen wie verfügbare Informationen zu installierten Paketen gehören.

Werbekosten

Zusätzlich zum Gebot können Buy-Side-Plattformen die Kosten pro Klick als Teil von generateBid() zurückgeben. Beispiel:

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

Wenn diese Anzeige die Gewinneranzeige ist, wird adCost aus Datenschutzgründen stochastisch auf 8 Bit gerundet. Der gerundete Wert von adCost wird dann bei der Impression-Berichterstellung an den Parameter contextual_signals in reportWin übergeben.

Filterlogik auf der Buy-Side

Buy-Side-Plattformen können Anzeigen anhand zusätzlicher On-Device-Signale filtern, die während der Anzeigenauswahlphase verfügbar sind. So können Ad-Tech-Plattformen beispielsweise Frequency Capping implementieren. Wenn es mehrere Filteranbieter gibt, kann die Ausführungsreihenfolge nicht garantiert werden.

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 anhand zusätzlicher On-Device-Signale gefiltert werden soll, die für Protected Audience verfügbar sind und das Gerät nicht verlassen. Wenn wir die Designs für zusätzliche Filterlogik festlegen, werden Buy-Side-Plattformen dieser Struktur folgen, um zu signalisieren, dass die Filterung erfolgen soll.

Sell-Side-Bewertungslogik

Die Scoring-Logik wird in der Regel von der Sell-Side-Plattform bereitgestellt. Der Code dient dazu, anhand der Ausgaben der Gebotslogik eine Gewinneranzeige zu ermitteln. Es kann zusätzliche Geschäftslogik angewendet werden, um das Ergebnis zu ermitteln. Wenn es mehrere Anbieter von Entscheidungslogik gibt, kann die Ausführungsreihenfolge der Anbieter nicht garantiert werden. Die Plattform verwendet den Eingabeparameter „URL für 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:

• Anzeige: Die zu bewertende Anzeige; Ausgabe der Funktion generateBid().
• Gebot: Der Gebotsbetrag, der von der Funktion generateBid() ausgegeben wird.
• Auktionskonfiguration: Eingabeparameter für die Methode selectAds().
• Vertrauenswürdige Scoring-Signale: Anzeigentechnologie-Plattformen nutzen Echtzeitdaten, um Anzeigen zu filtern und zu bewerten. Ein App-Publisher kann beispielsweise verhindern, dass Anzeigen aus einer bestimmten Werbekampagne in der App ausgeliefert werden. Diese Daten werden aus dem URL-Parameter für vertrauenswürdige Scoring-Signale der Auktionskonfiguration abgerufen. Der Server, der diese Anfrage verarbeitet, sollte ein vertrauenswürdiger Server sein, der von einem Anzeigentechnologie-Anbieter verwaltet wird.
• Kontextbezogenes Signal: Dazu können ein grober Zeitstempel oder ungefähre Standortinformationen gehören.
• Nutzersignal: Dazu können Informationen wie der App-Store gehören, über den die Installation der App initiiert wurde.
• Signal für benutzerdefinierte Zielgruppe: Wenn die zu bewertende Anzeige aus einer benutzerdefinierten Zielgruppe auf dem Gerät stammt, enthält dieses Signal Informationen wie den Reader und den Namen der benutzerdefinierten Zielgruppe.

Laufzeit des Codes für die Anzeigenauswahl

Im Vorschlag ruft das System den von der Ad-Tech-Plattform bereitgestellten Auktionscode von konfigurierbaren URL-Endpunkten ab und führt ihn auf dem Gerät aus. Aufgrund der Ressourcenbeschränkungen auf Mobilgeräten sollte der 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 Obergrenze werden in einem späteren Update bekannt gegeben.
• Der Code muss in sich geschlossen sein und darf keine externen Abhängigkeiten haben.

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

Programmiersprache

Der von der Ad-Tech-Plattform bereitgestellte Auktionscode sollte in JavaScript geschrieben sein. So könnten Anzeigentechnologie-Plattformen beispielsweise Gebotscode auf Plattformen teilen, die Privacy Sandbox unterstützen.

Rendering der Gewinneranzeige

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.

Die Lösung soll so weiterentwickelt werden, dass Informationen zur Mitgliedschaft eines Nutzers in einer benutzerdefinierten Zielgruppe oder zum App-Engagement-Verlauf nicht über Informationen zur Gewinneranzeige von der App oder dem SDK ermittelt werden können (ähnlich dem Vorschlag für Fenced Frames von Chrome).

Berichte zu Impressionen und Ereignissen

Nachdem 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 können die Plattform auf Verkäuferseite und die Plattform auf Käuferseite, die die Auktion gewonnen hat, zusätzliche Berichte auf Ereignisebene zur Gewinneranzeige erhalten. So können Sie Informationen zur Auktion (Gebot, Name der benutzerdefinierten Zielgruppe usw.) in Klicks, Aufrufe und andere Anzeigenereignisse einbeziehen. Die Plattform ruft die Berichtslogik in dieser Reihenfolge auf:

1. Berichte für die Angebotsseite.
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 von Gebotsmodellen und genaue Abrechnungsabläufe zu ermöglichen. Diese Unterstützung für das Impression Reporting ergänzt die Attribution Reporting API.

Für die Unterstützung von Ereignisberichten sind zwei Schritte erforderlich: Auf der Verkäuferseite und auf der Käuferseite muss JavaScript registrieren, für welches Ereignis Ereignisberichte empfangen werden sollen. Die Verkäuferseite ist für die Meldung von Informationen auf Ereignisebene verantwortlich.

Protected Audience bietet einen Mechanismus, um zukünftige Ereignisse im Zusammenhang mit einer gewonnenen Auktion zu abonnieren, indem Beacons registriert werden. In der reportResult()-JavaScript-Funktion eines Verkäufers können Sell-Side-Plattformen Beacons mit 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 die Registrierung erfolgen soll. Dieser Wert wird als Schlüssel verwendet, um den Endpunkt zu suchen, den die Plattform beim Melden der Auktionsergebnisse anpingt.
• reporting_url: Die URL, die der Ad-Tech-Plattform gehört und mit der das Ereignis verarbeitet wird.

Ereignisschlüssel sind String-IDs, die dem Sell-Side-SDK gehören, das für das Melden der Auktionsergebnisse verantwortlich ist. Damit ein Callback erfolgt, registrieren Ad-Tech-Unternehmen Beacons mit Schlüsseln, die mit den Schlüsseln übereinstimmen, die von der Sell-Side beim Melden der Ereignisse verwendet werden. Diese müssen nicht k-anonym sein. Es gibt jedoch Beschränkungen für die Anzahl und Länge der Schlüssel, die für eine bestimmte benutzerdefinierte Zielgruppe registriert werden können. Wenn reportEvent() aufgerufen wird, können Sell-Side-Plattformen, auf denen die Auktion durchgeführt wurde, diese Ereignisberichte immer empfangen. Nur die erfolgreiche Buy-Side-Plattform kann diese Berichte erhalten.

Berichte für die Angebotsseite

Die Plattform ruft die JavaScript-Funktion reportResult() im vom Verkäufer bereitgestellten Code auf, der über den Parameter URL für Entscheidungslogik 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 den Käufer: Ein JSON-Objekt, das an die reportWin-Funktion des Käufers übergeben werden soll.

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

• URL für das Rendern von Anzeigen
• Betrag des erfolgreichen Gebots
• App-Name
• Abfragekennungen
• Signale für Käufer: Um die gemeinsame Nutzung von Daten zwischen Angebots- und Nachfrageseite zu unterstützen, übergibt die Plattform diesen Rückgabewert als Eingabeparameter an den Berichterstellungscode der Nachfrageseite.

Berichte für die Käuferseite

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

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 die Ausgabe von „sell-side reportResult“. So kann die Sell-Side-Plattform Daten für Berichte 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 unter Umständen 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 gemeldet werden, nachdem die Berichterstellung für Impressionen für die Auktion abgeschlossen ist. Das Sell-Side-SDK ist für das Melden von Ereignissen verantwortlich. Die Plattform stellt eine API zur Verfügung, die ein ReportEventRequest entgegennimmt, das die zuletzt durchgeführte Auktion, den gemeldeten Ereignisschlüssel, die mit diesem Schlüssel verknüpften Daten, die Angabe, ob der Bericht an den Käufer oder den Verkäufer (oder beide) gesendet werden soll, und ein optionales Eingabeereignis für Werbeereignisse angibt. Der Client definiert den Ereignisschlüssel und die zu meldenden Daten.

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, die aus dem AdSelectionOutcome abgerufen wurde.
• event_key ist ein von der Verkaufsseite 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 mit Flags festgelegt wird, die von der Plattform bereitgestellt werden. Es kann 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 Sell-Side-SDK reportEvent aufgerufen hat, versucht die Plattform, je nach reporting_destinations-Flag, event_key mit den Schlüsseln abzugleichen, die von Käufern und Verkäufern in ihren JavaScript-Funktionen reportWin und reportResult registriert wurden. Wenn eine Übereinstimmung vorliegt, sendet die Plattform die event_data per POST an die zugehörige reporting_url. Der content type der Anfrage ist Nur-Text und der Textkörper ist der event_data. Diese Anfrage wird nach bestem Wissen und Gewissen gestellt und schlägt bei einem Netzwerkfehler, einer Serverfehlermeldung oder wenn keine übereinstimmenden Schlüssel gefunden wurden, ohne Fehlermeldung 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 Ad-Tech-Unternehmen die Attributionsleistung verschiedener Remarketing-Taktiken bewerten, um herauszufinden, mit welchen Zielgruppen sich der höchste ROI erzielen lässt.

Durch diese API-übergreifende Integration haben Ad-Tech-Unternehmen 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 sollen.
• Auktionsdaten aus der Protected Audience-Auktion in die Quellseitenschlüsselzuordnung für die Berichterstellung von aggregierten Zusammenfassungen (mit der Attribution Reporting API) aufnehmen. Weitere Informationen

Wenn ein Nutzer eine Anzeige sieht oder darauf klickt:

• Die URL, die zum Melden dieser Ereignisinteraktionen mit Protected Audience verwendet wird, enthält die erforderlichen Daten für den Käufer, um einen Aufruf oder Klick als zulässige Quelle mit der Attribution Reporting API zu registrieren.
• Die Anzeigentechnologie kann CustomAudience (oder andere relevante Kontextinformationen zur Anzeige, z. B. Anzeigenplatzierung oder Ansichtsdauer) über diese URL übergeben, damit diese Metadaten in Zusammenfassungsberichte übernommen werden, wenn die Anzeigentechnologie die aggregierte Kampagnenleistung überprüft.

Quellenregistrierung aktivieren

reportEvent() akzeptiert einen neuen optionalen Parameter InputEvent. Käufer, die Ad Beacons registrieren, können auswählen, welche reportEvent-Berichte mit Attribution Reporting APIs als registrierte Quelle registriert werden. Der Anfrageheader „Attribution-Reporting-Eligible“ wird allen Ereignisberichts-Anfragen hinzugefügt, die von reportEvent() gesendet werden. Antworten mit entsprechenden ARA-Headern werden auf dieselbe Weise geparst wie jede andere reguläre ARA-Quellenregistrierungsantwort. Informationen zum Registrieren einer Quell-URL finden Sie in der Erläuterung zur Attribution Reporting API.

Da ARA unter Android sowohl View- als auch Click-Events unterstützt, werden InputEvents verwendet, um zwischen den beiden Typen zu unterscheiden. Wie bei der Registrierung von ARA-Quellen interpretiert die reportEvent() API ein plattformbestätigtes InputEvent als Klickereignis. Wenn InputEvent fehlt, null oder ungültig ist, wird die Quellregistrierung als Aufruf betrachtet.

Die eventData nach der Auktion kann vertrauliche Informationen enthalten. Daher wird sie bei Anfragen zur Registrierung von weitergeleiteten Quellen von der Plattform entfernt.eventData

Beispiel für Berichte zu Interaktionen und Conversions

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

In diesem Workflow stimmt sich der Käufer mit dem Verkäufer ab, um eine eindeutige ID in die Auktion zu senden. Während der Auktion sendet der Käufer diese eindeutige ID zusammen mit den Auktionsdaten. Während des Renderns und der Conversion werden die Daten der gerenderten Anzeige ebenfalls mit derselben eindeutigen ID gesendet. Später kann die eindeutige ID verwendet werden, um diese Berichte miteinander zu verknüpfen.

Workflow: Vor Beginn der Auktion sendet der Käufer eine eindeutige ID an den Verkäufer. Dies geschieht im Rahmen seiner programmatischen Echtzeitgebotsantwort („RTB“). Die ID kann als Variable wie auctionId festgelegt werden. Die ID wird als perBuyerSignals im auctionConfig ü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 während der Anzeigenwiedergabe und für bestimmte Interaktionsereignisse (registerAdBeacon()) ausgelöst wird. Wenn Sie Auktionssignale für ein Anzeigenereignis zuordnen möchten, legen Sie auctionId als Suchparameter der Beacon-URL fest.
2. Während der Anzeigenbereitstellung können die Beacons, die Sie während der Auktionszeit registriert haben, ausgelöst oder mit Daten auf Ereignisebene erweitert werden. Der Verkäufer muss reportEvent() auslösen und die Daten auf Ereignisebene übergeben. Die Plattform pingt die registrierte Ad-Beacon-URL des Käufers an, die mit dem ausgelösten reportEvent() korreliert.
3. Der Käufer registriert die Anzeige mit der Attribution Reporting API, indem er auf die Anfragen für das Anzeigen-Beacon mit dem Header Attribution-Reporting-Register-Source antwortet. Wenn Sie Auktionssignalen ein Conversion-Ereignis zuordnen möchten, legen Sie die auctionId in der Quell-URL „Register“ fest.

Am Ende dieses Prozesses hat der Käufer einen Auktionsbericht, einen Interaktionsbericht und einen Conversion-Bericht, die mithilfe der eindeutigen ID korreliert 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.

Vertrauenswürdiger Server, der von einer Anzeigentechnologieplattform verwaltet wird

Für die Logik zur Anzeigenauswahl sind Echtzeitinformationen wie der Status des Budgetausschöpfung erforderlich, um zu ermitteln, ob Anzeigenkandidaten für die Auktion ausgewählt werden sollen. Sowohl Buy-Side- als auch Sell-Side-Plattformen können diese Informationen von den von ihnen betriebenen Servern abrufen. Um das Risiko zu minimieren, dass über diese Server vertrauliche Informationen offengelegt werden, sind die folgenden Einschränkungen vorgesehen:

• Das Verhalten dieser Server, das später in diesem Abschnitt beschrieben wird, würde keine Nutzerinformationen preisgeben.
• Auf den Servern werden keine pseudonymen Profile auf Grundlage der angezeigten Daten erstellt. Sie müssen also als „vertrauenswürdig“ eingestuft werden.

Käuferseite: Sobald die Gebotslogik der Käuferseite initiiert wird, ruft die Plattform vertrauenswürdige Gebotsdaten per HTTP vom vertrauenswürdigen Server ab. Die URL wird zusammengesetzt, indem die URL und die Schlüssel aus den Metadaten für vertrauenswürdige Gebotssignale der benutzerdefinierten Zielgruppe angehängt werden, die verarbeitet wird. Dieser Abruf erfolgt nur bei der Verarbeitung von Anzeigen aus benutzerdefinierten Zielgruppen auf dem Gerät. In dieser Phase kann die Käuferseite Budgets durchsetzen, den Pausen-/Fortsetzungsstatus von Kampagnen prüfen, die Ausrichtung vornehmen usw.

Dies ist eine Beispiel-URL zum Abrufen vertrauenswürdiger Gebotsdaten basierend auf den Metadaten für vertrauenswürdige Gebotssignale aus der benutzerdefinierten Zielgruppe:

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

Die Antwort des Servers sollte ein JSON-Objekt sein, dessen Schlüssel „key1“, „key2“ usw. sind und dessen Werte den Gebotsfunktionen des Käufers zur Verfügung gestellt werden.

Verkaufsseite: Ähnlich wie beim Ablauf auf der Kaufseite möchten Verkäufer möglicherweise Informationen zu Creatives abrufen, die bei der Auktion berücksichtigt werden. Ein Publisher möchte beispielsweise möglicherweise erzwingen, dass bestimmte Creatives aufgrund von Bedenken hinsichtlich der Markensicherheit nicht in seiner App ausgeliefert werden. Diese Informationen können abgerufen und der Auktionslogik auf der Verkäuferseite zur Verfügung gestellt werden. Ähnlich wie bei der serverseitigen Suche auf der Käuferseite erfolgt die serverseitige Suche auf der Verkäuferseite auch über einen HTTP-Abruf. Die URL wird erstellt, indem die URL für vertrauenswürdige Scoring-Signale mit den Rendering-URLs der Creatives verknüpft wird, für die die Daten abgerufen werden müssen.

Im Folgenden finden Sie eine Beispiel-URL, mit der Informationen zu Creatives abgerufen werden, die in der Auktion berücksichtigt wurden. Die URL basiert auf Creative-Render-URLs:

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

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

Diese Server würden vertrauenswürdig betrieben und bieten mehrere Sicherheits- und Datenschutzvorteile:

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

Als vorübergehende Lösung können Käufer und Verkäufer diese Gebotssignale von einem beliebigen Server abrufen, auch von einem, den sie selbst betreiben. In der Release-Version wird die Anfrage jedoch nur an einen vertrauenswürdigen Schlüssel/Wert-Server gesendet.

Käufer und Verkäufer können einen gemeinsamen vertrauenswürdigen Key-Value-Server für Plattformen verwenden, die mit der Privacy Sandbox für Android und das Web kompatibel sind.