Entwicklerhandbuch für die Protected Audience API

Wählen Sie in der Dokumentation zur Privacy Sandbox für Android mit der Schaltfläche Entwicklervorschau oder Beta die Programmversion aus, mit der Sie arbeiten. Die Anleitungen können variieren.

Die Protected Audience API auf Android (früher FLEDGE) umfasst die Custom Audience API und die Ad Selection API. Mit diesen APIs können AdTech-Plattformen und Werbetreibende personalisierte Anzeigen basierend auf bisherigen App-Interaktionen schalten. Dadurch wird die Weitergabe von IDs zwischen Apps und die Weitergabe von Informationen zu App-Interaktionen von Nutzern an Dritte eingeschränkt.

Die Custom Audience API dreht sich um die Abstraktion „benutzerdefinierte Zielgruppe“, die eine Gruppe von Nutzern mit gemeinsamen Absichten darstellt. Ein Werbetreibender kann einen Nutzer in einer benutzerdefinierten Zielgruppe registrieren und relevante Anzeigen damit verknüpfen. Diese Informationen werden lokal gespeichert und können für Gebote von Werbetreibenden, das Filtern von Anzeigen und das Anzeigen-Rendering verwendet werden.

Die Ad Selection API bietet ein Framework, mit dem mehrere Entwickler lokal eine Auktion für eine benutzerdefinierte Zielgruppe ausführen können. Dazu berücksichtigt das System relevante Anzeigen, die mit der benutzerdefinierten Zielgruppe verknüpft sind, und führt eine zusätzliche Verarbeitung der Anzeigen durch, die eine AdTech-Plattform an das Gerät zurückgibt.

Anzeigentechnologie-Plattformen können diese APIs einbinden, um Remarketing zu implementieren, das die Privatsphäre der Nutzer schützt. Für zukünftige Releases ist die Unterstützung weiterer Anwendungsfälle, einschließlich Anzeigen für App-Installationen, geplant. Weitere Informationen zur Protected Audience API auf Android finden Sie im Designvorschlag.

In dieser Anleitung wird beschrieben, wie Sie die Protected Audience API auf Android-Geräten verwenden, um Folgendes zu tun:

1. Benutzerdefinierte Zielgruppen verwalten
2. Anzeigenauswahl auf einem Gerät einrichten und ausführen
3. Anzeigenimpressionen melden

Hinweis

Führen Sie die folgenden Schritte aus, bevor Sie beginnen:

1. Richten Sie Ihre Entwicklungsumgebung für die Privacy Sandbox für Android ein.
2. Sie können entweder ein System-Image auf einem unterstützten Gerät installieren oder einen Emulator einrichten, der die Privacy Sandbox auf Android unterstützt.

3. Aktivieren Sie in einem Terminal mit dem folgenden adb-Befehl den Zugriff auf die Protected Audience API, der standardmäßig deaktiviert ist.

     adb shell device_config put adservices ppapi_app_allow_list \"*\"
   

4. Aktivieren Sie in einem Terminal die Beacon-Berichte mit den folgenden adb-Befehlen.

    adb shell device_config put adservices fledge_beacon_reporting_metrics_enabled true
    adb shell device_config put adservices fledge_register_ad_beacon_enabled true
   

5. Fügen Sie Ihrem App-Manifest eine ACCESS_ADSERVICES_CUSTOM_AUDIENCE-Berechtigung hinzu:

     <uses-permission android:name="android.permission.ACCESS_ADSERVICES_CUSTOM_AUDIENCE" />
   

6. Verweise im <application>-Element deines Manifests auf eine Anzeigendienstkonfiguration:

     <property android:name="android.adservices.AD_SERVICES_CONFIG"
               android:resource="@xml/ad_services_config" />
   

7. Geben Sie die XML-Ressource für Anzeigendienste an, auf die in Ihrem Manifest verwiesen wird, z. B. res/xml/ad_services_config.xml. Weitere Informationen zu Berechtigungen für Anzeigendienste und zur SDK-Zugriffssteuerung

     <ad-services-config>
       <custom-audiences allowAllToAccess="true" />
     </ad-services-config>
   

8. Standardmäßig schränkt die Ad Selection API den maximalen Arbeitsspeicher ein, der einem Script für Auktions- oder Impressionsberichte zugewiesen werden kann. Für die Speicherbeschränkungsfunktion ist die WebView-Version 105.0.5195.58 oder höher erforderlich. Die Plattform erzwingt eine Versionsprüfung und Aufrufe der selectAds- und reportImpression-APIs schlagen fehl, wenn diese nicht erfüllt ist. Es gibt zwei Möglichkeiten, dies einzurichten:

   • Option 1: Führen Sie den folgenden adb-Befehl aus, um diese Prüfung zu deaktivieren:

     adb device_config put fledge_js_isolate_enforce_max_heap_size false
     

   • Option 2: Installieren Sie WebView Beta aus dem Google Play Store. Diese Version muss der oben angegebenen Version entsprechen oder höher sein.

Benutzerdefinierte Zielgruppen zusammenführen

Eine benutzerdefinierte Zielgruppe ist eine Gruppe von Nutzern mit gemeinsamen Absichten oder Interessen, die von einer Werbe-App festgelegt wird. Eine App oder ein SDK kann eine benutzerdefinierte Zielgruppe verwenden, um eine bestimmte Zielgruppe anzugeben, z. B. Nutzer, die Artikel in einem Einkaufswagen gelassen haben. So erstellen oder verknüpfen Sie eine benutzerdefinierte Zielgruppe asynchron:

1. Initialisieren Sie das CustomAudienceManager-Objekt.
2. Erstelle ein CustomAudience-Objekt, indem du wichtige Parameter wie das Paket des Käufers und einen relevanten Namen angibst. Initialisieren Sie dann das JoinCustomAudienceRequest-Objekt mit dem CustomAudience-Objekt.
3. Rufen Sie die asynchrone joinCustomAudience() mit dem JoinCustomAudienceRequest-Objekt und den relevanten Executor- und OutcomeReceiver-Objekten auf.

val customAudienceManager: CustomAudienceManager =
    context.getSystemService(CustomAudienceManager::class.java)

// Initialize a custom audience.
val audience = CustomAudience.Builder()
    .setBuyer(buyer)
    .setName(name)
    ...
    .build()

// Initialize a custom audience request.
val joinCustomAudienceRequest: JoinCustomAudienceRequest =
    JoinCustomAudienceRequest.Builder().setCustomAudience(audience).build()

// Request to join a custom audience.
customAudienceManager.joinCustomAudience(joinCustomAudienceRequest,
    executor,
    outcomeReceiver)

CustomAudienceManager customAudienceManager =
    context.getSystemService(CustomAudienceManager.class);

// Initialize a custom audience.
CustomAudience audience = new CustomAudience.Builder()
    .setBuyer(buyer)
    .setName(name)
    ...
    .build();

// Initialize a custom audience request.
JoinCustomAudienceRequest joinCustomAudienceRequest =
    new JoinCustomAudienceRequest.Builder().setCustomAudience(audience).build();

// Request to join a custom audience.
customAudienceManager.joinCustomAudience(joinCustomAudienceRequest,
    executor,
    outcomeReceiver);

Die Kombination der folgenden Parameter identifiziert jedes CustomAudience-Objekt auf einem Gerät eindeutig:

• owner: Paketname der Eigentümer-App. Dieser wird implizit auf den Paketnamen der aufrufenden App festgelegt.
• buyer: Kennung für das Werbenetzwerk des Käufers, das Anzeigen für diese benutzerdefinierte Zielgruppe verwaltet.
• name: Ein beliebiger Name oder eine beliebige Kennung für die benutzerdefinierte Zielgruppe.

Wenn Sie joinCustomAudience() wiederholt mit einer anderen Instanz von CustomAudience aufrufen, werden alle vorhandenen CustomAudience mit übereinstimmenden owner, buyer- und name-Parametern aktualisiert. Zum Schutz der Privatsphäre wird im Ergebnis der API nicht zwischen „Erstellung“ und „Aktualisierung“ unterschieden.

Außerdem muss die CustomAudience mit den folgenden erforderlichen Parametern erstellt werden:

• URL für die tägliche Aktualisierung: Eine HTTPS-URL, die täglich im Hintergrund abgefragt wird, um die Signale für Gebote von Nutzern, vertrauenswürdige Gebotsdaten sowie Rendering-URLs und Metadaten für Anzeigen einer benutzerdefinierten Zielgruppe zu aktualisieren.
• URL der Gebotslogik: Eine HTTPS-URL, die während der Anzeigenauswahl abgefragt wird, um die JavaScript-Gebotslogik eines Käufers abzurufen. Die erforderlichen Funktionssignaturen finden Sie in diesem JavaScript-Code.
• Anzeigen-Render-IDs: Eine beliebige ID, die von der Anzeigentechnologie des Käufers festgelegt wird. Dies ist eine Optimierung für die Generierung der Nutzlast für B&A.

Optionale Parameter für ein CustomAudience-Objekt können Folgendes umfassen:

• Aktivierungszeit: Eine benutzerdefinierte Zielgruppe kann erst nach der Aktivierung an der Anzeigenauswahl und den täglichen Aktualisierungen teilnehmen. Das kann beispielsweise nützlich sein, um inaktive Nutzer einer App zu erreichen.
• Ablaufzeit: Ein zukünftiger Zeitpunkt, nach dem die benutzerdefinierte Zielgruppe vom Gerät entfernt wird.
• Nutzersignale für Gebote: Ein JSON-String mit Nutzersignalen wie der bevorzugten Sprache des Nutzers, die von der JavaScript-Gebotslogik eines Käufers verwendet wird, um während der Anzeigenauswahl Gebote zu generieren. Dieses Format ermöglicht es AdTech-Plattformen, Code plattformübergreifend wiederzuverwenden und die Verwendung in JavaScript-Funktionen zu vereinfachen.
• Vertrauenswürdige Gebotsdaten: Eine HTTPS-URL und eine Liste von Strings, die während der Anzeigenauswahl verwendet werden, um Gebotssignale von einem vertrauenswürdigen Schlüssel/Wert-Dienst abzurufen.
• Anzeigen: Liste der AdData-Objekte, die den Anzeigen entsprechen, die bei der Anzeigenauswahl berücksichtigt werden. Jedes AdData-Objekt besteht aus:
  • Render-URL: Eine HTTPS-URL, die zum Rendern der finalen Anzeige abgefragt wird.
  • Metadaten: Ein als String serialisiertes JSON-Objekt mit Informationen, die von der Gebotslogik des Käufers während der Anzeigenauswahl verwendet werden.
  • Anzeigenfilter: Eine Klasse, die alle erforderlichen Informationen für die Installation von Anzeigenfiltern und die Häufigkeitsbeschränkung bei der Anzeigenauswahl enthält.

Hier ein Beispiel für die Objektinstanziierung von CustomAudience:

// Minimal initialization of a CustomAudience object
val customAudience: CustomAudience = CustomAudience.Builder()
    .setBuyer(AdTechIdentifier.fromString("my.buyer.domain.name"))
    .setName("example-custom-audience-name")
    .setDailyUpdateUrl(Uri.parse("https://DAILY_UPDATE_URL"))
    .setBiddingLogicUrl(Uri.parse("https://BIDDING_LOGIC_URL"))
    .build()

// Minimal initialization of a CustomAudience object
CustomAudience customAudience = CustomAudience.Builder()
    .setBuyer(AdTechIdentifier.fromString("my.buyer.domain.name"))
    .setName("example-custom-audience-name")
    .setDailyUpdateUrl(Uri.parse("https://DAILY_UPDATE_URL"))
    .setBiddingLogicUrl(Uri.parse("https://BIDDING_LOGIC_URL"))
    .build();

Ergebnisse von „joinCustomAudience()“ verarbeiten

Bei der asynchronen Methode joinCustomAudience() wird das Objekt OutcomeReceiver verwendet, um das Ergebnis des API-Aufrufs zu signalisieren.

• Der onResult()-Callback gibt an, dass die benutzerdefinierte Zielgruppe erfolgreich erstellt oder aktualisiert wurde.
• Der onError()-Callback steht für zwei mögliche Bedingungen.
  • Wenn JoinCustomAudienceRequest mit ungültigen Argumenten initialisiert wird, gibt AdServicesException IllegalArgumentException als Ursache an.
  • Bei allen anderen Fehlern wird AdServicesException mit IllegalStateException als Ursache zurückgegeben.

Hier ein Beispiel für die Verarbeitung des Ergebnisses von joinCustomAudience():

var callback: OutcomeReceiver<Void, AdServicesException> =
    object : OutcomeReceiver<Void, AdServicesException> {
    override fun onResult(result: Void) {
        Log.i("CustomAudience", "Completed joinCustomAudience")
    }

    override fun onError(error: AdServicesException) {
        // Handle error
        Log.e("CustomAudience", "Error executing joinCustomAudience", error)
    }
};

OutcomeReceiver callback = new OutcomeReceiver<Void, AdServicesException>() {
    @Override
    public void onResult(@NonNull Void result) {
        Log.i("CustomAudience", "Completed joinCustomAudience");
    }

    @Override
    public void onError(@NonNull AdServicesException error) {
        // Handle error
        Log.e("CustomAudience", "Error executing joinCustomAudience", error);
    }
};

Benutzerdefinierte Zielgruppe verlassen

Wenn der Nutzer nicht mehr die Geschäftskriterien für eine bestimmte benutzerdefinierte Zielgruppe erfüllt, kann eine App oder ein SDK leaveCustomAudience() aufrufen, um die benutzerdefinierte Zielgruppe vom Gerät zu entfernen. So entfernen Sie eine CustomAudience anhand ihrer eindeutigen Parameter:

1. Initialisieren Sie das CustomAudienceManager-Objekt.
2. Initialisieren Sie die LeaveCustomAudienceRequest mit der buyer und der name der benutzerdefinierten Zielgruppe. Weitere Informationen zu diesen Eingabefeldern finden Sie unter Benutzerdefinierte Zielgruppen zusammenführen.
3. Rufen Sie die asynchrone leaveCustomAudience()-Methode mit dem LeaveCustomAudienceRequest-Objekt und den relevanten Executor- und OutcomeReceiver-Objekten auf.

val customAudienceManager: CustomAudienceManager =
    context.getSystemService(CustomAudienceManager::class.java)

// Initialize a LeaveCustomAudienceRequest
val leaveCustomAudienceRequest: LeaveCustomAudienceRequest =
    LeaveCustomAudienceRequest.Builder()
        .setBuyer(buyer)
        .setName(name)
        .build()

// Request to leave a custom audience
customAudienceManager.leaveCustomAudience(
    leaveCustomAudienceRequest,
    executor,
    outcomeReceiver)

CustomAudienceManager customAudienceManager =
    context.getSystemService(CustomAudienceManager.class);

// Initialize a LeaveCustomAudienceRequest
LeaveCustomAudienceRequest leaveCustomAudienceRequest =
    new LeaveCustomAudienceRequest.Builder()
        .setBuyer(buyer)
        .setName(name)
        .build();

// Request to leave a custom audience
customAudienceManager.leaveCustomAudience(
    leaveCustomAudienceRequest,
    executor,
    outcomeReceiver);

Ähnlich wie beim Aufrufen von joinCustomAudience() signalisiert OutcomeReceiver das Ende eines API-Aufrufs. Aus Datenschutzgründen wird bei einem Fehlerergebnis nicht zwischen internen Fehlern und ungültigen Argumenten unterschieden. Der onResult()-Callback wird aufgerufen, wenn der API-Aufruf abgeschlossen ist, unabhängig davon, ob eine übereinstimmende benutzerdefinierte Zielgruppe erfolgreich entfernt wurde.

Anzeigenauswahl ausführen

Wenn Sie Anzeigen mit der Protected Audience API auswählen möchten, rufen Sie die Methode selectAds() auf:

1. Initialisieren Sie ein AdSelectionManager-Objekt.
2. Erstellen Sie ein AdSelectionConfig-Objekt.
3. Rufen Sie die asynchrone selectAds()-Methode mit dem AdSelectionConfig-Objekt und den relevanten Executor- und OutcomeReceiver-Objekten auf.

val adSelectionManager: AdSelectionManager =
  context.getSystemService(AdSelectionManager::class.java)

// Initialize AdSelectionConfig
val adSelectionConfig: AdSelectionConfig =
  AdSelectionConfig.Builder().setSeller(seller)
    .setDecisionLogicUrl(decisionLogicUrl)
    .setCustomAudienceBuyers(customAudienceBuyers)
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .setBuyerContextualAds(
      Collections.singletonMap(
        contextualAds.getBuyer(), contextualAds
      )
    ).build()

// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(
  adSelectionConfig, executor, outcomeReceiver
)

AdSelectionManager adSelectionManager =
    context.getSystemService(AdSelectionManager.class);

// Initialize AdSelectionConfig
AdSelectionConfig adSelectionConfig =
  new AdSelectionConfig.Builder()
    .setSeller(seller)
    .setDecisionLogicUrl(decisionLogicUrl)
    .setCustomAudienceBuyers(customAudienceBuyers)
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .setBuyerContextualAds(
      Collections.singletonMap(contextualAds.getBuyer(), contextualAds)
    )
    .build();

// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(adSelectionConfig, executor, outcomeReceiver);

Für die Methode selectAds() ist eine AdSelectionConfig-Eingabe erforderlich, bei der Sie die folgenden erforderlichen Parameter angeben müssen:

• Verkäufer: Kennung für das Anzeigennetzwerk des Verkäufers, das die Anzeigenauswahl initiiert.
• URL der Entscheidungslogik: Eine HTTPS-URL, über die die JavaScript-Logik des Werbenetzwerks des Verkäufers abgerufen wird.
  • HTTPS-URL: Wird abgefragt, um die JavaScript-Logik des Werbenetzwerks des Verkäufers abzurufen. Weitere Informationen finden Sie unter Erforderliche Funktionssignaturen.
  • Vordefinierter URI: entspricht dem Format für die Anzeigenauswahl von FLEDGE. IllegalArgumentException wird geworfen, wenn ein nicht unterstützter oder fehlerhafter vordefinierter URI übergeben wird.
• Käufer mit benutzerdefinierten Zielgruppen: Eine vollständige Liste der IDs für Käufer-Werbenetzwerke, die vom Verkäufer zur Teilnahme am Anzeigenauswahlprozess zugelassen sind. Diese Käufer-IDs entsprechen CustomAudience.getBuyer() der teilnehmenden benutzerdefinierten Zielgruppen.

Für eine individuellere Anzeigenauswahl können Sie optional die folgenden Parameter angeben:

• Signale für die Anzeigenauswahl: Ein JSON-Objekt, das als String serialisiert ist und Signale enthält, die von der JavaScript-Gebotslogik für Käufer verwendet werden, die von CustomAudience.getBiddingLogicUrl() abgerufen wird.
• Verkäufersignale: Ein JSON-Objekt, das als String serialisiert ist und Signale enthält, die von der vom Verkäufer abgerufenen JavaScript-Entscheidungslogik aus AdSelectionConfig.getDecisionLogicUrl() verwendet werden.
• Signale pro Käufer: Eine Zuordnung von JSON-Objekten, die als Strings serialisiert sind und Signale enthalten, die von der Gebotslogik bestimmter Käufer verwendet werden. Das JavaScript wird aus CustomAudience.getBiddingLogicUrl() abgerufen und die Signale werden anhand der Käuferfelder der teilnehmenden benutzerdefinierten Zielgruppen identifiziert.
• Kontextbezogene Anzeigen: Eine Sammlung von Anzeigenkandidaten, die während einer Auktion direkt von Käufern erfasst werden, die nicht für eine Auktion mit geschützten Zielgruppen gilt.

Sobald eine Anzeige ausgewählt wurde, werden die Ergebnisse, Gebote und Signale intern für die Berichterstellung gespeichert. Der OutcomeReceiver.onResult()-Callback gibt ein AdSelectionOutcome zurück, das Folgendes enthält:

• Eine Rendering-URL für die Anzeige, die gewonnen hat, die von AdData.getRenderUrl() abgerufen wird.
• Eine eindeutige Anzeigenauswahl-ID für den Gerätenutzer. Diese ID wird für die Berichterstellung zur Anzeigenimpression verwendet.

Wenn die Anzeigenauswahl aus Gründen wie ungültigen Argumenten, Zeitüberschreitungen oder übermäßigem Ressourcenverbrauch nicht abgeschlossen werden kann, enthält der OutcomeReceiver.onError()-Callback eine AdServicesException mit den folgenden Verhaltensweisen:

• Wenn die Anzeigenauswahl mit ungültigen Argumenten gestartet wird, gibt AdServicesException IllegalArgumentException als Ursache an.
• Bei allen anderen Fehlern wird AdServicesException mit IllegalStateException als Ursache zurückgegeben.

Kontextbasierte Anzeigen

Mit Protected Audience können kontextbezogene Anzeigen in eine Protected Audience-Auktion einbezogen werden. Kontextbezogene Anzeigen müssen auf dem Anzeigentechnologie-Server ausgewählt und außerhalb der Protected Audience APIs an das Gerät zurückgegeben werden. Kontextbezogene Anzeigen können dann über die AdSelectionConfig in die Auktion aufgenommen werden. Sie funktionieren dann genauso wie auf dem Gerät platzierte Anzeigen, einschließlich der Eignung für den Ausschluss von Anzeigen. Sobald die Auktion für geschützte Zielgruppen abgeschlossen ist, müssen Sie reportImpression() aufrufen. Dadurch wird reportWin() in der ausgelieferten kontextbezogenen Anzeige aufgerufen, und zwar nach demselben Muster wie bei Impressionsberichten, um die ausgelieferte Anzeige auf einem Gerät zu empfangen. Für jede kontextbezogene Anzeige sind ein Käufer, ein Gebot, ein Link zur Berichtslogik, eine Rendering-URL und Anzeigenmetadaten erforderlich.

Wenn Sie kontextbezogene Anzeigen in der App bereitstellen möchten, muss die Ziel-App ein ContextualAds-Objekt erstellen:

val contextualAds: ContextualAds =
  Builder().setBuyer(AdTechIdentifier.fromString(mBiddingLogicUri.getHost()))
    //Pass in your valid app install ads
    .setDecisionLogicUri(mContextualLogicUri)
    .setAdsWithBid(appInstallAd)
    .build()

ContextualAds contextualAds = new ContextualAds.Builder()
  .setBuyer(AdTechIdentifier.fromString(mBiddingLogicUri.getHost()))
  .setDecisionLogicUri(mContextualLogicUri)
  //Pass in your valid app install ads
  .setAdsWithBid(appInstallAd)
  .build();

Das resultierende ContextualAds-Objekt kann dann beim Erstellen der AdSelectionConfig übergeben werden:

// Create a new ad
val noFilterAd: AdData = Builder()
  .setMetadata(JSONObject().toString())
  .setRenderUri(Uri.parse(baseUri + NO_FILTER_RENDER_SUFFIX))
  .build()
val noFilterAdWithBid = AdWithBid(noFilterAd, NO_FILTER_BID)
contextualAds.getAdsWithBid().add(noFilterAdWithBid)

// Create a new ad
AdData noFilterAd = new AdData.Builder()
  .setMetadata(new JSONObject().toString())
  .setRenderUri(Uri.parse(baseUri + NO_FILTER_RENDER_SUFFIX))
  .build();
AdWithBid noFilterAdWithBid = new AdWithBid(noFilterAd, NO_FILTER_BID);
contextualAds.getAdsWithBid().add(noFilterAdWithBid);

App-Installationsanzeigen filtern

Mit dem Filter für App-Installationsanzeigen können Sie Installationsanzeigen für Apps herausfiltern, die bereits auf einem Gerät installiert sind.

Im ersten Schritt müssen Sie festlegen, welche Werbetreibenden nach dem installierten Paket filtern können. Das muss in der App geschehen, auf die Sie eine Anzeige ausrichten möchten.

//Create a request for setting the app install advertisers
val adtech = AdTechIdentifier.fromString("your.enrolled.uri")
val adtechSet = setOf(adtech)
val request = SetAppInstallAdvertisersRequest(adtechSet)

//Set the app install advertisers in the ad selection manager
mAdSelectionManager.setAppInstallAdvertisers(
  request,
  mExecutor,
  object : OutcomeReceiver<Any?, Exception?>() {
    fun onResult(@NonNull ignoredResult: Any?) {
      Log.v("[your tag]", "Updated app install advertisers")
    }

    fun onError(@NonNull error: Exception?) {
      Log.e("[your tag]", "Failed to update app install advertisers", error)
    }
  })

//Create a request for setting the app install advertisers
AdTechIdentifier adtech = AdTechIdentifier.fromString("your.enrolled.uri");
Set<AdTechIdentifier> adtechSet = Collections.singleton(adtech);
SetAppInstallAdvertisersRequest request = new SetAppInstallAdvertisersRequest(adtechSet);

//Set the app install advertisers in the ad selection manager
mAdSelectionManager.setAppInstallAdvertisers(
  request,
  mExecutor,
  new OutcomeReceiver<Object, Exception>() {
    @Override
    public void onResult(@NonNull Object ignoredResult) {
      Log.v("[your tag]", "Updated app install advertisers");
    }

    @Override
    public void onError(@NonNull Exception error) {
      Log.e("[your tag]", "Failed to update app install advertisers", error);
    }
  });

Wenn der Code oben ausgeführt wird, können die übergebenen Werbetreibenden die von Ihnen bei der Gebotserstellung angegebenen installierten Apps herausfiltern. Wenn Sie einem Werbetreibenden den Zugriff auf den Installationsstatus dieser App entziehen möchten, führen Sie diesen Code noch einmal aus, wobei die Informationen des Werbetreibenden entfernt werden.

Im nächsten Schritt wird der Anzeigenfilter in der Publisher-App eingerichtet. Die Partei, die die Anzeige in der Publisher-App ausliefert (höchstwahrscheinlich ein Supply-Side-SDK), muss ihr AdFilters-Objekt mit Informationen zu den Anzeigen in Bezug auf Apps initialisieren, die herausgefiltert werden sollen:

// Instantiate AdFilters object with package names.
val filters: AdFilters = Builder().setAppInstallFilters(
    Builder().setPackageNames(setOf("example.target.app")).build()
  ).build()

// Instantiate AdFilters object with package names.
AdFilters filters = new AdFilters.Builder()
.setAppInstallFilters(
  new AppInstallFilters.Builder()
  .setPackageNames(Collections.singleton("example.target.app"))
  .build())
.build();

Publisher auf der Nachfrageseite können auch eine AdFilter für Anzeigen festlegen, die in ihren benutzerdefinierten Zielgruppen vorhanden sind.

AdFilters kann auch beim Instanziieren eines neuen AdData-Objekts übergeben werden:

// Instantiate an AdData object with the AdFilters created in the
// previous example.
val appInstallAd: AdData =
  Builder().setMetadata("{ ... }") // Valid JSON string
    .setRenderUri(Uri.parse("www.example-dsp1.com/.../campaign123.html"))
    .setAdFilters(filters).build()

// Instantiate an AdData object with the AdFilters created in the
// previous example.
AdData appInstallAd = new AdData.Builder()
.setMetadata("{ ... }") // Valid JSON string
.setRenderUri(Uri.parse("www.example-dsp1.com/.../campaign123.html"))
    .setAdFilters(filters)
    .build();

Filterung nach Frequency Capping

Mit dem Frequency Capping-Filter können Anbieter von Anzeigentechnologien begrenzen, wie oft eine Anzeige ausgeliefert wird. Durch die Filterung nach Frequency Capping wird die Überpräsenz von Anzeigen reduziert und die Auswahl alternativer Anzeigen für eine bestimmte Werbekampagne optimiert.

Ein Filter für die Häufigkeitsobergrenze besteht aus zwei Hauptkomponenten: dem Anzeigenereignistyp und dem Anzeigenzählerschlüssel. Folgende Anzeigenereignistypen sind verfügbar:

• Gewinn: Ein Gewinnereignis gibt an, dass die Anzeige eine Auktion gewonnen hat. Gewinnereignisse werden automatisch von der Protected Audience API aktualisiert und können nicht direkt vom Entwickler aufgerufen werden. Daten zu erfolgreichen Anzeigen sind nur für Anzeigen innerhalb einer bestimmten benutzerdefinierten Zielgruppe sichtbar.
• Impression: Im Gegensatz zu reportImpression wird updateAdCounterHistogram() von einem On-Device-Caller (SSP oder MMP) verwendet, um Impressionsereignisse an einem beliebigen Punkt im Code aufzurufen. Impressionsereignisse sind für alle Anzeigen einer bestimmten DSP sichtbar und nicht auf Anzeigen in derselben benutzerdefinierten Zielgruppe beschränkt.
• Aufruf: Das Ereignis wird vom On-Device-Caller (SSP oder MMP) an einem beliebigen Punkt im Code über einen Aufruf von updateAdCounterHistogram() aufgerufen. Aufrufereignisse sind für alle Anzeigen einer bestimmten DSP sichtbar und nicht auf Anzeigen in derselben benutzerdefinierten Zielgruppe beschränkt.
• Klick: Das Ereignis wird vom On-Device-Caller (SSP oder MMP) an einem beliebigen Punkt im Code über einen Aufruf von updateAdCounterHistogram() aufgerufen. Klickereignisse sind für alle Anzeigen einer bestimmten DSP sichtbar und nicht auf Anzeigen in derselben benutzerdefinierten Zielgruppe beschränkt.

In der Publisher-App ruft eine SSP oder MMP, die auf dem Gerät vorhanden ist, Anzeigenereignisse auf. Wenn updateAdCounterHistogram() aufgerufen wird, wird der Zähler eines Frequency Capping-Filters erhöht, damit für zukünftige Auktionen aktuelle Informationen zur Auslieferung einer bestimmten Anzeige an einen Nutzer verfügbar sind. Die Anzeigenereignistypen sind nicht zwangsläufig mit der entsprechenden Nutzeraktion verknüpft. Sie dienen als Richtlinien, die Aufrufern helfen sollen, ihr Ereignissystem zu strukturieren. Um die Anzeigenzähler zum Zeitpunkt eines Ereignisses zu erhöhen, gibt der On-Device-Akteur die Anzeigenauswahl-ID der Gewinnerwerbungs-Auktion an.

Anzeigenzählerschlüssel sind beliebige vorzeichenbehaftete 32-Bit-Ganzzahlen, die von der Anzeigentechnologie eines Käufers zugewiesen werden. Sie entsprechen einer bestimmten Gruppe von Anzeigen, die von der DSP definiert wird. Da Anzeigenzählerschlüssel nur auf Anzeigen beschränkt sind, die zu einer bestimmten DSP gehören, können diese Schlüssel ausgewählt werden, ohne dass sie sich mit Histogrammen aus einer anderen Anzeigentechnologie überschneiden. Mit Anzeigenzählerschlüsseln werden DSP-spezifische Kennungen in den Anzeigen einer DSP oder innerhalb einer bestimmten benutzerdefinierten Zielgruppe erhöht, um Anzeigen aus zukünftigen Auktionen herauszufiltern.

Mithilfe von Zählerschlüsseln können Anzeigen priorisiert werden, die aufgrund der Interaktionen mit anderen Anzeigen einer bestimmten Anzeigentechnologie des Käufers mit höherer Wahrscheinlichkeit für einen bestimmten Nutzer interessant sind. Eine Anzeige, die aufgrund von gewonnenen Anzeigenauktionen, Aufrufen und Klicks eine hohe Interaktionsrate erzielt hat, ist beispielsweise ein abgeleiteter Datenpunkt. Zur Veranschaulichung: Eine Anzeige für Golfschläger für Linkshänder könnte darauf hinweisen, dass der Nutzer nicht an Schlägern für Rechtshänder interessiert ist. Ein Frequency Capping-Filter, der für einen Zählerschlüssel festgelegt ist, der Anzeigen für Linkshänder zugewiesen ist, könnte Anzeigen für Rechtshänder herausfiltern.

Wenn Sie das Frequency Capping in Ihrer Auktion verwenden möchten, müssen Sie zuerst KeyedFrequencyCap-Objekte erstellen:

// Value used when incrementing frequency counter
val adCounterKey = 123

// Frequency cap exceeded after 2 counts
val keyedFrequencyCapForImpression: KeyedFrequencyCap = Builder(
  adCounterKey, 2, Duration.ofSeconds(10)
).build()

// Frequency cap exceeded after 1 counts
val keyedFrequencyCapForImpression: KeyedFrequencyCap = Builder(
  adCounterKey, 1, Duration.ofSeconds(10)
).build()

// Value used when incrementing frequency counter
int adCounterKey = 123;

// Frequency cap exceeded after 2 counts
KeyedFrequencyCap keyedFrequencyCapForImpression =
  new KeyedFrequencyCap.Builder(
    adCounterKey, 2, Duration.ofSeconds(10)
  ).build();

// Frequency Cap exceeded after 1 counts
KeyedFrequencyCap keyedFrequencyCapForClick =
  new KeyedFrequencyCap.Builder(
    adCounterKey, 1, Duration.ofSeconds(10)
  ).build();

Nachdem die KeyedFrequencyCap-Objekte erstellt wurden, können Sie sie an ein AdFilters-Objekt übergeben.

val filters: AdFilters = Builder()
  .setFrequencyCapFilters(
    Builder()
      .setKeyedFrequencyCapsForImpressionEvents(
        ImmutableObject.of(keyedFrequencyCapForImpression)
      )
      .setKeyedFrequencyCapsForClickEvents(
        ImmutableObject.of(keyedFrequencyCapForClick)
      )
  ).build()

AdFilters filters = new AdFilters.Builder()
    .setFrequencyCapFilters(new FrequencyCapFilters.Builder()
        .setKeyedFrequencyCapsForImpressionEvents(
            ImmutableObject.of(keyedFrequencyCapForImpression)
        )
        .setKeyedFrequencyCapsForClickEvents(
            ImmutableObject.of(keyedFrequencyCapForClick)
        )
    ).build();

Wenn das AdFilters-Objekt mit Filtern für das Frequency Capping ausgefüllt ist, kann es beim Erstellen der benutzerdefinierten Zielgruppe übergeben werden:

// Initialize a custom audience.
val audience: CustomAudience = Builder()
  .setBuyer(buyer)
  .setName(name)
  .setAds(
    listOf(
      Builder()
        .setRenderUri(renderUri)
        .setMetadata(JSONObject().toString())
        .setAdFilters(filters)
        .setAdCounterKeys(adCounterKeys)
        .build()
    )
  ).build()

// Initialize a custom audience.
CustomAudience audience = new CustomAudience.Builder()
    .setBuyer(buyer)
    .setName(name)
    .setAds(Collections.singletonList(new AdData.Builder()
        .setRenderUri(renderUri)
        .setMetadata(new JSONObject().toString())
        .setAdFilters(filters)
        .setAdCounterKeys(adCounterKeys)
        .build()))
    .build();

Wenn Filter für die Häufigkeitsobergrenze in eine benutzerdefinierte Zielgruppe implementiert werden, kann die SSP die erforderlichen Klick-, Aufruf- oder Impressionsereignisse aufrufen.

val callerAdTech: AdTechIdentifier = mAdSelectionConfig.getSeller()

val request: UpdateAdCounterHistogramRequest = Builder(
  adSelectionId,
  FrequencyCapFilters.AD_EVENT_TYPE_CLICK,  //CLICK, VIEW, or IMPRESSION
  callerAdTech
).build()

AdTechIdentifier callerAdTech = mAdSelectionConfig.getSeller();

UpdateAdCounterHistogramRequest request =
  new UpdateAdCounterHistogramRequest.Builder(
      adSelectionId,
      FrequencyCapFilters.AD_EVENT_TYPE_CLICK, //CLICK, VIEW, or IMPRESSION
      callerAdTech
).build();

Anzeigen, die die voreingestellten Filterlimits für das Frequency Capping erreicht haben, werden aus der Auktion herausgefiltert. Die Filterung erfolgt, bevor die Gebotslogik für On-Device-Auktionen ausgeführt wird und während die Nutzlast für Gebote und Auktionsdienste generiert wird.Mit diesem Toolkit können Werbetreibende die Interaktionen zwischen Nutzern und Anzeigen in ihren benutzerdefinierten Zielgruppen flexibel nutzen, um das Anzeigen-Targeting zu konzentrieren und gleichzeitig eine übermäßige Anzeigenpräsenz zu vermeiden.

Kontextbezogene Anzeigenfilterung ohne Netzwerkaufrufe

Wenn auf dem Gerät keine Remarketing-Nachfrage vorhanden ist, können Sie die Anzeigenauswahl für kontextbezogene Anzeigen ohne Netzwerkaufrufe ausführen. Mit vordefinierten URIs und einer Liste mit kontextbezogenen Anzeigen mit Geboten kann die Plattform das Abrufen von Gebotslogik, Gebotssignalen und Bewertungssignalen überspringen. Die Plattform verwendet einen vordefinierten URI, um die kontextbezogene Anzeige mit dem höchsten Gebot auszuwählen.

Um die Latenz zu verbessern, können Anzeigentechnologien einen Anzeigenauswahlvorgang ausführen, der nur kontextbezogene Anzeigen mit Anzeigenfilterfunktion ohne Netzwerkaufrufe enthält. Dazu werden vordefinierte URIs für die Signalbewertung verwendet. Eine Liste der scoreAds-Implementierungen finden Sie im Abschnitt Unterstützte vordefinierte URI-Anwendungsfälle und ‑Namen.

So führen Sie die Anzeigenauswahl ohne Netzwerkaufrufe durch:

1. Anzeigenfilterung einrichten
2. Kontextbezogene Anzeigen erstellen

3. Erstellen Sie ein AdSelectionConfig-Objekt mit folgenden Angaben:

   1. Eine leere Liste von Käufern
   2. Ein vordefinierter URI, um das höchste Gebot auszuwählen
   3. Kontextbasierte Anzeigen
   4. Ein leerer URI für die Bewertungssignale. Mit einem leeren URI können Sie angeben, dass Sie das Abrufen vertrauenswürdiger Signale nicht für die Bewertung verwenden möchten:

   Uri prebuiltURIScoringUri = Uri.parse("ad-selection-prebuilt://ad-selection/highest-bid-wins/?reportingUrl=your.registered.uri/reporting");
   // Initialize AdSelectionConfig
   AdSelectionConfig adSelectionConfig =
     new AdSelectionConfig.Builder()
       .setSeller(seller)
       .setDecisionLogicUri(prebuiltURIScoringUri)
       .setCustomAudienceBuyers(Collections.emptyList())
       .setAdSelectionSignals(adSelectionSignals)
       .setSellerSignals(sellerSignals)
       .setPerBuyerSignals(perBuyerSignals)
       .setBuyerContextualAds(buyerContextualAds)
       .setTrustedScoringSignalsUri(Uri.EMPTY)
       .build();
   

4. Anzeigenauswahl ausführen:

   adSelectionManager.selectAds(
       adSelectionConfig,
       executor,
       outcomeReceiver);
   

Eigenes JavaScript für Berichte ausführen und vordefinierte URIs verwenden

Derzeit ist auf der Privacy Sandbox-Plattform nur eine grundlegende JavaScript-Implementierung für Berichte für vordefinierte URIs verfügbar. Wenn Sie Ihr eigenes JavaScript für Berichte ausführen und gleichzeitig vordefinierte URIs für eine Anzeigenauswahl mit geringer Latenz verwenden möchten, können Sie DecisionLogicUri zwischen Anzeigenauswahl und Berichtsausführung überschreiben.

1. Führen Sie die Schritte aus, um die Anzeigenauswahl für kontextbezogene Anzeigen mit vordefinierten URIs auszuführen.

2. Kopie der AdSelectionConfig erstellen, bevor Berichte erstellt werden

   adSelectionConfigWithYourReportingJS = adSelectionConfig.cloneToBuilder()
     // Replace <urlToFetchYourReportingJS> with your own URL:
     .setDecisionLogicUri(Uri.parse(<urlToFetchYourReportingJS>))
     .build();
   

3. Impressionsberichte erstellen

   // adSelectionId is from the result of the previous selectAds run
   ReportImpressionRequest request = new ReportImpressionRequest(
     adSelectionId,
     adSelectionConfigWithYourReportingJS);
   adSelectionManager.reportImpression(
     request,
     executor,
     outcomeReceiver);
   

Vermittlungsabfolge ausführen

Für die abfolgebasierte Vermittlung müssen mehrere Drittanbieter-SDKs (Drittanbieternetzwerke) von einem Vermittlungsnetzwerk mit Erstanbieter-SDK verwaltet werden. Die abfolgebasierte Vermittlung erfolgt auf die gleiche Weise, unabhängig davon, ob die Auktion auf dem Gerät oder über Bidding & Auction Services (B&A) stattgefunden hat.

Drittanbieternetzwerke

Drittanbieternetzwerke müssen einen Adapter bereitstellen, mit dem das Vermittlungsnetzwerk die erforderlichen Methoden zum Ausführen einer Auktion aufrufen kann:

• Anzeigenauswahl ausführen
• Impressionen erfassen

Hier ein Beispiel für einen Adapter für ein Vermittlungsnetzwerk:

class NetworkAdaptor {
    private val adSelectionManager : AdSelectionManager

    init {
        adSelectionManager = context.getSystemService(AdSelectionManager::class.java)
    }

    fun selectAds() {...}

    fun reportImpressions() {...}
}

class NetworkAdaptor {
    AdSelectionManager adSelectionManager;

    public NetworkAdaptor() {
        AdSelectionManager adSelectionManager =
            context.getSystemService(AdSelectionManager.class);
    }

    public void selectAds() {...}

    public void reportImpressions() {...}
}

Jedes SDK hat eigene Dienstmanager und ‑kunden für die Anzeigenauswahl sowie eigene selectAds- und reportImpressions-Implementierungen. SDK-Anbieter können die Abschnitte zur Anzeigenauswahl für On-Device-Auktionen oder die B&A-Erläuterung für B&A-Auktionen lesen. Berichte zu Anzeigenimpressionen erstellen (Berichte zu Impressionen für einzelne SSPs)

Vermittlungsnetzwerk

Ähnlich wie bei Drittanbieternetzwerken sind für Vermittlungsnetzwerke selectAds- und reportImpression-Implementierungen erforderlich. Weitere Informationen finden Sie in den Abschnitten zur Ausführung der Anzeigenauswahl und zum Erfassen von Anzeigenimpressionen.

Vermittlungsnetzwerke sind für die Ausführung der Vermittlungskette und ihre Platzierung in der Vermittlungskette verantwortlich. Im nächsten Abschnitt erfahren Sie, wie Sie diesen Prozess einrichten und ausführen.

Vermittlungskette und Gebotsuntergrenzen abrufen

Das Vermittlungsnetzwerk ist für das Abrufen der selbst erhobenen (1P) kontextbezogenen Anzeigen, der Vermittlungskette und der Gebotsuntergrenzen (3P) von Drittanbieternetzwerken verantwortlich. Das kann bei einer Anfrage zum Abrufen von kontextbezogenen Anzeigen passieren, die vom Vermittlungsnetzwerk ausgeführt wird. Die Vermittlungsabfolge bestimmt, wie die Drittanbieternetzwerke durchlaufen werden. Die Gebotsuntergrenzen können als adSelectionSignals an den Auktionsprozess übergeben werden.

Netzwerk-Placement in der Vermittlungskette

Ein Vermittlungs-SDK kann sich basierend auf dem Echtzeit-eCPM von selbst erhobenen Anzeigengeboten in der Vermittlungskette platzieren. In der Protected Audience API sind Anzeigengebote nicht transparent. Ein Mediation-SDK sollte AdSelectionFromOutcomesConfig verwenden, um das Gebot einer bestimmten Anzeigenanzeige mit dem Mindestgebot des nächsten Drittanbieternetzwerks in der Kette zu vergleichen. Wenn das Gebot aus selbst erhobenen Daten über dem Mindestgebot liegt, wird das Mediation SDK vor dem Drittanbieternetzwerk platziert.

Anzeigenauswahl ausführen

Um einen Anzeigenkandidaten aus selbst erhobenen Daten abzurufen, kann das Vermittlungsnetzwerk eine On-Device-Auktion ausführen. Folgen Sie dazu der Anleitung im Abschnitt Anzeigenauswahl ausführen. Dadurch werden ein Anzeigenkandidat aus selbst erhobenen Daten, ein Gebot und ein AdSelectionId generiert, die im Vermittlungsprozess verwendet werden.

AdSelectionFromOutcomesConfig erstellen

Mit einem AdSelectionFromOutcomesConfig kann das Vermittlungsnetzwerk eine Liste von AdSelectionIds (Ergebnisse aus vorherigen Auktionen), Signale zur Anzeigenauswahl und einen URI zum Abrufen von JavaScript übergeben, mit dem eine Anzeige aus mehreren Kandidaten ausgewählt wird. Die Liste der Anzeigenauswahl-IDs zusammen mit den Geboten und den Signalen wird an das JavaScript übergeben, das eine der AdSelectionIds zurückgeben kann, wenn der Mindestgebotspreis unterschritten wird, oder keine, wenn die Vermittlungskette fortgesetzt werden soll.

Vermittlungsnetzwerke erstellen eine AdSelectionFromOutcomesConfig mithilfe der AdSelectionId aus dem vorherigen Abschnitt und des Mindestgebots für das Drittanbieternetzwerk, das berücksichtigt werden soll. Für jeden Schritt in der Vermittlungskette sollte eine neue AdSelectionFromOutcomesConfig erstellt werden.

fun  runSelectOutcome(
    adSelectionClient : AdSelectionClient,
    outcome1p : AdSelectionOutcome,
    network3p : NetworkAdapter) : ListenableFuture<AdSelectionOutcome?> {
    val config = AdSelectionFromOutcomesConfig.Builder()
        .setSeller(seller)
        .setAdSelectionIds(listOf(outcome1p))
        .setSelectionSignals({"bid_floor": bid_floor})
        .setSelectionLogicUri(selectionLogicUri)
        .build()
    return adSelectionClient.selectAds(config)
}

public ListenableFuture<AdSelectionOutcome> runSelectOutcome(AdSelectionOutcome outcome1p,
                                              NetworkAdapter network3p) {
    AdSelectionFromOutcomesConfig config = new AdSelectionFromOutcomesConfig.Builder()
            .setSeller(seller)
            .setAdSelectionIds(Collection.singletonList(outcome1p))
            .setSelectionSignals({"bid_floor": bid_floor})
            .setSelectionLogicUri(selectionLogicUri)
            .build();

    return adSelectionClient.selectAds(config){}
}

Für die Methode selectAds() für die abfolgebasierte Vermittlung ist eine AdSelectionFromOutcomesConfig-Eingabe erforderlich, bei der Sie die folgenden erforderlichen Parameter angeben müssen:

• Verkäufer: Kennung für das Anzeigennetzwerk des Verkäufers, das die Anzeigenauswahl initiiert.
• AdSelectionIds: Eine einzelne Liste einer vorherigen selectAds()-Ausführung für eine selbst erhobenen Anzeige.
• Signale für die Anzeigenauswahl: Ein JSON-Objekt, das als String serialisiert ist und Signale enthält, die von der Gebotslogik des Käufers verwendet werden. Geben Sie in diesem Fall den Mindestgebotentwert an, der für das jeweilige Drittanbieternetzwerk abgerufen wurde.
• URI der Auswahllogik: Eine HTTPS-URL, die während der Anzeigenauswahl abgefragt wird, um das JavaScript des Vermittlungsnetzwerks zur Auswahl einer Anzeigenauslieferung abzurufen. Die erforderlichen Funktionssignaturen findest du in diesem JavaScript-Code. Das JavaScript sollte die Drittanbieteranzeige zurückgeben, wenn das Gebot über dem Mindestgebot liegt, andernfalls null. So kann das Vermittlungs-SDK die Vermittlungskette abbrechen, wenn ein Gewinner gefunden wird.

Rufe nach dem Erstellen von AdSelectionOutcomesConfig die selectAds()-Methode des Drittanbieternetzwerks auf, das zuerst in der Kette steht.

val adSelectionManager = context.getSystemService(AdSelectionManager::class.java)

// Initialize AdSelectionFromOutcomesConfig
AdSelectionFromOutcomesConfig adSelectionFromOutcomesConfig =
  AdSelectionFromOutcomesConfig.Builder()
    .setSeller(seller)
    .setAdSelectionIds(listof(outcome1p))
    .setSelectionSignals({"bid_floor": bid_floor})
    .setSelectionLogicUri(selectionLogicUri)
    .setAdSelectionIds(outcomeIds)
    .build()

// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(
    adSelectionFromOutcomesConfig,
    executor,
    outcomeReceiver)

AdSelectionManager adSelectionManager =
    context.getSystemService(AdSelectionManager.class);

// Initialize AdSelectionFromOutcomesConfig
AdSelectionFromOutcomesConfig adSelectionFromOutcomesConfig =
        new AdSelectionFromOutcomesConfig.Builder()
            .setSeller(seller)
            .setAdSelectionIds(Collection.singletonList(outcome1p))
            .setSelectionSignals({"bid_floor": bid_floor})
            .setSelectionLogicUri(selectionLogicUri)
            .setAdSelectionIds(outcomeIds)
            .build();

// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(
    adSelectionFromOutcomesConfig,
    executor,
    outcomeReceiver);

Vermittlungsabfolge orchestrieren

Im Folgenden wird die Reihenfolge der Schritte für die Vermittlung beschrieben.

1. Anzeigenauswahl mit selbst erhobenen Daten ausführen.
2. Für die Vermittlungskette iterieren. Gehen Sie für jedes Drittanbieternetzwerk so vor:
   1. Erstellen Sie AdSelectionFromOutcomeConfig unter Berücksichtigung des Mindestgebots für selbst erhobene Daten outcomeId und des Mindestgebots des Drittanbieter-SDKs.
   2. Rufe selectAds() mit der Konfiguration aus dem vorherigen Schritt auf.
   3. Wenn das Ergebnis nicht leer ist, geben Sie die Anzeige zurück.
   4. Rufen Sie die Methode selectAds() des aktuellen SDK-Netzwerkadapters auf. Wenn das Ergebnis nicht leer ist, geben Sie die Anzeige zurück.
3. Wenn in der Kette kein Gewinner gefunden wird, geben Sie die selbstverwaltete Anzeige zurück.

fun runWaterfallMediation(mediationChain : List<NetworkAdapter>)
  : Pair<AdSelectionOutcome, NetworkAdapter> {
    val outcome1p = runAdSelection()

    var outcome : AdSelectionOutcome
    for(network3p in mediationChain) {
      outcome = runSelectOutcome(outcome1p, network3p)
      if (outcome1p.hasOutcome() && outcome.hasOutcome()) {
          return Pair(outcome, this)
      }

      outcome = network3p.runAdSelection()
      if(outcome.hasOutcome()) {
          return Pair(outcome, network3p)
      }
    }
  return Pair(outcome1p, this)
}

class MediationNetwork {
    AdSelectionManager adSelectionManager;

    public MediationNetwork() {
        AdSelectionManager adSelectionManager =
            context.getSystemService(AdSelectionManager.class);
    }

    public void runAdSelection() {...}

    public void reportImpressions() {...}

    public Pair<AdSelectionOutcome, NetworkAdapter> runWaterfallMediation(
            List<NetworkAdapter> mediationChain) {
        AdSelectionOutcome outcome1p = runAdSelection();

        AdSelectionOutcome outcome;
        for(NetworkAdapter network3p: mediationChain) {
            if (outcome1p.hasOutcome() &&
              (outcome = runSelectOutcome(outcome1p, network3p)).hasOutcome()) {
                return new Pair<>(outcome, this);
            }

            if((outcome = network3p.runAdSelection()).hasOutcome()) {
                return new Pair<>(outcome, network3p);
            }
        }
        return new Pair<>(outcome1p, this);
    }

    /* Runs comparison by creating an AdSelectionFromOutcomesConfig */
    public AdSelectionOutcome runSelectOutcome(AdSelectionOutcome outcome1p,
                                              NetworkAdapter network3p) { ... }
}

Anzeigenimpressionen melden

Je nachdem, wie die Auktion abläuft, gibt es zwei Möglichkeiten, eine Anzeigenimpression zu erfassen. Wenn Sie eine einzelne SSP sind, die eine Auktion durchführt, folgen Sie diesem Abschnitt. Wenn Sie die abfolgebasierte Vermittlung implementieren möchten, folgen Sie der Anleitung im Abschnitt Berichte zu Impressionen bei der abfolgebasierten Vermittlung.

Berichte zu Impressionen einzelner SSPs

Nachdem im Workflow zur Anzeigenauswahl eine Anzeige ausgewählt wurde, können Sie die Impression mit der Methode AdSelectionManager.reportImpression() an die teilnehmenden Plattformen auf Käufer- und Verkäuferseite zurückmelden. So melden Sie eine Anzeigenimpression:

1. Initialisieren Sie ein AdSelectionManager-Objekt.
2. Erstellen Sie ein ReportImpressionRequest-Objekt mit der Anzeigenauswahl-ID.
3. Rufen Sie die asynchrone reportImpression()-Methode mit dem ReportImpressionRequest-Objekt und den relevanten Executor- und OutcomeReceiver-Objekten auf.

AdSelectionManager adSelectionManager =
    context.getSystemService(AdSelectionManager.class);

// Initialize a ReportImpressionRequest
ReportImpressionRequest reportImpressionRequest =
        new ReportImpressionRequest.Builder()
                .setAdSelectionId(adSelectionId)
                .setAdSelectionConfig(adSelectionConfig)
                .build();

// Request to report the impression with the ReportImpressionRequest
adSelectionManager.reportImpression(
    reportImpressionRequest,
    executor,
    outcomeReceiver);

val adSelectionManager = context.getSystemService(AdSelectionManager::class.java)

// Initialize a ReportImpressionRequest
val adSelectionConfig: ReportImpressionRequest =
    ReportImpressionRequest.Builder()
        .setAdSelectionId(adSelectionId)
        .setAdSelectionConfig(adSelectionConfig)
        .build()

// Request to report the impression with the ReportImpressionRequest
adSelectionManager.reportImpression(
    reportImpressionRequest,
    executor,
    outcomeReceiver)

Initialisieren Sie ReportImpressionRequest mit den folgenden erforderlichen Parametern:

• Anzeigenauswahl-ID: Eine eindeutige ID für einen Gerätenutzer, die eine erfolgreiche Anzeigenauswahl identifiziert.
• Anzeigenauswahlkonfiguration: Entspricht der Konfiguration, die im selectAds()-Aufruf verwendet wird und durch die angegebene Anzeigenauswahl-ID identifiziert wird.

Bei der asynchronen Methode reportImpression() wird das Objekt OutcomeReceiver verwendet, um das Ergebnis des API-Aufrufs zu signalisieren.

• Der onResult()-Callback gibt an, ob URLs für Impressionsberichte erstellt und die Anfrage geplant wurde.
• Der onError()-Callback gibt die folgenden möglichen Bedingungen an:
  • Wenn der Aufruf mit einem ungültigen Eingabeargument initialisiert wird, gibt AdServicesException IllegalArgumentException als Ursache an.
  • Bei allen anderen Fehlern wird AdServicesException mit IllegalStateException als Ursache zurückgegeben.

Impressionsberichte zur abfolgebasierten Vermittlung

Ein Vermittlungs-SDK muss das Gewinner-SDK im Blick behalten, um die Berichtsabläufe zu aktivieren. Die SDKs, die an einer Vermittlungskette teilnehmen, sollten eine Methode für den Vermittler bereitstellen, mit der er seinen eigenen Berichtsablauf auslösen kann. Wenn Sie ein SDK verwenden, das an einer vermittelten Auktion teilnimmt, können Sie die oben genannten Schritte ausführen, um eigene Berichte zu implementieren.

SSPs können dieses Beispiel für Drittanbieter-SDK-Code als Prototyp verwenden, um an Vermittlungsabläufen teilzunehmen:

Pair<AdSelectionOutcome, NetworkAdapter> winnerOutcomeAndNetwork =
         mediationSdk.orchestrateMediation(mediationChain);

if (winner.first.hasOutcome()) {
      winner.second.reportImpressions(winner.first.getAdSelectionId());

Endpunkte für Impressionsberichte

Die Report Impression API sendet HTTPS-GET-Anfragen an Endpunkte, die von der verkäuferseitigen Plattform und der siegreichen käuferseitigen Plattform bereitgestellt werden:

Endpunkt der Buy-Side-Plattform:

• Die API verwendet die in der benutzerdefinierten Zielgruppe angegebene URL der Gebotslogik, um das vom Käufer bereitgestellte JavaScript abzurufen, das eine Logik zum Zurückgeben einer URL für Impressionsberichte enthält.
• Rufen Sie die JavaScript-Funktion reportWin() auf, die voraussichtlich die URL der Impressionsberichte des Käufers zurückgibt.

Endpunkt der Sell-Side-Plattform:

• Verwenden Sie die im AdSelectionConfig-Objekt angegebene URL der Entscheidungslogik, um das JavaScript der Entscheidungslogik des Verkäufers abzurufen.
• Rufen Sie die JavaScript-Funktion reportResult() auf, die voraussichtlich die URL der Impressionsberichte des Verkäufers zurückgibt.

Berichte zu Gebots- und Auktionsdiensten

Bei einer Auktion, die über Bidding & Auction Services ausgeführt wird, sind alle erforderlichen Berichtsinformationen, einschließlich generierter URLs für Berichte zu Anzeigeninteraktionen, in der verschlüsselten Antwort der serverseitigen Auktion enthalten. Wenn die Antwort entschlüsselt wird, werden die entsprechenden URLs bei der Plattform registriert. Die Berichterstellung für Anzeigen und Impressionen erfolgt daher nach denselben Schritten.

Best-Effort-Impressionsberichte

Die Methode reportImpression() ist so konzipiert, dass Berichte nach dem Best-Effort-Prinzip erstellt werden.

Anzeigeninteraktionen melden

Mit Protected Audience können Sie detailliertere Berichte zu Interaktionen für eine gerenderte Anzeige erstellen. Das können Interaktionen wie Wiedergabezeit, Klicks, Mouseovers oder andere nützliche Messwerte sein, die erfasst werden können. Um diese Berichte zu erhalten, sind zwei Schritte erforderlich. Käufer und Verkäufer müssen sich zuerst registrieren, um diese Berichte in ihrem JavaScript-Code für Berichte zu erhalten. Anschließend muss der Kunde diese Ereignisse melden.

Registrierung für Interaktionsereignisse

Die Registrierung für Interaktionsereignisse erfolgt in den JavaScript-Funktionen reportWin() des Käufers und reportResult() des Verkäufers mithilfe einer von der Plattform bereitgestellten JavaScript-Funktion: registerAdBeacon. Wenn Sie sich für den Empfang eines Ereignisberichts registrieren möchten, rufen Sie die JavaScript-Funktion der Plattform aus Ihrem Berichts-JavaScript auf. Im folgenden Snippet wird die reportWin() eines Käufers verwendet, derselbe Ansatz gilt jedoch auch für reportResult().

reportWin(
  adSelectionSignals,
  perBuyerSignals,
  signalsForBuyer,
  contextualSignals,
  customAudienceSignals) {
    ...
    // Calculate reportingUri, clickUri, viewUri, and hoverUri

    registerAdBeacon({"click": clickUri, "view": viewUri, "hover": hoverUri});

    return reportingUri;
}

Interaktionsereignisse erfassen

Nachdem eine Impression erfasst wurde, können Kunden die Interaktionen mit der Methode AdSelectionManager.reportInteraction() an zuvor registrierte erfolgreiche Buy-Side- und Sell-Side-Plattformen zurückmelden. So melden Sie ein Anzeigenereignis:

1. Initialisieren Sie ein AdSelectionManager-Objekt.
2. Erstellen Sie ein ReportInteractionRequest-Objekt mit der Anzeigenauswahl-ID, dem Interaktionsschlüssel, den Interaktionsdaten und dem Berichtsziel.
3. Rufen Sie die asynchrone reportInteraction()-Methode mit dem request-Objekt und den relevanten Executor- und OutcomeReceiver-Objekten auf.

AdSelectionManager adSelectionManager =
    context.getSystemService(AdSelectionManager.class);

// Initialize a ReportInteractionRequest
ReportInteractionRequest request =
  new ReportInteractionRequest.Builder()
    .setAdSelectionId(adSelectionId)
    .setInteractionKey("view")
    .setInteractionData("{ viewTimeInSeconds : 1 }") // Can be any string
    .setReportingDestinations(
      FLAG_REPORTING_DESTINATION_BUYER | FLAG_REPORTING_DESTINATION_SELLER
    )
    .build();

// Request to report the impression with the ReportImpressionRequest
adSelectionManager.reportInteraction(
  reportImpressionRequest,
  executor,
  outcomeReceiver);

Initialisieren Sie ReportInteractionRequest mit den folgenden erforderlichen Parametern:

• Anzeigenauswahl-ID: Eine Anzeigenauswahl-ID, die aus einer zuvor zurückgegebenen AdSelectionOutcome abgerufen wurde.
• Interaktionsschlüssel: Ein vom Kunden definierter Stringschlüssel, der die erfasste Aktion beschreibt. Er muss mit dem Schlüssel übereinstimmen, der vom Verkäufer oder Käufer in den JavaScript-Funktionen für die Berichterstellung registriert wurde.
• Interaktionsdaten: Ein String mit Daten, die in den Ereignisbericht aufgenommen und per POST an die Berichtsserver gesendet werden sollen.
• Meldeanwendungen: Eine Bitmaske, die angibt, ob die Ereignisse an den Käufer, den Verkäufer oder an beide gesendet werden sollen. Diese Flags werden von der Plattform bereitgestellt und die endgültige Zielmaske kann mit bitweisen Operationen erstellt werden. Wenn Sie eine Meldung an ein Ziel senden möchten, können Sie das Flag verwenden, das von der Plattform bereitgestellt wird. Wenn Sie Berichte an mehrere Ziele senden möchten, können Sie die bitweise OR-Verknüpfung (|) verwenden, um Flag-Werte zu kombinieren.

Bei der asynchronen reportInteraction()-Methode wird das Objekt OutcomeReceiver verwendet, um das Ergebnis des API-Aufrufs zu signalisieren.

• Der onResult()-Callback gibt an, dass der Anruf zur Interaktionsmeldung gültig ist.
• Der onError()-Callback gibt die folgenden möglichen Bedingungen an:
  • Wenn der Aufruf erfolgt, während die App im Hintergrund ausgeführt wird, wird IllegalStateException mit einer Beschreibung des Fehlers zurückgegeben.
  • Wenn der Client beim Aufrufen von reportInteraction() gedrosselt wird, wird LimitExceededException zurückgegeben.
  • Wenn das Paket nicht für den Aufruf der APIs zum Schutz der Privatsphäre registriert ist, wird SecurityException() zurückgegeben.
  • Wenn die App, die Interaktionen meldet, von der App abweicht, die selectAds() aufgerufen hat, wird IllegalStateException zurückgegeben.
• Wenn der Nutzer nicht zugestimmt hat, die Privacy Sandbox APIs zu aktivieren, schlägt der Aufruf stillschweigend fehl.

Endpunkte für Interaktionsberichte

Die Report Interaction API sendet HTTPS-POST-Anfragen an Endpunkte, die von der Sell-Side-Plattform und der Buy-Side-Plattform stammen, die den Zuschlag erhalten hat. Bei Protected Audience werden die Interaktionsschlüssel mit den URIs abgeglichen, die in JavaScript für die Berichterstellung deklariert wurden. Für jede Interaktion, die erfasst wird, wird dann eine POST-Anfrage an jeden Endpunkt gesendet. Der Content-Type der Anfrage ist ein Nur-Text-Format, der Textkörper enthält die Interaktionsdaten.

Best-Effort-Interaktionsberichte

Der reportInteraction() ist so konzipiert, dass Berichte nach dem Best-Effort-Prinzip über HTTP POST eingereicht werden.

Tägliches Hintergrundupdate

Beim Erstellen einer benutzerdefinierten Zielgruppe können Ihre App oder Ihr SDK Metadaten für benutzerdefinierte Zielgruppen initialisieren. Außerdem können die folgenden Metadaten für benutzerdefinierte Zielgruppen über einen täglichen Aktualisierungsprozess im Hintergrund aktualisiert werden.

• Signale für die Gebotseinstellung
• Daten für die vertrauenswürdige Gebotseinstellung
• AdData Liste

Dabei wird die in der benutzerdefinierten Zielgruppe definierte URL für die tägliche Aktualisierung abgefragt. Die URL kann eine JSON-Antwort zurückgeben.

• Die JSON-Antwort kann alle unterstützten Metadatenfelder enthalten, die aktualisiert werden müssen.
• Jedes JSON-Feld wird unabhängig geprüft. Der Client ignoriert alle fehlerhaften Felder, was dazu führt, dass dieses Feld in der Antwort nicht aktualisiert wird.
• Eine leere HTTP-Antwort oder ein leeres JSON-Objekt „{}“ führt zu keiner Aktualisierung der Metadaten.
• Die Größe der Antwortnachricht muss auf 10 KB begrenzt sein.
• Für alle URIs muss HTTPS verwendet werden.
• trusted_bidding_uri muss dieselbe ETLD+1 wie der Käufer haben.

Beispiel: JSON-Antwort für die tägliche Aktualisierung im Hintergrund

{
    "user_bidding_signals" : { ... },  // Valid JSON object
    "trusted_bidding_data" : {
        "trusted_bidding_uri" : 'example-dsp1-key-value-service.com',
        "trusted_bidding_keys" : [ 'campaign123', 'campaign456', ... ]
    },
    'ads' : [
        {
            "render_uri" : 'www.example-dsp1.com/.../campaign123.html',
            'metadata' : { ... }  // Valid JSON object
        },
        {
            "render_uri" : 'www.example-dsp1.com/.../campaign456.html',
            'metadata' : { ... }  // Valid JSON object
        },
        ...
    ]
}

JavaScript für die Anzeigenauswahl

Der Anzeigenauswahl-Workflow koordiniert die Ausführung von vom Käufer und vom Verkäufer bereitgestelltem JavaScript.

Das vom Käufer bereitgestellte JavaScript wird von der URL für die Gebotslogik abgerufen, die in der benutzerdefinierten Zielgruppe angegeben ist. Das zurückgegebene JavaScript sollte die folgenden Funktionen enthalten:

• generateBid()
• reportWin()

Vom Verkäufer bereitgestelltes JavaScript wird von der Entscheidungslogik-URL abgerufen, die im Parameter AdSelectionConfig für die Anzeigenauswahl-API angegeben ist. Das zurückgegebene JavaScript sollte die folgenden Funktionen enthalten:

• scoreAd()
• reportResult()

generateBid()

function generateBid(
  ad,
  auction_signals,
  per_buyer_signals,
  trusted_bidding_signals,
  contextual_signals,
  user_signals,
  custom_audience_bidding_signals) {
  return {'status': 0, 'ad': ad, 'bid': ad.metadata.result };
}

Eingabeparameter:

• ad: ein JSON-Objekt im Format var ad = { 'render_url': url, 'metadata': json_metadata };
• auction_signals, per_buyer_signals: JSON-Objekte, die im Auktionskonfigurationsobjekt angegeben sind

• custom_audience_bidding_signals: Von der Plattform generiertes JSON-Objekt. Das Format für dieses JSON-Objekt ist:

  var custom_audience_signals = {
    "owner":"ca_owner",
    "buyer":"ca_buyer",
    "name":"ca_name",
    "activation_time":"ca_activation_time_epoch_ms",
    "expiration_time":"ca_expiration_time_epoch_ms",
    "user_bidding_signals":"ca_user_bidding_signals"
  }
  

  Dabei gilt:

  • owner, buyer und name sind Strings aus den Properties mit demselben Namen wie die benutzerdefinierte Zielgruppe, die an der Anzeigenauswahl teilnimmt.
  • activation_time und expiration_time sind die Aktivierungs- und Ablaufzeit der benutzerdefinierten Zielgruppe, ausgedrückt in Sekunden seit der Unix-Epoche.
  • ca_user_bidding_signals ist ein JSON-String, der bei der Erstellung im Feld userBiddingSignals der CustomAudience angegeben wurde.
  • trusted_bidding_signals, contextual_signals und user_signals sind JSON-Objekte. Sie werden als leere Objekte übergeben und in zukünftigen Releases ausgefüllt. Das Format wird nicht von der Plattform erzwungen und wird von der Anzeigentechnologie verwaltet.

Ergebnis:

• ad: ist die Anzeige, auf die sich das Gebot bezieht. Das Script darf eine Kopie der empfangenen Anzeige mit anderen Metadaten zurückgeben. Das Attribut render_url der Anzeige sollte unverändert bleiben.
• bid: ein Gleitkommawert, der den Gebotspreis für diese Anzeige darstellt
• status: Ganzzahlwert, der einen der folgenden Werte haben kann:
  • 0: für eine erfolgreiche Ausführung
  • 1: (oder ein beliebiger Wert ungleich Null), falls eines der Eingabesignale ungültig ist. Wenn von „generate-bid“ ein Wert ungleich Null zurückgegeben wird, wird der Gebotsvorgang für alle Kampagnenanzeigen ungültig.

scoreAd()

function scoreAd(
  ad,
  bid,
  ad_selection_config,
  seller_signals,
  trusted_scoring_signals,
  contextual_signal,
  user_signal,
  custom_audience_signal) {
    return {'status': 0, 'score': score };
}

Eingabeparameter:

• ad: siehe generateBid-Dokumentation
• bid: Gebotswert für die Anzeige

• ad_selection_config: Ein JSON-Objekt, das den Parameter AdSelectionConfig der selectAds API darstellt. Das Format dafür ist:

  var ad_selection_config = {
    'seller': 'seller',
    'decision_logic_url': 'url_of_decision_logic',
    'custom_audience_buyers': ['buyer1', 'buyer2'],
    'auction_signals': auction_signals,
    'per_buyer_signals': per_buyer_signals,
    'contextual_ads': [ad1, ad2]
  }
  

• seller_signals: JSON-Objekte, die aus dem API-Parameter sellerSignals AdSelectionConfig gelesen werden

• trusted_scoring_signal: wird aus dem Feld adSelectionSignals im API-Parameter AdSelectionConfig gelesen

• contextual_signals, user_signals: JSON-Objekte. Sie werden als leere Objekte übergeben und in zukünftigen Releases ausgefüllt. Das Format wird nicht von der Plattform erzwungen und wird von der Anzeigentechnologie verwaltet.

• per_buyer_signals: JSON-Objekt, das aus der perBuyerSignal-Zuordnung im API-Parameter AdSelectionConfig gelesen wird. Dabei wird der aktuelle Käufer der benutzerdefinierten Zielgruppe als Schlüssel verwendet. Leeres String, wenn die Zuordnung keinen Eintrag für den angegebenen Käufer enthält.

Ausgabe:

• score: ein Gleitkommawert, der den Bewertungswert für diese Anzeige darstellt
• status: Ganzzahlwert, der einen der folgenden Werte haben kann:
  • 0: für eine erfolgreiche Ausführung
  • 1: Falls die customAudienceSignals ungültig sind
  • 2: Wenn AdSelectionConfig ungültig ist
  • 3: Wenn eines der anderen Signale ungültig ist
  • Jeder Wert ungleich Null führt zum Abbruch des Prozesses. Der Wert bestimmt die Art der geworfenen Ausnahme.

selectOutcome()

function selectOutcome(
  outcomes,
  selection_signals) {
    return {'status': 0, 'result': null};
}

Eingabeparameter:

• outcomes: ein JSON-Objekt {"id": id_string, "bid": bid_double}
• selection_signals: JSON-Objekte, die im Auktionskonfigurationsobjekt angegeben sind

Ausgabe:

• status: 0 für Erfolg, ein anderer Wert für Fehler
• result: eines der übergebenen Ergebnisse oder „null“

reportResult()

function reportResult(ad_selection_config, render_url, bid, contextual_signals) {
   return {
      'status': status,
      'results': {'signals_for_buyer': signals_for_buyer, 'reporting_url': reporting_url }
   };
}

Eingabeparameter:

• ad_selection_config: siehe Dokumentation von scoreAds
• render_url: die Render-URL der Gewinneranzeige
• bid: das Gebot für die Anzeige, die den Zuschlag erhalten hat
• contextual_signals: siehe Dokumentation von generateBid

Ausgabe:

• status: 0 für Erfolg und ein anderer Wert für Fehler
• results: Ein JSON-Objekt mit den folgenden Elementen:
  • signals_for_buyer: Ein JSON-Objekt, das an die reportWin-Funktion übergeben wird
  • reporting_url: Eine URL, über die die Plattform den Käufer über die Impression informiert

reportWin()

function reportWin(
   ad_selection_signals,
   per_buyer_signals,
   signals_for_buyer,
   contextual_signals,
   custom_audience_signals) {
   return {'status': 0, 'results': {'reporting_url': reporting_url } };
}

Eingabeparameter:

• ad_selection_signals, per_buyer_signals: siehe Dokumentation für scoreAd
• signals_for_buyer: Ein JSON-Objekt, das von reportResult zurückgegeben wird
• contextual_signals, custom_audience_signals: siehe Dokumentation für generateBid

Ausgabe:

• status: 0 für Erfolg und ein anderer Wert für Fehler
• results: Ein JSON-Objekt mit den folgenden Elementen:
  • reporting_url: Eine URL, über die die Plattform den Verkäufer über die Impression benachrichtigt.

registerAdBeacon()

function registerAdBeacon(
  beacons
)

Eingabeparameter:

• beacons: Ein Objekt mit Schlüssel/Wert-Paaren von Interaktionsschlüsseln und Berichts-URIs. Das Format dafür ist:

  let beacons = {
    'interaction_key': 'reporting_uri',
    'interaction_key': 'reporting_uri',
    ...
  }
  

  • interaction_key: Ein String, der das Ereignis darstellt. Dieser Wert wird später von der Plattform verwendet, um bei der Meldung von Ereignisinteraktionen die reporting_uri abzurufen, die benachrichtigt werden soll. Dieser Schlüssel muss mit den Angaben des Käufers oder Verkäufers übereinstimmen.
  • reporting_uri: Ein URI zum Empfangen von Ereignisberichten. Dieser sollte sich auf den gemeldeten Ereignistyp beziehen. Er muss eine POST-Anfrage akzeptieren, um alle Daten zu verarbeiten, die zusammen mit dem Ereignis erfasst werden.

  Beispiel:

    let beacons = {
      'click': 'https://reporting.example.com/click_event',
      'view': 'https://reporting.example.com/view_event'
    }
  

Vordefinierte URIs für die Anzeigenauswahl

Mit vordefinierten URIs können Anbieter von Anzeigentechnologien JavaScript-Funktionen für die Entscheidungslogik zur Anzeigenauswahl in den Klassen AdSelectionConfig und AdSelectionFromOutcomesConfig festlegen. Für vordefinierte URIs sind keine Netzwerkaufrufe zum Herunterladen des entsprechenden JavaScript erforderlich. Anbieter von Anzeigentechnologien können vordefinierte URIs verwenden, ohne eine registrierte Domain zum Hosten des JavaScripts einrichten zu müssen.

Ein vordefinierter URI hat folgendes Format:

ad-selection-prebuilt:<use-case>/<name>?<required-script-generation-parameters>

Die Privacy Sandbox-Plattform stellt JavaScript mit den Informationen aus diesem URI in der Laufzeit bereit.

Eine IllegalArgumentException wird ausgelöst, wenn:

• einer der erforderlichen Parameter im URI fehlt
• im URI unbekannte Parameter vorhanden sind

Unterstützte Anwendungsfälle und Namen für vordefinierte URIs

Anwendungsfall 1: Anzeigenauswahl

Vordefinierte URIs im Anwendungsfall ad-selection werden im Ablauf selectAds(AdSelectionConfig) unterstützt.

Name des vordefinierten URI: highest-bid-wins

Dieser vordefinierte URI enthält ein JavaScript, das nach dem Gebotsabgabevorgang die Anzeige mit dem höchsten Gebot auswählt. Außerdem gibt es eine grundlegende Meldefunktion, mit der die render_uri und bid des Gewinners gemeldet werden können.

Erforderliche Parameter

reportingUrl: Die Basis-URL für Berichte, die mit dem render_uri und dem bid der Gewinneranzeige parametrisiert ist:

<reportingUrl>?render_uri=<renderUriOfWinnigAd>&bid=<bidOfWinningAd>

Nutzung

Wenn Ihre Basis-URL für die Berichterstellung https://www.ssp.com/reporting ist, lautet die vordefinierte URI:

`ad-selection-prebuilt://ad-selection/highest-bid-wins/?reportingUrl=https://www.ssp.com/reporting`

Anwendungsfall 2: „Anzeigenauswahl aus Ergebnissen“

Vordefinierte URIs für den Anwendungsfall ad-selection-from-outcomes unterstützen den Workflow selectAds(AdSelectionFromOutcomesConfig).

Name des vordefinierten URI: waterfall-mediation-truncation

Der vordefinierte URI waterfall-mediation-truncation enthält JavaScript, das die Abschneidelogik der Vermittlungsabfolge implementiert. Dabei gibt das JavaScript eine Anzeigenanzeige von selbst erhobenen Daten zurück, wenn der bid mindestens dem bid floor entspricht. Andernfalls wird null zurückgegeben.

Erforderliche Parameter

bidFloor: Der Schlüssel des Mindestgebotswerts, der in getSelectionSignals() übergeben wird und mit der Anzeige des Mediation-SDKs verglichen wird.

Nutzung

Wenn deine Anzeigenauswahlsignale so aussehen: {"bid_floor": 10}, lautet der resultierende vordefinierte URI:

`ad-selection-prebuilt://ad-selection-from-outcomes/waterfall-mediation-truncation/?bidFloor=bid_floor`

Test

Für den Einstieg in die Protected Audience API haben wir Beispiel-Apps in Kotlin und Java erstellt, die Sie auf GitHub finden.

Vorbereitung

Für die Protected Audience API ist JavaScript bei der Anzeigenauswahl und bei Impressionsberichten erforderlich. Es gibt zwei Methoden, dieses JavaScript in einer Testumgebung bereitzustellen:

• Einen Server mit den erforderlichen HTTPS-Endpunkten ausführen, der das JavaScript zurückgibt
• Remote-Abruf überschreiben, indem Sie den erforderlichen Code aus einer lokalen Quelle angeben

Für beide Ansätze muss ein HTTPS-Endpunkt eingerichtet werden, um Impressionsberichte zu verarbeiten.

HTTPS-Endpunkte

Wenn Sie die Anzeigenauswahl und die Impressionsberichte testen möchten, müssen Sie sieben HTTPS-Endpunkte einrichten, auf die Ihr Testgerät oder ‑emulator zugreifen kann:

1. Käuferendpunkt, der die JavaScript-Gebotslogik bereitstellt.
2. Ein Endpunkt, über den die Gebotssignale ausgeliefert werden.
3. Verkäuferendpunkt, der die JavaScript-Daten der Entscheidungslogik bereitstellt.
4. Ein Endpunkt, der Bewertungssignale bereitstellt.
5. Endpunkt für Berichte zu Impressionen des Käufers, der die Auktion gewonnen hat.
6. Endpunkt für Berichte zu Verkäuferimpressionen.
7. Ein Endpunkt für die Auslieferung der täglichen Updates für eine benutzerdefinierte Zielgruppe.

Der Einfachheit halber enthält das GitHub-Repository grundlegenden JavaScript-Code zu Testzwecken. Außerdem enthält es OpenAPI-Dienstdefinitionen, die auf einer unterstützten Mock- oder Mikrodienstplattform bereitgestellt werden können. Weitere Informationen finden Sie in der README-Datei des Projekts.

Remote-Abruf von JavaScript überschreiben

Diese Funktion ist für End-to-End-Tests vorgesehen. Wenn Sie das Remote-Abrufen überschreiben möchten, muss Ihre App im Debug-Modus mit aktivierten Entwickleroptionen ausgeführt werden.

Wenn Sie den Debug-Modus für Ihre Anwendung aktivieren möchten, fügen Sie dem Attribut „application“ in AndroidManifest.xml die folgende Zeile hinzu:

<application
  android:debuggable="true">

Ein Beispiel für die Verwendung dieser Überschreibungen finden Sie in der Beispiel-App für die Protected Audience API auf GitHub.

Sie müssen eigenes benutzerdefiniertes JavaScript hinzufügen, um Abläufe für die Anzeigenauswahl wie Gebote, Bewertungsentscheidungen und Berichte zu verarbeiten. Im GitHub-Repository finden Sie Beispiele für einfachen JavaScript-Code, der alle erforderlichen Anfragen verarbeitet. In der Beispielanwendung der Protected Audience API wird gezeigt, wie Code aus dieser Datei gelesen und für die Verwendung als Überschreibung vorbereitet wird.

Sie können das Abrufen von JavaScript auf der Sell-Side und Buy-Side unabhängig voneinander überschreiben. Sie benötigen jedoch einen HTTPS-Endpunkt, um JavaScript zu senden, für das Sie keine Überschreibungen bereitstellen. In der README-Datei finden Sie Informationen zum Einrichten eines Servers, der diese Fälle verarbeitet.

Das Abrufen von JavaScript kann nur für benutzerdefinierte Zielgruppen überschrieben werden, deren Inhaber Ihr Paket ist.

Sell-side-JavaScript überschreiben

So richten Sie ein Überschreiben von JavaScript für die Sell-Side ein:

1. Initialisieren Sie ein AdSelectionManager-Objekt.
2. Rufe einen Verweis auf TestAdSelectionManager aus dem AdSelectionManager-Objekt ab.
3. Erstellen Sie ein AdSelectionConfig-Objekt.
4. Erstelle ein AddAdSelectionOverrideRequest mit dem AdSelectionConfig-Objekt und einem String, das das JavaScript darstellt, das du als Überschreibung verwenden möchtest.
5. Rufen Sie die asynchrone overrideAdSelectionConfigRemoteInfo()-Methode mit dem AddAdSelectionOverrideRequest-Objekt und den relevanten Executor- und OutcomeReceiver-Objekten auf.

val testAdSelectionManager: TestAdSelectionManager =
  context.getSystemService(AdSelectionManager::class.java).getTestAdSelectionManager()

// Initialize AdSelectionConfig =
val adSelectionConfig = new AdSelectionConfig.Builder()
    .setSeller(seller)
    .setDecisionLogicUrl(decisionLogicUrl)
    .setCustomAudienceBuyers(customAudienceBuyers)
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .build()

// Initialize AddAddSelectionOverrideRequest
val request = AddAdSelectionOverrideRequest.Builder()
    .setAdSelectionConfig(adSelectionConfig)
    .setDecisionLogicJs(decisionLogicJS)
    .build()

// Run the call to override the JavaScript for the given AdSelectionConfig
// Note that this only takes effect in apps marked as debuggable
testAdSelectionManager.overrideAdSelectionConfigRemoteInfo(
    request,
    executor,
    outComeReceiver)

TestAdSelectionManager testAdSelectionManager =
  context.getSystemService(AdSelectionManager.class).getTestAdSelectionManager();

// Initialize AdSelectionConfig =
AdSelectionConfig adSelectionConfig = new AdSelectionConfig.Builder()
    .setSeller(seller)
    .setDecisionLogicUrl(decisionLogicUrl)
    .setCustomAudienceBuyers(customAudienceBuyers)
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .build();

// Initialize AddAddSelectionOverrideRequest
AddAdSelectionOverrideRequest request = AddAdSelectionOverrideRequest.Builder()
    .setAdSelectionConfig(adSelectionConfig)
    .setDecisionLogicJs(decisionLogicJS)
    .build();

// Run the call to override the JavaScript for the given AdSelectionConfig
// Note that this only takes effect in apps marked as debuggable
testAdSelectionManager.overrideAdSelectionConfigRemoteInfo(
    request,
    executor,
    outComeReceiver);

Weitere Informationen zu den einzelnen Feldern in AdSelectionConfig finden Sie im Abschnitt Anzeigenauswahl ausführen. Der Hauptunterschied besteht darin, dass decisionLogicUrl auf einen Platzhalterwert gesetzt werden kann, da er ignoriert wird.

Damit das bei der Anzeigenauswahl verwendete JavaScript überschrieben werden kann, muss decisionLogicJs die richtigen Funktionssignaturen der Verkäuferseite enthalten. Ein Beispiel zum Lesen einer JavaScript-Datei als String finden Sie in der Beispiel-App für die Protected Audience API auf GitHub.

Bei der asynchronen overrideAdSelectionConfigRemoteInfo()-Methode wird das OutcomeReceiver-Objekt verwendet, um das Ergebnis des API-Aufrufs zu signalisieren.

Der onResult()-Callback gibt an, dass die Überschreibung erfolgreich angewendet wurde. Bei zukünftigen Aufrufen von selectAds() wird die Entscheidungs- und Berichtslogik verwendet, die Sie als Überschreibung übergeben haben.

Der onError()-Callback gibt zwei mögliche Bedingungen an:

• Wenn der Überschreibung mit ungültigen Argumenten versucht wird, gibt die AdServiceException einen IllegalArgumentException als Ursache an.
• Wenn der Überschreibungsversuch mit einer App erfolgt, die nicht im Debug-Modus mit aktivierten Entwickleroptionen ausgeführt wird, wird IllegalStateException als Ursache angezeigt.AdServiceException

Überschreibungen auf Verkäuferseite zurücksetzen

In diesem Abschnitt wird davon ausgegangen, dass Sie das JavaScript für die Sell-Side überschrieben haben und dass Sie einen Verweis auf TestAdSelectionManager und AdSelectionConfig haben, die im vorherigen Abschnitt verwendet wurden.

So setzen Sie die Überschreibungen für alle AdSelectionConfigs zurück:

1. Rufen Sie die asynchrone resetAllAdSelectionConfigRemoteOverrides()-Methode mit dem entsprechenden OutcomeReceiver-Objekt auf.

// Resets overrides for all AdSelectionConfigs
testAadSelectionManager.resetAllAdSelectionConfigRemoteOverrides(
  outComeReceiver)

// Resets overrides for all AdSelectionConfigs
testAdSelectionManager.resetAllAdSelectionConfigRemoteOverrides(
    outComeReceiver);

Nachdem Sie die Überschreibungen auf Verkäuferseite zurückgesetzt haben, wird für Aufrufe von selectAds() die decisionLogicUrl verwendet, die in AdSelectionConfig gespeichert ist, um das erforderliche JavaScript abzurufen.

Wenn der Aufruf von resetAllAdSelectionConfigRemoteOverrides() fehlschlägt, gibt der OutComeReceiver.onError()-Callback einen AdServiceException zurück. Wenn versucht wird, Überschreibungen in einer App zu entfernen, die nicht im Debug-Modus mit aktivierten Entwickleroptionen ausgeführt wird, wird in AdServiceException IllegalStateException als Ursache angegeben.

Buy-Side-JavaScript überschreiben

1. Anleitung zum Zusammenführen von Zielgruppen
2. Erstellen Sie eine AddCustomAudienceOverrideRequest mit dem Käufer und dem Namen der benutzerdefinierten Zielgruppe, die Sie überschreiben möchten, sowie der Gebotslogik und den Daten, die Sie als Überschreibung verwenden möchten.
3. Rufen Sie die asynchrone overrideCustomAudienceRemoteInfo()-Methode mit dem AddCustomAudienceOverrideRequest-Objekt und den relevanten Executor- und OutcomeReceiver-Objekten auf.

val testCustomAudienceManager: TestCustomAudienceManager =
  context.getSystemService(CustomAudienceManager::class.java).getTestCustomAudienceManager()

// Join custom audience

// Build the AddCustomAudienceOverrideRequest
val request = AddCustomAudienceOverrideRequest.Builder()
    .setBuyer(buyer)
    .setName(name)
    .setBiddingLogicJs(biddingLogicJS)
    .setTrustedBiddingSignals(trustedBiddingSignals)
    .build()

// Run the call to override JavaScript for the given custom audience
testCustomAudienceManager.overrideCustomAudienceRemoteInfo(
    request,
    executor,
    outComeReceiver)

TestCustomAudienceManager testCustomAudienceManager =
  context.getSystemService(CustomAudienceManager.class).getTestCustomAudienceManager();

// Join custom audience

// Build the AddCustomAudienceOverrideRequest
AddCustomAudienceOverrideRequest request =
    AddCustomAudienceOverrideRequest.Builder()
        .setBuyer(buyer)
        .setName(name)
        .setBiddingLogicJs(biddingLogicJS)
        .setTrustedBiddingSignals(trustedBiddingSignals)
        .build();

// Run the call to override JavaScript for the given custom audience
testCustomAudienceManager.overrideCustomAudienceRemoteInfo(
    request,
    executor,
    outComeReceiver);

Die Werte für buyer und name sind dieselben, die beim Erstellen der benutzerdefinierten Zielgruppe verwendet wurden. Weitere Informationen zu diesen Feldern

Außerdem können Sie zwei weitere Parameter angeben:

• biddingLogicJs: JavaScript, das die Logik des Käufers enthält, die bei der Anzeigenauswahl verwendet wird. Die erforderlichen Funktionssignaturen finden Sie in diesem JavaScript-Code.
• trustedBiddingSignals: Gebotssignale, die bei der Anzeigenauswahl verwendet werden sollen. Zu Testzwecken kann dies ein leerer String sein.

Bei der asynchronen overrideCustomAudienceRemoteInfo()-Methode wird das Objekt OutcomeReceiver verwendet, um das Ergebnis des API-Aufrufs zu signalisieren.

Der onResult()-Callback gibt an, dass die Überschreibung erfolgreich angewendet wurde. Bei nachfolgenden Aufrufen von selectAds() wird die Gebot- und Berichtslogik verwendet, die Sie als Überschreibung übergeben haben.

Der onError()-Callback steht für zwei mögliche Bedingungen.

• Wenn der Überschreibung mit ungültigen Argumenten versucht wird, gibt die AdServiceException einen IllegalArgumentException als Ursache an.
• Wenn der Überschreibungsversuch mit einer App erfolgt, die nicht im Debug-Modus mit aktivierten Entwickleroptionen ausgeführt wird, wird IllegalStateException als Ursache angezeigt.AdServiceException

Buy-Side-Überschreibungen zurücksetzen

In diesem Abschnitt wird davon ausgegangen, dass Sie das Buy-Side-JavaScript überschrieben haben und eine Referenz auf den im vorherigen Abschnitt verwendeten TestCustomAudienceManager haben.

So setzen Sie Überschreibungen für alle benutzerdefinierten Zielgruppen zurück:

1. Rufen Sie die asynchrone resetAllCustomAudienceOverrides()-Methode mit den relevanten Executor- und OutcomeReceiver-Objekten auf.

// Resets overrides for all custom audiences
testCustomAudienceManager.resetCustomAudienceRemoteInfoOverride(
    executor,
    outComeReceiver)

// Resets overrides for all custom audiences
testCustomAudienceManager.resetCustomAudienceRemoteInfoOverride(
    executor,
    outComeReceiver)

Nachdem Sie die Buy-Side-Überschreibungen zurückgesetzt haben, werden bei nachfolgenden Aufrufen von selectAds() die Werte für biddingLogicUrl und trustedBiddingData verwendet, die in CustomAudience gespeichert sind, um das erforderliche JavaScript abzurufen.

Wenn der Aufruf von resetCustomAudienceRemoteInfoOverride() fehlschlägt, gibt der OutComeReceiver.onError()-Callback einen AdServiceException zurück. Wenn versucht wird, Überschreibungen in einer App zu entfernen, die nicht im Debug-Modus mit aktivierten Entwickleroptionen ausgeführt wird, wird in AdServiceException IllegalStateException als Ursache angezeigt.

Berichtsserver einrichten

Wenn Sie Remote-Abruf-Überschreibungen verwenden, müssen Sie trotzdem einen Server einrichten, auf den Ihr Gerät oder Emulator zugreifen kann, um auf Berichtsereignisse zu reagieren. Ein Endpunkt, der 200 zurückgibt, ist für Tests ausreichend. Das GitHub-Repository enthält OpenAPI-Dienstdefinitionen, die auf einer unterstützten Mock- oder Mikroservice-Plattform bereitgestellt werden können. Weitere Informationen finden Sie in der README-Datei des Projekts.

Suchen Sie nach den OpenAPI-Definitionen unter „reporting-server.json“. Diese Datei enthält einen Endpunkt, der 200 zurückgibt, was einem HTTP-Antwortcode entspricht. Dieser Endpunkt wird während selectAds() verwendet und signalisiert der Protected Audience API, dass die Impressionsberichte erfolgreich abgeschlossen wurden.

Zu testende Funktion

• Sie können die Gruppen beitreten oder verlassen und eine benutzerdefinierte Zielgruppe basierend auf früheren Nutzeraktionen einrichten.
• Testen Sie die Auslösung der Anzeigenauswahl auf dem Gerät über remote gehostete JavaScripts.
• Sehen Sie sich an, wie sich die Verknüpfung einer App mit benutzerdefinierten Zielgruppeneinstellungen auf die Ergebnisse der Anzeigenauswahl auswirken kann.
• Impressionsberichte nach der Anzeigenauswahl erstellen

Beschränkungen

In der folgenden Tabelle sind Einschränkungen für die Verarbeitung durch die Protected Audience API aufgeführt. Die angegebenen Limits können sich auf Grundlage von Feedback ändern. Informationen zu in der Entwicklung befindlichen Funktionen finden Sie in den Versionshinweisen.

Fehler und Probleme melden

Ihr Feedback ist ein wichtiger Bestandteil der Privacy Sandbox für Android. Bitte teilen Sie uns Probleme oder Verbesserungsvorschläge für die Privacy Sandbox für Android mit.