Entwicklerleitfaden für die Protected Audience API

<ph type="x-smartling-placeholder"></ph> Entwicklervorschau Beta

Beim Lesen der Privacy Sandbox für Android Dokumentation auswählen, klicken Sie auf die Schaltfläche Vorschau für Entwickler oder Beta, um Programmversion, mit der Sie arbeiten, da die Anleitung variieren kann.

---

Feedback geben

Die Protected Audience API unter Android (früher FLEDGE) enthält die Custom Audience API und Ad Selection API AdTech-Plattformen und Werbetreibende können diese APIs verwenden, um interessenspezifische Anzeigen auf der Grundlage vorheriger App-Interaktionen auszuliefern, die schränkt die Freigabe von Kennungen für mehrere Apps ein und beschränkt die Freigabe der App eines Nutzers mit Dritten interagieren.

Die Custom Audience API befasst sich mit der „benutzerdefinierten Zielgruppe“ Abstraktion, die eine Gruppe von Nutzenden mit gemeinsamen Absichten repräsentiert. Eine Werbetreibende können Nutzer für eine benutzerdefinierte Zielgruppe registrieren und ihnen relevante Anzeigen zuordnen. damit nichts. Diese Informationen werden lokal gespeichert und können verwendet werden, um Werbetreibende Gebote, Anzeigenfilterung und Anzeigen-Rendering.

Die Ad Selection API bietet ein Framework, mit dem mehrere Entwickler für eine benutzerdefinierte Zielgruppe lokal eine Auktion durchführen. Um dies zu erreichen, berücksichtigt relevante Anzeigen, die mit der benutzerdefinierten Zielgruppe verknüpft sind, und erzielt eine zusätzliche Verarbeitung von Anzeigen, die von einer Anzeigentechnologie-Plattform an das Gerät zurückgegeben werden.

AdTech-Plattformen können diese APIs integrieren, um Remarketing zu implementieren, schützt die Privatsphäre der Nutzer. Unterstützung für weitere Anwendungsfälle, einschließlich App-Installation sind für zukünftige Versionen geplant. Weitere Informationen zu Protected Audience API für Android im Designvorschlag

In diesem Leitfaden erfahren Sie, wie Sie mit der Protected Audience API unter Android Gehen Sie so vor:

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

Hinweis

Bevor Sie beginnen, führen Sie die folgenden Schritte aus:

1. Richten Sie Ihre Entwicklungsumgebung für die Privacy Sandbox für Android ein.
2. Installieren Sie entweder ein System-Image auf einem unterstützten Gerät oder richten Sie ein Emulator, der die Privacy Sandbox für Android unterstützt.

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

     adb shell device_config put adservices ppapi_app_allow_list \"*\"
   

4. ACCESS_ADSERVICES_CUSTOM_AUDIENCE-Berechtigung in deine App einbinden Manifest:

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

5. Verweisen Sie im <application>-Element von Ihr Manifest:

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

6. Gib die XML-Ressource für die Anzeigendienste an, auf die in deinem Manifest verwiesen wird, z. B.: res/xml/ad_services_config.xml Weitere Informationen zu Berechtigungen für Werbedienste und die SDK-Zugriffssteuerung.

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

7. Standardmäßig erzwingt die Ad Selection API Beschränkungen auf die maximale Speichermenge, die bei einer Auktions- oder Impression-Berichterstellung das Skript zuweisen kann. Für die Funktion zur Arbeitsspeicherbeschränkung ist eine WebView-Version erforderlich 105.0.5195.58 oder höher. Die Plattform erzwingt eine Versionsprüfung und ruft Die APIs selectAds und reportImpression schlagen fehl, wenn dies nicht zufrieden ist. Dafür gibt es zwei Möglichkeiten:

   • Option 1: Deaktivieren Sie diese Prüfung mit dem folgenden adb-Befehl:

     adb device_config put fledge_js_isolate_enforce_max_heap_size false
     

   • Option 2: WebView Beta aus dem Google Play Store installieren Dies muss gleich oder höher als die zuvor angegebene Version ist.

Einer benutzerdefinierten Zielgruppe beitreten

Eine benutzerdefinierte Zielgruppe ist eine Gruppe von Nutzern mit gemeinsamen Absichten oder Interessen, die von der App des Werbetreibenden festgelegt wurden. Eine App oder ein SDK kann eine benutzerdefinierte Zielgruppe angeben, um eine bestimmte Zielgruppe anzugeben, z. B. eine Person, die Artikel verlassen hat. im Einkaufswagen. Führen Sie die folgenden Schritte aus, um eine benutzerdefinierte Zielgruppe asynchron zu erstellen oder hinzuzufügen: Folgendes:

1. Initialisieren Sie das Objekt CustomAudienceManager.
2. Erstellen Sie ein CustomAudience-Objekt, indem Sie Schlüsselparameter wie das Paket des Käufers und einen relevanten Namen. Initialisieren Sie dann die Objekt JoinCustomAudienceRequest durch CustomAudience -Objekt enthält.
3. Rufen Sie den asynchronen joinCustomAudience() mit der Methode Objekt JoinCustomAudienceRequest und relevante Executor und OutcomeReceiver-Objekte.

Kotlin

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)

Java

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);

Durch die Kombination der folgenden Parameter werden die einzelnen Parameter CustomAudience-Objekt auf einem Gerät:

• owner: Paketname der Eigentümer-App. Dies ist implizit auf den Wert Paketname der Anrufer-App.
• buyer: ID für das Werbenetzwerk des Käufers, über das Anzeigen für dieses benutzerdefinierte Targeting verwaltet werden Zielgruppe.
• name: Ein beliebiger Name oder eine beliebige Kennung für die benutzerdefinierte Zielgruppe.

Wiederholter Aufruf von joinCustomAudience() mit einer anderen Instanz von CustomAudience aktualisiert alle vorhandenen CustomAudience mit entspricht den Parametern owner, buyer und name. Zur Wahrung des Datenschutzes -Ergebnis der API nicht zwischen „Erstellung“ und „Aktualisieren“.

Außerdem muss die CustomAudience mit diesen erforderlichen Parameter:

• URL für tägliche Updates: Eine HTTPS-URL, die täglich im Hintergrund abgefragt wird. Gebotssignale von Nutzern, Daten zu vertrauenswürdigen Geboten einer benutzerdefinierten Zielgruppe aktualisieren Sie können URLs und Metadaten für Anzeigen rendern.
• Gebotslogik-URL: Eine HTTPS-URL, die während der Anzeigenauswahl abgefragt wird, um ein JavaScript-Gebotslogik des Käufers. Erforderliche Funktionssignaturen in diesem JavaScript.
• Anzeigen-Rendering-IDs: Eine beliebige ID, die von der Anzeigentechnologie des Käufers festgelegt wird. Dies ist ein Optimierung zum Generieren der Nutzlast für B&A.

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

• Aktivierungszeit: Eine benutzerdefinierte Zielgruppe kann nur an der Anzeigenauswahl teilnehmen. und tägliche Updates nach der Aktivierung. Dies kann nützlich sein, um inaktive Nutzer einer App.
• Ablaufzeit: Eine Zeit, nach der die benutzerdefinierte Zielgruppe in der Zukunft liegt. vom Gerät entfernt.
• Gebotssignale von Nutzern: Ein JSON-String mit Nutzersignalen wie dem dem bevorzugten Gebietsschema des Nutzers, das vom JavaScript für die Gebotslogik eines Käufers genutzt wird zum Generieren von Geboten bei der Anzeigenauswahl. Dieses Format hilft AdTech Plattformen können Code plattformübergreifend wiederverwenden und vereinfachen die Verwendung von JavaScript Funktionen.
• Daten zu vertrauenswürdigen Geboten: Eine HTTPS-URL und eine Liste von Strings, die während der Anzeigenauswahlprozess, bei dem Gebotssignale von einem vertrauenswürdigen Schlüssel/Wert-Paar abgerufen werden .
• Ads (Anzeigen): Eine Liste von AdData-Objekten, die den Anzeigen entsprechen, die an der Anzeigenauswahl mitwirken. Jedes AdData-Objekt besteht aus:
  • Rendering-URL: Eine HTTPS-URL, die zum Rendern der endgültigen Anzeige abgefragt wird.
  • Metadaten: Ein JSON-Objekt, das als String serialisiert ist und Informationen zum bei der Anzeigenauswahl von der Gebotslogik des Käufers übernommen werden.
  • Anzeigenfilter: Klasse, die alle erforderlichen Informationen für Apps enthält Anzeigenfilterung und Frequency Capping bei der Anzeigenauswahl installieren

Hinweis: Die Werte für „Signale für Gebote von Nutzern“, „Vertrauenswürdige Gebotsdaten“ und „Anzeigen“ -Attribute insgesamt nicht größer als 10 KB sein. Diese 3 Felder müssen ausgefüllt sein für eine benutzerdefinierte Zielgruppe bei der Anzeigenauswahl.

Hier ein Beispiel für eine Instanziierung des CustomAudience-Objekts:

Kotlin

// 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()

Java

// 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();

JoinCustomAudience()-Ergebnisse verarbeiten

Die asynchrone Methode joinCustomAudience() verwendet die Methode OutcomeReceiver. , um das Ergebnis des API-Aufrufs zu signalisieren.

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

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

Kotlin

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)
    }
};

Java

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 User die Geschäftskriterien für einen bestimmten benutzerdefinierten kann eine App oder ein SDK leaveCustomAudience() aufrufen, um die benutzerdefinierte vom Gerät aus. So entfernen Sie ein CustomAudience basierend auf seinem eindeutigen gehen Sie so vor:

1. Initialisieren Sie das Objekt CustomAudienceManager.
2. LeaveCustomAudienceRequest mit den buyer und name. Weitere Informationen zu diesen Eingabefeldern finden Sie unter Einer benutzerdefinierten Zielgruppe beitreten:
3. Rufen Sie die asynchrone leaveCustomAudience()-Methode mit dem Objekt LeaveCustomAudienceRequest und relevante Executor und OutcomeReceiver-Objekte.

Kotlin

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)

Java

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() werden auch die OutcomeReceiver-Signale das Ende eines API-Aufrufs. Aus Datenschutzgründen muss ein Fehlerergebnis zwischen internen Fehlern und ungültigen Argumenten unterscheiden können. Das onResult() Callback wird aufgerufen, wenn der API-Aufruf abgeschlossen ist, unabhängig davon, ob ein übereinstimmender benutzerdefinierte Zielgruppe wurde entfernt.

Anzeigenauswahl ausführen

Wenn Sie die Protected Audience API zur Anzeigenauswahl verwenden 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 Objekt AdSelectionConfig und relevante Executor und OutcomeReceiver-Objekte.

Kotlin

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
)

Java

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);

Die Methode selectAds() erfordert eine AdSelectionConfig-Eingabe, wobei müssen Sie die folgenden erforderlichen Parameter angeben:

• Verkäufer: ID des Verkäufer-Werbenetzwerks, mit dem die Anzeigenauswahl initiiert wird.
• URL der Entscheidungslogik: Eine HTTPS-URL, die abgefragt wird, um die ID des Werbenetzwerks des Verkäufers zu erhalten. JavaScript-Logik.
  • HTTPS-URL: Wird abgefragt, um die JavaScript-Logik des Verkäufer-Werbenetzwerks zu erhalten. Erforderliche Funktionssignaturen
  • Vordefinierter URI: Dieser URI entspricht dem FLEDGE-Anzeigenauswahlformat. IllegalArgumentException wird ausgelöst, wenn ein nicht unterstütztes oder fehlerhaftes Format vorliegt. wird der vorkonfigurierte URI übergeben.
• Käufer von benutzerdefinierten Zielgruppen: vollständige Liste der Kennungen für Werbenetzwerke des Käufers die der Verkäufer zur Teilnahme an der Anzeigenauswahl berechtigt. Diese Käufer-IDs entsprechen CustomAudience.getBuyer() der teilnehmenden benutzerdefinierten Zielgruppen.

Die folgenden Parameter können optional für eine benutzerdefinierte Anzeige angegeben werden. Auswahl:

• Signale für die Anzeigenauswahl: Ein JSON-Objekt, serialisiert als String, das Signale, die von der Gebotslogik des Käufers konsumiert werden, die vom JavaScript abgerufen wird CustomAudience.getBiddingLogicUrl()
• Verkäufersignale: Ein JSON-Objekt, das als String serialisiert ist und Signale enthält. der vom Verkäufer abgerufenen JavaScript-Entscheidungslogik AdSelectionConfig.getDecisionLogicUrl()
• Signale pro Käufer: Eine Zuordnung von JSON-Objekten, serialisiert als Strings mit Signalen, die von bestimmten Käufern JavaScript für die Gebotslogik abgerufen aus CustomAudience.getBiddingLogicUrl(), die durch in die Käuferfelder der teilnehmenden benutzerdefinierten Zielgruppen ein.
• Kontextbezogene Anzeigen:Eine Sammlung von Anzeigenkandidaten, die direkt erfasst werden von Käufern während einer Auktion, die außerhalb einer geschützten Zielgruppe stattfindet Auktion.

Nachdem eine Anzeige ausgewählt wurde, bleiben die Ergebnisse, Gebote und Signale intern erhalten. für die Berichterstellung. Der OutcomeReceiver.onResult()-Callback gibt ein AdSelectionOutcome mit:

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

Wenn die Anzeigenauswahl aus folgenden Gründen nicht abgeschlossen werden kann: ungültige Argumente, Zeitüberschreitungen oder einen übermäßigen Ressourcenverbrauch, Der OutcomeReceiver.onError()-Callback liefert ein AdServicesException-Element mit den folgenden Verhaltensweisen:

• Wenn die Anzeigenauswahl mit ungültigen Argumenten initiiert wird, AdServicesException zeigt ein IllegalArgumentException als Ursache.
• Bei allen anderen Fehlern wird ein AdServicesException mit einem IllegalStateException als Ursache.

Kontextbezogene Anzeigen

Protected Audience kann kontextbezogene Anzeigen in eine Protected Auktion einbinden. Auf dem AdTech-Server müssen kontextbezogene Anzeigen ausgewählt und an den außerhalb der Protected Audience APIs. Kontextbezogene Anzeigen können dann in der Auktion mit dem AdSelectionConfig an. An diesem Punkt Wie bei Anzeigen auf dem Gerät, einschließlich Eignung für die ausschließende Anzeigenfilterung. Sobald die Die Protected Audience-Auktion ist abgeschlossen. Sie müssen Folgendes aufrufen: reportImpression() Dadurch wird reportWin() in der erfolgreichen kontextbezogenen Anzeige aufgerufen. dieselben Muster wie bei den Impressionsberichten, . Jede kontextbezogene Anzeige benötigt einen Käufer, ein Gebot, einen Link zur Berichterstellungslogik, Rendering-URL und Anzeigenmetadaten.

Zum Bereitstellen kontextbezogener Anzeigen in der App muss die Ziel-App ein Objekt ContextualAds:

Kotlin

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

Java

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:

Kotlin

// 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)

Java

// 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 lassen sich Installationsanzeigen für Apps filtern. die bereits auf einem Gerät installiert sind.

Zunächst legen wir fest, welche Werbetreibenden um nach dem installierten Paket zu filtern. Dies muss in der App geschehen, für das Targeting mit einer Anzeige.

Kotlin

//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)
    }
  })

Java

//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 vorherige Code ausgeführt wird, können die übergebenen Werbetreibenden folgende Aktionen ausführen: Herausfiltern der installierten Apps, die Sie bei der Gebotserstellung angeben. Wenn Sie müssen einen Werbetreibenden entfernen, damit dieser nicht mehr auf die Installation dieser App zugreifen kann führen Sie diesen Code noch einmal aus und entfernen Sie dabei die Werbetreibendeninformationen.

Im nächsten Schritt richten Sie die Anzeigenfilterung in der Publisher-App ein. Die Partei, die Die Anzeige wird innerhalb der Publisher-App ausgeliefert (wahrscheinlich ein Supply-Side-SDK). muss das AdFilters-Objekt mit Informationen zu den Anzeigen initialisieren die sie herausfiltern möchten:

Kotlin

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

Java

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

Demand-Side-Publisher können auch eine AdFilter für Anzeigen festlegen, die in ihre benutzerdefinierten Zielgruppen.

AdFilters kann auch beim Instanziieren einer neuen AdData übergeben werden. -Objekt enthält:

Kotlin

// 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()

Java

// 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();

Filtern nach Frequency Capping

Mit Frequency Capping können Anzeigentechnologie-Anbieter begrenzen, wie oft eine Anzeige angezeigt. Durch Frequency Capping wird die übermäßige Auslieferung von Anzeigen reduziert und alternative Anzeigen werden optimiert. Anzeigenauswahl für eine bestimmte Werbekampagne

Es gibt zwei Hauptkomponenten eines Frequency Capping-Filters: Anzeigenereignistyp und den Anzeigenzähler-Schlüssel. Folgende Anzeigenereignistypen können verwendet werden:

• Gewinnen (demnächst verfügbar): Wenn die Anzeige eine Auktion gewonnen hat, bedeutet das, dass sie gewonnen haben. Gewinnereignisse werden automatisch von der Protected Audience API aktualisiert und können nicht direkt vom Entwickler aufgerufen werden. Gewinndaten sind nur für Anzeigen in einem benutzerdefinierten Zielgruppe.
• Impression: getrennt von reportImpression; ein On-Device-Anrufer (SSP oder MMP) verwendet updateAdCounterHistogram(), um Impressionsereignisse im einen Punkt im Code eingeben. Impressionsereignisse sind für alle Anzeigen sichtbar, für eine bestimmte DSP und sind nicht auf Anzeigen in derselben benutzerdefinierten Zielgruppe beschränkt.
• Ansicht: Das Ereignis wird vom On-Device-Aufrufer (SSP oder MMP) an einem mit einem Anruf bei updateAdCounterHistogram(). Aufrufereignisse sind die für alle Anzeigen einer DSP sichtbar sind und nicht auf Anzeigen im selben Benutzerdefinierte Zielgruppe.
• Klick: Das Ereignis wird vom Aufrufer auf dem Gerät (SSP oder MMP) an einem mit einem Anruf bei updateAdCounterHistogram(). Klickereignisse für alle Anzeigen einer bestimmten DSP sichtbar sind und nicht auf Anzeigen in der für dieselbe benutzerdefinierte Zielgruppe.

In der Publisher-App ruft eine SSP oder MMP mit einer Präsenz auf dem Gerät die Anzeige auf. Ereignisse. Wenn updateAdCounterHistogram() aufgerufen wird, ist der Zähler einer Frequenz Der Cap-Filter wird erhöht, sodass zukünftige Auktionen immer auf dem neuesten Stand sind. Informationen darüber, wie ein Nutzer eine bestimmte Anzeige gesehen hat. Die Anzeigenereignistypen sind nicht die mit der entsprechenden Nutzeraktion verbunden sind, und stellen Richtlinien dar, zur Strukturierung ihres Ereignissystems. Um Anzeigenzähler zum Zeitpunkt der ein Ereignis handelt, gibt der Akteur auf dem Gerät die Anzeigenauswahl-ID an, die die Auktion gewinnt.

Anzeigenzählerschlüssel sind beliebige vorzeichenbehaftete 32-Bit-Ganzzahlen, die einer Käuferanzeige zugewiesen werden und einem bestimmten, von der DSP definierten Anzeigensatz entsprechen. Seit Anzeige Zählerschlüssel auf Anzeigen beschränkt sind, die zu einer bestimmten DSP gehören. ohne Überschneidungen mit Histogrammen einer anderen Anzeigentechnologie auszuwählen. Anzeigenzähler Schlüssel werden verwendet, um die DSP-spezifischen Kennungen für die Anzeigen einer DSP eine bestimmte benutzerdefinierte Zielgruppe erstellen, um Anzeigen aus zukünftigen Auktionen herauszufiltern.

Mithilfe von Zählern können Anzeigen priorisiert werden, bei denen die Wahrscheinlichkeit, für einen bestimmten Nutzer interessant sein könnten, basierend auf dessen Interaktionen mit anderen Anzeigen eines der Anzeigentechnologie eines Käufers. Beispiel: Eine Anzeige, die ein hohes Maß an das Engagement aus erfolgreichen Anzeigenauktionen, Aufrufen und Klicks Datenpunkt verwendet. Eine Anzeige für Linkshänder-Golfschläger könnte darauf hindeuten, dass der Nutzer kein Interesse an Rechtshändern hat. A Der Frequency Capping-Filter für eine Zählertaste, die linksseitigen Anzeigen zugewiesen ist, und filtert Anzeigen für Rechtshänder heraus.

Damit Sie Frequency Capping in Ihrer Auktion verwenden können, müssen Sie zuerst KeyedFrequencyCap-Objekte:

Kotlin

// 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()

Java

// 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.

Kotlin

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

Java

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

Wenn das AdFilters-Objekt mit Frequency Capping-Filtern gefüllt ist, kann es wird übergeben, wenn die benutzerdefinierte Zielgruppe erstellt wird:

Kotlin

// 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()

Java

// 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 Frequency Capping-Filter in einer benutzerdefinierten Zielgruppe implementiert sind, kann die SSP und dann die erforderlichen Klick-, Aufruf- oder Impression-Ereignisse auslösen.

Kotlin

val callerAdTech: AdTechIdentifier = mAdSelectionConfig.getSeller()

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

Java

AdTechIdentifier callerAdTech = mAdSelectionConfig.getSeller();

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

Anzeigen, die die festgelegten Grenzwerte für Frequency Capping-Filter erreicht haben, werden herausgefiltert. der Auktion. Das Filtern erfolgt vor der Gebotslogik für On-Device-Auktionen und wenn die Nutzlast für die Gebots- und Auktion Serviceauktionen.Mit diesem Toolkit können Anzeigentechnologie-Anbieter Interaktionen zwischen Nutzern und den Anzeigen in ihren benutzerdefinierten Zielgruppen, um die Anzeigen und gleichzeitig die Auslieferung von Anzeigen möglichst gering halten.

Kontextbezogene Anzeigenfilterung ohne Netzwerkaufrufe

Falls auf dem Gerät keine Remarketing-Nachfrage besteht, können Sie eine Anzeigenauswahl für kontextbezogene Anzeigen ohne Netzwerkaufrufe. Mit vordefinierten URIs und einer Liste von kontextbezogene Anzeigen mit Geboten, muss die Plattform das Abrufen der Gebotslogik überspringen, Gebots- und Bewertungssignale. Die Plattform nutzt einen vordefinierten URI zur Auswahl Kontextanzeige mit dem höchsten Gebot

Zur Verbesserung der Latenz können Anzeigentechnologie-Anbieter eine Anzeigenauswahl ausführen, die nur kontextbezogene Anzeigen mit Anzeigenfilterfunktion ohne Netzwerkaufrufe. Dies ist mit vordefinierten URIs für Bewertungssignale erreicht. Im Artikel Unterstützte Abschnitt „Vordefinierte URIs mit Anwendungsfällen und Namen“ für eine Liste von scoreAds Implementierungen.

So führen Sie die Anzeigenauswahl ohne Netzwerkaufrufe aus:

1. Anzeigenfilterung einrichten
2. Kontextbezogene Anzeigen erstellen

3. Erstellen Sie ein AdSelectionConfig-Objekt mit Folgendem:

   1. Eine leere Käuferliste
   2. Einen vordefinierten URI zur Auswahl des höchsten Gebots
   3. Kontextbezogene Anzeigen
   4. Ein leerer URI für die Bewertungssignale. Mit dem leeren URI kann angegeben werden, dass Sie vertrauenswürdige Signale nicht für die Bewertung abrufen 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 die Berichterstellung mit vordefinierten URIs ausführen

Heutzutage verfügt die Privacy Sandbox-Plattform nur über ein einfaches JavaScript -Implementierung für vordefinierte URIs verfügbar. Wenn Sie Ihre eigenen Berichterstellung von JavaScript und Verwendung vordefinierter URIs für eine Anzeige mit niedriger Latenz können Sie den DecisionLogicUri zwischen Anzeigenauswahl und Berichterstellung.

1. Schritte zur Anzeigenauswahl für kontextbezogene Anzeigen mithilfe vordefinierter URIs ausführen

2. Erstellen Sie eine Kopie von AdSelectionConfig, bevor Sie Berichte erstellen

   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);
   

Abfolgebasierte Vermittlung ausführen

Bei der abfolgebasierten Vermittlung müssen mehrere Drittanbieter-SDKs (Drittanbieter-Werbenetzwerke) die von einem SDK-Vermittlungsnetzwerk mit Erstanbieter-SDK orchestriert werden. Die abfolgebasierte Vermittlung ist unabhängig davon, ob die Auktion auf dem Gerät oder am Gebote und Auktionsdienste.

Drittanbieternetzwerke

Drittanbieter-Netzwerke müssen einen Adapter bereitstellen, mit dem das Vermittlungsnetzwerk Rufen Sie die erforderlichen Methoden zum Ausführen einer Auktion auf:

• Anzeigenauswahl ausführen
• Berichte zu Impressionen erstellen

Hier ein Beispiel für einen Vermittlungsadapter für das Werbenetzwerk:

Kotlin

class NetworkAdaptor {
    private val adSelectionManager : AdSelectionManager

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

    fun selectAds() {...}

    fun reportImpressions() {...}
}

Java

class NetworkAdaptor {
    AdSelectionManager adSelectionManager;

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

    public void selectAds() {...}

    public void reportImpressions() {...}
}

Für jedes SDK sind eigene Manager und Kunden für die Anzeigenauswahl sowie eigene Implementierung von selectAds und reportImpressions. SDK-Anbieter finden die Abschnitte zur Anzeigenauswahl für On-Device-Auktionen oder das B&A Erklärvideos für B&A-Auktionen. So melden Sie eine Anzeige Impressionen (nach den Berichten zu Impressionen einzelner SSPs für Berichterstellung.

Vermittlungsnetzwerk

Ähnlich wie bei Drittanbieternetzwerken benötigen Vermittlungsnetzwerke selectAds und reportImpression Implementierungen. In den Abschnitten zum Schalten von Anzeigen und wie Sie Berichte zu Anzeigenimpressionen erstellen, um weitere Informationen zu erhalten.

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

Vermittlungskette und Gebotsuntergrenze abrufen

Das Vermittlungsnetzwerk ist für das Abrufen der eigenen Daten zuständig. kontextbezogene Anzeigen, Vermittlungskette und Drittanbieter-Werbenetzwerke (Drittanbieter). Dieses kann bei einer Anfrage zum Abrufen kontextbezogener Anzeigen, die von der Vermittlung ausgeführt werden, Netzwerk. Die Vermittlungskette bestimmt, wie die Drittanbieternetzwerke iteriert werden. Die Mindestpreise können als adSelectionSignals an den Auktionsprozess übergeben werden.

Werbenetzwerk-Placement in der Vermittlungskette

Ein Vermittlungs-SDK kann sich basierend auf seinem Live-eCPM in die Vermittlungskette einfügen. der Gebote für eigene Anzeigen. In der Protected Audience API sind Anzeigengebote intransparent. Schlichtung Das SDK sollte AdSelectionFromOutcomesConfig verwenden, um ein bestimmtes selbst erhobenes Element vergleichen zu können Gebot der Anzeige auf den Mindestpreis des nächsten Drittanbieter-Werbenetzwerks in der Kette. Wenn das eigene Gebot höher als der Mindestpreis ist, bedeutet dies, dass das SDK dieses Drittanbieter-Netzwerks.

Anzeigenauswahl ausführen

Zum Abrufen einer selbst erhobenen Anzeigenkandidaten kann das Vermittlungsnetzwerk eine On-Device- den Schritten im Bereich Anzeigenauswahl folgen. Dadurch werden eine Anzeige mit selbst erhobenen Daten, ein Gebot und ein AdSelectionId, das bei der Vermittlung verwendet wird .

AdSelectionFromResultsConfig erstellen

Mithilfe von AdSelectionFromOutcomesConfig kann das Vermittlungsnetzwerk eine Liste übergeben von AdSelectionIds (Ergebnisse aus früheren Auktionen), Signalen zur Anzeigenauswahl und URI zum Abrufen von JavaScript, das eine Anzeige aus mehreren Kandidaten auswählt. Die Liste AdSelectionIds zusammen mit ihren Geboten und Signalen an die JavaScript, das eine der AdSelectionIds zurückgeben kann, wenn es das Gebot übertrifft Mindestpreis oder „Keine“, falls die Vermittlungskette fortgesetzt werden soll.

Vermittlungsnetzwerke erstellen ein AdSelectionFromOutcomesConfig mithilfe selbst erhobener Daten AdSelectionId aus dem vorherigen Abschnitt und die Gebotsuntergrenze für das Drittanbieter-Werbenetzwerk berücksichtigt werden. Es sollte eine neue AdSelectionFromOutcomesConfig erstellt werden für jeden Schritt in der Vermittlungskette.

Kotlin

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

Java

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 Methodenüberschreibung selectAds() für die abfolgebasierte Vermittlung ist ein AdSelectionFromOutcomesConfig-Eingabe, wobei Sie Folgendes angeben müssen Erforderliche Parameter:

• Verkäufer: ID des Verkäufer-Werbenetzwerks, mit dem die Anzeigenauswahl initiiert wird.
• AdSelectionIds: Eine Singleton-Liste eines früheren selectAds()-Tests mit selbst erhobenen Daten Anzeige.
• Signale für die Anzeigenauswahl: Ein JSON-Objekt, serialisiert als String, das Signale für die Gebotslogik des Käufers. Geben Sie in diesem Fall den Mindestpreis an, für das jeweilige Drittanbieternetzwerk abgerufen.
• Auswahllogik-URI: Eine HTTPS-URL, die während der Anzeigenauswahl zum Abrufen des JavaScript des Vermittlungsnetzwerks zur Auswahl einer erfolgreichen Anzeige verwendet wird. Weitere Informationen finden Sie in den Funktionssignaturen in diesem JavaScript verwenden. Der JavaScript-Code sollte die Drittanbieteranzeige, wenn das Gebot über dem Mindestpreis liegt. Andernfalls wird null zurückgegeben. So kann das Mediation SDK die Vermittlungskette kürzen, wenn ein Gewinner gefunden.

Rufen Sie mit dem erstellten AdSelectionOutcomesConfig die Methode selectAds() von das erste Drittanbieternetzwerk.

Kotlin

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)

Java

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);

Abfolgebasierte Vermittlung orchestrieren

Für die Durchführung der Vermittlung werden die folgenden Vorgänge in der folgenden Reihenfolge ausgeführt: .

1. Anzeigenauswahl für selbst erhobene Daten ausführen
2. Durchlaufen Sie die Vermittlungskette. Gehen Sie für jedes Drittanbieternetzwerk so vor: <ph type="x-smartling-placeholder">
   </ph>
   1. Build-AdSelectionFromOutcomeConfig einschließlich der selbst erhobenen outcomeId und der Gebotsuntergrenze des Drittanbieter-SDKs.
   2. Rufen Sie selectAds() mit der Konfiguration aus dem vorherigen Schritt auf.
   3. Wenn das Ergebnis nicht leer ist, wird die Anzeige zurückgegeben.
   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 eigene Anzeige zurück.

Kotlin

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

Java

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) { ... }
}

Berichte zu Anzeigenimpressionen erstellen

Es gibt zwei Möglichkeiten, um eine Anzeigenimpression zu erfassen, je nachdem, wie die Auktion ausgeführt wird. Wenn Sie eine einzelne SSP haben, die eine Auktion durchführt, folgen Sie der Anleitung in diesem Abschnitt. Wenn die abfolgebasierte Vermittlung implementieren möchten, folgen Sie der Anleitung in der Bericht zu Impressionen in der Wasserfall-Vermittlung.

Berichte zu Impressionen für eine einzelne SSP

Nachdem eine erfolgreiche Anzeige im Anzeigenauswahl-Workflow ausgewählt wurde, können Sie Die Impression wird den teilnehmenden Buy-Side- und Sell-Side-Plattformen gemeldet. mit der Methode AdSelectionManager.reportImpression(). Um eine Anzeige zu melden Impression:

1. Initialisieren Sie ein AdSelectionManager-Objekt.
2. Erstellen Sie ein ReportImpressionRequest-Objekt mit der ID für die Anzeigenauswahl.
3. Rufen Sie die asynchrone reportImpression()-Methode mit dem Objekt ReportImpressionRequest und relevante Executor und OutcomeReceiver-Objekte.

Java

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);

Kotlin

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 Parameter:

• Anzeigenauswahl-ID: Eine ID, die nur für einen Gerätenutzer eindeutig ist und zur Identifizierung eines Anzeigenauswahl erfolgreich war.
• Konfiguration der Anzeigenauswahl: Dieselbe Konfiguration, die in selectAds() verwendet wird. -Aufruf, der durch die angegebene Anzeigenauswahl-ID identifiziert wird.

Die asynchrone Methode reportImpression() verwendet die Methode OutcomeReceiver. , um das Ergebnis des API-Aufrufs zu signalisieren.

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

Berichte zu Impressionen bei der abfolgebasierten Vermittlung

Ein Vermittlungs-SDK muss das erfolgreiche SDK verfolgen, um seine Abläufe für die Berichterstellung. Die SDKs in einer Vermittlungskette sollten -Methode, die der Vermittler aufrufen soll, um einen eigenen Berichtsablauf auszulösen. Ein SDK an einer vermittelten Auktion teilnehmen, können Sie wie oben beschrieben vorgehen, ihre eigenen Berichte erstellen.

SSPs können dieses 3P SDK-Codebeispiel als Prototyp für die Teilnahme an Vermittlungsabläufe:

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

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

Endpunkte für Berichte zu Impressionen

Die Report Impression API gibt HTTPS-GET-Anfragen an Endpunkte aus, die von der Sell-Side-Plattform und der erfolgreichen Buy-Side-Plattform:

Endpunkt der Buy-Side-Plattform:

• In der API wird die in der benutzerdefinierten Zielgruppe angegebene Gebotslogik-URL verwendet, um den vom Käufer bereitgestellten JavaScript-Code abrufen, der die Logik für die Rückgabe eines URL für Impressionsberichte.
• Die JavaScript-Funktion reportWin() aufrufen, die voraussichtlich Folgendes zurückgeben wird: URL für die Berichterstellung zu Impressionen des Käufers.

Endpunkt der Sell-Side-Plattform:

• Verwenden Sie die URL der Entscheidungslogik, die in AdSelectionConfig angegeben ist. , um das JavaScript für die Entscheidungslogik des Verkäufers abzurufen.
• Die JavaScript-Funktion reportResult() aufrufen, die den Fehlercode zurückgeben soll der Impressions-Berichts-URL des Verkäufers.

Gebote und Berichte zu Auktionsdiensten

Eine mit Bidding und Auktionsdienste verfügen dann über alle Berichtsinformationen, einschließlich generierter URLs für Berichte zu Anzeigeninteraktionen die in der verschlüsselten Antwort der serverseitigen Auktion enthalten sind. Wenn der Parameter entschlüsselt wird, sind die entsprechenden URLs auf der Plattform registriert, für Anzeigen- und Impressionsberichte dieselben Schritte wie oben beschrieben.

Best-Effort-Berichte zu Impressionen

Die Methode reportImpression() wurde entwickelt, um Berichterstellung.

Hinweis:

• Wenn die API die URLs für die Impressionsberichte nicht anhand der JavaScript-Funktionen verwenden, wird ein Fehler zurückgegeben.
• Wenn der Aufruf der URLs fehlschlägt, zu Fehlern führen. Die Wiederholungslogik für temporäre Fehler lautet für zukünftige Releases geplant.
• Mehrere Aufrufe von reportImpression() mit demselben Parameter können dazu führen, dass die Ergebnisse Ihrer Anzeigenauswahl Mal.

Anzeigeninteraktionen melden

Mit Protected Audience können Sie Berichte zu detaillierteren Interaktionen für eine gerenderte Anzeige. Dazu gehören Interaktionen wie Aufrufzeit, Klicks, Mouseovers, oder andere nützliche Messwerte, die erfasst werden können. So erhalten Sie diese Berichte erfordern zwei Schritte. Erstens müssen sich Käufer und Verkäufer registrieren, diese Berichte im Berichterstellungs-JavaScript. Dann muss der Kunde melden Sie diese Ereignisse.

Für den Empfang von Interaktionsereignissen registrieren

Die Registrierung für Interaktionsereignisse erfolgt in den reportWin()- und JavaScript-Funktionen von reportResult() mithilfe einer JavaScript-Funktion bereitgestellt von der Plattform: registerAdBeacon. So registrieren Sie sich für einen Ereignisbericht können Sie einfach in der Berichterstellung die JavaScript-Funktion der Plattform aufrufen. JavaScript Im folgenden Snippet wird die reportWin() eines Käufers verwendet, aber dieselbe Ansatz für reportResult().

reportWin(
  adSelectionSignals,
  perBuyerSignals,
  signalsForBuyer,
  contextualSignals,
  customAudienceSignals) {
    ...
    // Calculate reportingUri, clickUri, viewUri, and hoverUri
    registerAdBeacon("click", clickUri)
    registerAdBeacon("view", viewUri)
    registerAdBeacon("hover", hoverUri)

    return reportingUrl;
}

Hinweis :Die Strings des Interaktionsschlüssels müssen mit den Angaben des Verkäufers übereinstimmen. Berichte empfangen können.

Interaktionsereignisse in Berichten erfassen

Nachdem die Kunden eine Impression gemeldet haben, können die Interaktionen an zuvor registrierten und erfolgreichen Buy-Side- und Sell-Side-Plattformen AdSelectionManager.reportInteraction()-Methode. So melden Sie ein Anzeigenereignis:

1. Initialisieren Sie ein AdSelectionManager-Objekt.
2. Erstellen Sie ein ReportInteractionRequest-Objekt mit der ID für die Anzeigenauswahl. Interaktionsschlüssel, Interaktionsdaten und das Ziel der Berichterstellung.
3. Rufen Sie die asynchrone reportInteraction()-Methode mit dem request-Objekt auf. sowie relevante Executor- und OutcomeReceiver-Objekte.

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 Parameter:

• Anzeigenauswahl-ID: Eine Anzeigenauswahl-ID, die von einer zuvor zurückgegebenen AdSelectionOutcome
• Interaktionsschlüssel: ein vom Client definierter Stringschlüssel, der die Aktion beschreibt. gemeldet wird. Dieser muss mit dem Schlüssel übereinstimmen, der vom Verkäufer registriert wurde, oder in den JavaScript-Funktionen für die Berichterstellung.
• Interaktionsdaten: Ein String mit Daten, die in das Ereignis einbezogen werden sollen. -Bericht, der zurück an die Reporting-Server gesendet wird.
• Berichtsziele: Eine Bitmaske, die angibt, ob die Ereignisse an den Käufer und/oder den Verkäufer gemeldet. Diese Flags werden vom Plattform und die endgültige Zielmaske können mit Geschäftsabläufe. Um einen Bericht für ein Ziel zu erstellen, können Sie das Flag des direkt über die Plattform. Wenn Sie Berichte für mehrere Ziele erstellen möchten, verwenden Sie die bitweise und ODER (|), um Flag-Werte zu kombinieren.

Die asynchrone Methode reportInteraction() verwendet die Methode OutcomeReceiver. , um das Ergebnis des API-Aufrufs zu signalisieren.

• Der onResult()-Callback gibt an, dass der Berichtsinteraktionsaufruf gültig ist.
• Der onError()-Callback zeigt die folgenden möglichen Bedingungen an:
  • Wird der Anruf getätigt, während die App im Hintergrund ausgeführt wird, IllegalStateException mit einer Fehlerbeschreibung wird zurückgegeben.
  • Wenn der Client beim Aufrufen von reportInteraction() gedrosselt wird, gibt ein LimitExceededException wird zurückgegeben.
  • Wenn das Paket nicht für den Aufruf der Privacy Preserving APIs registriert ist, wird ein SecurityException() wird zurückgegeben.
  • Wenn sich die Interaktionen der App-Berichte von der App unterscheiden, die aufgerufen wurde selectAds() wird eine IllegalStateException zurückgegeben.
• Wenn der Nutzer der Aktivierung der Privacy Sandbox APIs nicht zugestimmt hat, wird der Aufruf im Hintergrund fehlschlägt.

Hinweis :Wenn keine Fehler angezeigt werden, bedeutet das nicht, dass eine Meldung stattgefunden hat. Stattdessen ist dies garantiert, dass Protected Audience irgendwoher.

Endpunkte für Berichte zu Interaktionen

Die Report Interaction API gibt HTTPS POST-Anfragen an Endpunkte aus, die von der Sell-Side-Plattform und der Käufer-Plattform. Protected Audience API Die Interaktionsschlüssel stimmen mit den URIs überein, die im JavaScript-Berichtssystem deklariert wurden. und senden für jede gemeldete Interaktion eine POST-Anfrage an jeden Endpunkt. Der Inhaltstyp der Anfrage ist Nur-Text, wobei der Textkörper der Interaktionsdaten.

Best-Effort-Interaktionsberichte

Die reportInteraction() ist so konzipiert, dass Sie die folgenden Aufgaben bestmöglich nutzen können: HTTP POST-Berichte erstellen.

Tägliches Hintergrundupdate

Beim Erstellen einer benutzerdefinierten Zielgruppe kann Ihre App oder Ihr SDK eine benutzerdefinierte Zielgruppe initialisieren Metadaten. Außerdem kann die Plattform die folgenden benutzerdefinierten mithilfe einer täglichen Aktualisierung im Hintergrund.

• Gebotssignale von Nutzern
• Daten zu vertrauenswürdigen Geboten
• AdData Liste

Bei diesem Prozess wird die URL für tägliche Updates abgefragt, die in der benutzerdefinierten Zielgruppe definiert ist. und die URL kann eine JSON-Antwort zurückgeben.

• Die JSON-Antwort kann eines der unterstützten Metadatenfelder enthalten, für das die folgenden Anforderungen erfüllt sind: zu aktualisieren.
• Jedes JSON-Feld wird unabhängig validiert. Der Client ignoriert alle falsch formatierten Feldern, sodass das Feld in auf die Antwort.
• Eine leere HTTP-Antwort oder ein leeres JSON-Objekt „{}“ Ergebnisse in keine Metadatenaktualisierungen.
• Die Größe der Antwortnachricht muss auf 10 KB begrenzt werden.
• Alle URIs müssen HTTPS verwenden.
• trusted_bidding_uri muss dieselbe ETLD+1 wie der Käufer haben.

Beispiel: JSON-Antwort für ein tägliches Hintergrundupdate

{
    "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 Workflow für die Anzeigenauswahl orchestriert die Ausführung der vom Käufer vom Verkäufer bereitgestelltes JavaScript.

Das vom Käufer bereitgestellte JavaScript wird von der URL für die Gebotslogik abgerufen, die im benutzerdefinierte Zielgruppe. Der zurückgegebene JavaScript-Code sollte die folgenden Funktionen enthalten:

• generateBid()
• reportWin()

Das vom Verkäufer bereitgestellte JavaScript wird von der URL der Entscheidungslogik abgerufen, die unter Parameter AdSelectionConfig für die API zur Anzeigenauswahl Die 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 mit dem Format var ad = { 'render_url': url, 'metadata': json_metadata };
• auction_signals, per_buyer_signals: In der Auktion angegebene JSON-Objekte Konfigurationsobjekt

• custom_audience_bidding_signals: Von der Plattform generiertes JSON-Objekt. Die 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 dem Name der benutzerdefinierten Zielgruppe, die an der Anzeigenauswahl teilnimmt
  • activation_time und expiration_time sind der Zeitpunkt der Aktivierung und Ablauf der benutzerdefinierten Zielgruppe in Sekunden seit dem Unixzeit Epoche
  • ca_user_bidding_signals ist ein JSON-String, der im Feld „userBiddingSignals“ von CustomAudience bei der Erstellung
  • trusted_bidding_signals, contextual_signals und user_signals sind JSON Objekte. Sie werden als leere Objekte übergeben und ausgefüllt in zukünftigen Versionen. Das Format wird von der Plattform nicht erzwungen und verwaltet. durch die Anzeigentechnologie.

Ergebnis:

• ad: ist die Anzeige, auf die sich das Gebot bezieht. Das Skript darf eine Kopie von erhaltene Anzeige mit unterschiedlichen Metadaten. Das Attribut render_url des wird erwartet, dass die Anzeige unverändert bleibt.
• bid: ein Gleitkommawert, der den Gebotswert für diese Anzeige darstellt
• status: ein ganzzahliger Wert, der sein kann:
  • 0: für eine erfolgreiche Ausführung
  • 1: (oder ein beliebiger Wert ungleich null), falls eines der Eingabesignale ungültig ist. In Falls bei der Generierung eines Gebots ein Wert ungleich null zurückgegeben wird, ist der Gebotsvorgang für alle CA-Anzeigen ungültig gemacht

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 Dokumentation zu generateBid
• bid: der Gebotswert für die Anzeige

• ad_selection_config: ein JSON-Objekt, das den AdSelectionConfig-Parameter der selectAds API. 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 sellerSignals gelesen werden AdSelectionConfig API-Parameter

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

• contextual_signals, user_signals: JSON-Objekte. Sie werden derzeit als Leere Objekte und wird in zukünftigen Versionen gefüllt. Das Format ist nicht wird von der Plattform durchgesetzt und von der Anzeigentechnologie verwaltet.

• per_buyer_signals: JSON-Objekt, das aus der perBuyerSignal-Zuordnung im AdSelectionConfig API-Parameter, der die aktuelle benutzerdefinierte Version als Schlüssel verwendet Käufer der Zielgruppe Leer, wenn die Karte keinen Eintrag für das angegebene Käufer.

Ausgabe:

• score: ein Gleitkommawert, der den Punktzahlwert für diese Anzeige darstellt
• status: ein ganzzahliger Wert, der sein kann:
  • 0: für eine erfolgreiche Ausführung
  • 1: falls customAudienceSignals ungültig sind
  • 2: falls AdSelectionConfig ungültig ist
  • 3: wenn eines der anderen Signale ungültig ist
  • Alle Werte ungleich null führen dazu, dass der Prozess fehlschlägt, der Wert bestimmt den Typ der ausgelösten 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: In der Auktionskonfiguration angegebene JSON-Objekte Objekt

Ausgabe:

• status: 0 für Erfolg, Nicht-Null 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 zu scoreAds
• render_url: die Rendering-URL der erfolgreichen Anzeige
• bid: das für die erfolgreiche Anzeige angebotene Gebot
• contextual_signals: siehe Dokumentation zu generateBid

Ausgabe:

• status: 0 für Erfolg und Nicht-Null für Fehler
• results: ein JSON-Objekt, das Folgendes enthält:
  • signals_for_buyer: ein JSON-Objekt, das an reportWin übergeben wird Funktion
  • reporting_url: eine URL, die von der Plattform verwendet wird, um die Person zu benachrichtigen Impression für den Käufer

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 zu scoreAd
• signals_for_buyer: ein von reportResult zurückgegebenes JSON-Objekt
• contextual_signals, custom_audience_signals: siehe Dokumentation zu generateBid

Ausgabe:

• status: 0 für Erfolg und nicht null für Fehler
• results: ein JSON-Objekt, das Folgendes enthält:
  • reporting_url: eine URL, die von der Plattform verwendet wird, um die Person zu benachrichtigen für den Verkäufer

registerAdBeacon()

Hinweis :Sie wird von der Android-Plattform bereitgestellt und sollte nicht von AdTech.

function registerAdBeacon(
  interaction_key,
  reporting_uri
)

Eingabeparameter:

• interaction_key: Ein String, der das Ereignis darstellt. Diese wird vom wenn Sie Ereignisinteraktionen melden, reporting_uri, der benachrichtigt werden soll. Dieser Schlüssel muss zwischen dem wie Käufer oder Verkäufer die Registrierung vornehmen, und was der Verkäufer meldet.
• reporting_uri: Ein URI zum Empfang von Ereignisberichten. Dies sollte sich konkret auf der gemeldete Ereignistyp. Er muss eine POST-Anfrage akzeptieren, um beliebige Daten, die zusammen mit dem Ereignis erfasst werden.

Vordefinierte URIs für die Anzeigenauswahl

Mit vordefinierten URIs können Anzeigentechnologie-Anbieter JavaScript-Funktionen für Anzeigen Auswahllogik in AdSelectionConfig und AdSelectionFromOutcomesConfig Klassen. Für vordefinierte URIs ist kein Netzwerk erforderlich um das entsprechende JavaScript herunterzuladen. Anzeigentechnologie-Anbieter können vordefinierte URIs verwenden ohne eine registrierte Domain zum Hosten des JavaScript einrichten zu müssen.

Ein vordefinierter URI wird im folgenden Format erstellt:

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

Die Privacy Sandbox-Plattform stellt JavaScript bereit, das die Informationen aus dieser URI in der Laufzeit.

In folgenden Fällen wird ein IllegalArgumentException ausgelöst:

• Einer der erforderlichen Parameter ist nicht im URI vorhanden
• URI enthält unbekannte Parameter

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

Anwendungsfall 1: Anzeigenauswahl

Vordefinierte URIs für den Anwendungsfall ad-selection werden in der selectAds(AdSelectionConfig)-Ablauf.

Name des vordefinierten URI: highest-bid-wins

Dieser vordefinierte URI liefert ein JavaScript, das die Anzeige mit dem höchsten Gebot auswählt. nach der Gebotsabgabe. Es bietet auch eine grundlegende Berichtsfunktion, mit der Sie render_uri und bid des Gewinners.

Erforderliche Parameter

reportingUrl: Die grundlegende Berichts-URL, die mit dem Parameter render_uri und die bid der erfolgreichen Anzeige:

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

Nutzung

Wenn Ihre grundlegende Berichts-URL https://www.ssp.com/reporting lautet, ist die vordefinierte URI wäre:

`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 die selectAds(AdSelectionFromOutcomesConfig)-Workflow.

Name des vordefinierten URI: waterfall-mediation-truncation

Der vordefinierte URI waterfall-mediation-truncation stellt JavaScript-Code bereit, der Implementierung einer Kürzungslogik der abfolgebasierten Vermittlung, bei der vom JavaScript-Code eine eigene Anzeige erstellen, wenn bid größer oder gleich bid floor ist und Andernfalls wird null zurückgegeben.

Erforderliche Parameter

bidFloor: Der Schlüssel für den an getSelectionSignals() übergebenen Mindestpreis für das Gebot. der mit der Anzeige des Vermittlungs-SDKs verglichen wird.

Nutzung

Wenn die Signale für die Anzeigenauswahl so aussehen: {"bid_floor": 10}, werden die resultierenden wäre der vordefinierte URI:

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

Test

Um Ihnen den Einstieg in die Protected Audience API zu erleichtern, haben wir ein Beispiel Anwendungen in Kotlin und Java (auf GitHub verfügbar)

Vorbereitung

Die Protected Audience API erfordert JavaScript bei der Anzeigenauswahl und Impressionsberichten. Es gibt zwei Methoden, um diesen JavaScript-Code in einem Testumgebung:

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

Bei beiden Ansätzen muss für die Verarbeitung von Impressionen ein HTTPS-Endpunkt eingerichtet werden Berichterstellung.

HTTPS-Endpunkte

Um die Anzeigenauswahl und Berichte zu Impressionen zu testen, müssen Sie sieben HTTPS- Endpunkte, auf die Ihr Testgerät oder Emulator zugreifen kann:

1. Käuferendpunkt, der das JavaScript für die Gebotslogik bereitstellt.
2. Ein Endpunkt, der die Gebotssignale bereitstellt.
3. Verkäuferendpunkt, der die JavaScript-Entscheidungslogik bereitstellt.
4. Ein Endpunkt, der Bewertungssignale bereitstellt.
5. Endpunkt für Berichte zu den Impressionen des erfolgreichen Käufers.
6. Endpunkt für Berichte zu Verkäuferimpressionen.
7. Ein Endpunkt, um die täglichen Updates für eine benutzerdefinierte Zielgruppe bereitzustellen.

Der Einfachheit halber bietet das GitHub-Repository grundlegenden JavaScript-Code für Tests zu verstehen. Sie enthält auch OpenAPI-Dienstdefinitionen, die auf eine unterstützte simulierte oder Mikrodienstplattform. Weitere Informationen finden Sie im Projekt README-Datei.

Remote-Abruf von JavaScript überschreiben

Diese Funktion ist für End-to-End-Tests vorgesehen. Um Remote-Zugriff zu überschreiben abrufen möchten, muss die App im Debug-Modus mit aktivierten Entwickleroptionen ausgeführt werden.

Um den Debug-Modus für Ihre Anwendung zu aktivieren, fügen Sie folgende Zeile zur App-Attribut in der AndroidManifest.xml-Datei:

<application
  android:debuggable="true">

Hinweis: Entfernen Sie android:debuggable="true. bevor Sie Ihre

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

Sie müssen Ihren eigenen benutzerdefinierten JavaScript-Code hinzufügen, um Anzeigenauswahlroutinen wie z. B. Gebote, Bewertungsentscheidungen und Berichte. Sie können einfachen JavaScript-Code Beispiele, die alle erforderlichen Anfragen im GitHub-Repository verarbeiten. Die Beispielanwendung der Protected Audience API zeigt, wie Code aus und bereiten Sie sie für die Überschreibung vor.

Es ist möglich, JavaScript-Abrufe auf Verkäuferseite und auf Käuferseite zu überschreiben. unabhängig voneinander, aber Sie benötigen einen HTTPS-Endpunkt, um JavaScript-Code, für die Sie keine Überschreibungen angeben. In der README-Datei finden Sie Informationen zum Einrichten eines Servers für diese Fälle.

Der JavaScript-Abrufdienst kann nur für benutzerdefinierte Zielgruppen überschrieben werden, die gehören Ihrem Paket.

JavaScript auf Verkäuferseite überschreiben

So richten Sie eine Überschreibung von JavaScript auf Verkäuferseite ein: im folgenden Codebeispiel:

1. Initialisieren Sie ein AdSelectionManager-Objekt.
2. Du kannst einen Verweis auf TestAdSelectionManager aus dem AdSelectionManager-Objekt.
3. Erstellen Sie ein AdSelectionConfig-Objekt.
4. Erstellen Sie ein AddAdSelectionOverrideRequest mit dem AdSelectionConfig-Objekt und ein String-Objekt, das das JavaScript darstellt die Sie als Überschreibung verwenden möchten.
5. Rufen Sie die asynchrone overrideAdSelectionConfigRemoteInfo()-Methode mit dem Objekt AddAdSelectionOverrideRequest und relevantes Executor und OutcomeReceiver-Objekte.

Kotlin

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)

Java

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);

Im Abschnitt Anzeigenauswahl ausführen finden Sie weitere Informationen zu den werden die Felder in AdSelectionConfig dargestellt. Der Hauptunterschied ist die decisionLogicUrl wie gewünscht auf einen Platzhalterwert gesetzt werden kann. ignoriert.

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

Die asynchrone Methode overrideAdSelectionConfigRemoteInfo() verwendet die Methode OutcomeReceiver-Objekt, um das Ergebnis des API-Aufrufs zu signalisieren.

Der onResult()-Callback zeigt an, dass die Überschreibung erfolgreich angewendet wurde. Bei zukünftigen Aufrufen von selectAds() werden die Entscheidung und Berichterstellung verwendet die Sie als Überschreibung übergeben haben.

Der onError()-Callback deutet auf zwei mögliche Bedingungen hin:

• Wird versucht, mit ungültigen Argumenten zu überschreiben, AdServiceException zeigt ein IllegalArgumentException als Ursache.
• Wird versucht, eine App zu überschreiben, die nicht im Debug-Modus mit Entwickleroptionen aktiviert, wird mit AdServiceException angegeben, IllegalStateException als Ursache.

Überschreibungen auf Verkäuferseite zurücksetzen

In diesem Abschnitt wird davon ausgegangen, dass Sie das JavaScript auf Verkäuferseite überschrieben haben und dass Sie haben einen Verweis auf TestAdSelectionManager und AdSelectionConfig, der im vorherigen Abschnitt verwendet wurde.

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

1. Aufrufen der asynchronen Methode resetAllAdSelectionConfigRemoteOverrides() durch das entsprechende OutcomeReceiver-Objekt.

Kotlin

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

Java

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

Nachdem du die Überschreibungen auf Verkäuferseite zurückgesetzt hast, werden für selectAds()-Aufrufe beliebige decisionLogicUrl wird im AdSelectionConfig gespeichert, um zu versuchen, den erforderlichen JavaScript-Code abrufen.

Wenn der Aufruf von resetAllAdSelectionConfigRemoteOverrides() fehlschlägt, Der OutComeReceiver.onError()-Callback ist ein AdServiceException. Wenn das Entfernen von Überschreibungen mit einer App versucht wird, die nicht im Debug-Modus ausgeführt wird Wenn die Entwickleroptionen aktiviert sind, gibt AdServiceException Folgendes an: IllegalStateException als Ursache.

JavaScript auf Käuferseite überschreiben

1. Folgen Sie dieser Anleitung, um einer benutzerdefinierten Zielgruppe beizutreten.
2. Eine AddCustomAudienceOverrideRequest mit dem Käufer erstellen und den Namen der benutzerdefinierten Zielgruppe, die Sie überschreiben möchten, sowie den Gebotslogik und Daten, die Sie überschreiben möchten
3. Rufen Sie die asynchrone overrideCustomAudienceRemoteInfo()-Methode mit dem Objekt AddCustomAudienceOverrideRequest und relevant Executor- und OutcomeReceiver-Objekte

Kotlin

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)

Java

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 die gleichen, die bei der Erstellung verwendet wurden. der benutzerdefinierten Zielgruppe. Weitere Informationen zu diesen Feldern

Außerdem können Sie zwei zusätzliche Parameter angeben:

• biddingLogicJs: JavaScript-Code mit der Käuferlogik, die verwendet wird während der Anzeigenauswahl. Die erforderlichen Funktionssignaturen finden Sie in dieser JavaScript
• trustedBiddingSignals: Gebotssignale, die bei der Anzeigenauswahl verwendet werden sollen. Zu Testzwecken kann dies ein leerer String sein.

Die asynchrone Methode overrideCustomAudienceRemoteInfo() verwendet die Methode OutcomeReceiver-Objekt, um das Ergebnis des API-Aufrufs zu signalisieren.

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

Der onError()-Callback zeigt zwei mögliche Bedingungen an.

• Wird versucht, mit ungültigen Argumenten zu überschreiben, AdServiceException zeigt ein IllegalArgumentException als Ursache.
• Wird versucht, eine App zu überschreiben, die nicht im Debug-Modus mit Entwickleroptionen aktiviert, wird mit AdServiceException angegeben, IllegalStateException als Ursache.

Überschreibungen auf Käuferseite zurücksetzen

In diesem Abschnitt wird davon ausgegangen, dass Sie das JavaScript auf Käuferseite überschrieben haben und dass Sie haben einen Verweis auf das TestCustomAudienceManager, das im vorherigen Abschnitts.

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

1. Rufen Sie die asynchrone resetAllCustomAudienceOverrides()-Methode mit relevante Executor- und OutcomeReceiver-Objekte.

Kotlin

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

Java

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

Nachdem Sie die Überschreibungen auf Käuferseite zurückgesetzt haben, werden nachfolgende Aufrufe von selectAds() beliebige biddingLogicUrl und trustedBiddingData verwenden die in den CustomAudience gespeichert sind, um die erforderlichen JavaScript

Wenn der Aufruf von resetCustomAudienceRemoteInfoOverride() fehlschlägt, Der OutComeReceiver.onError()-Callback ist ein AdServiceException. Wenn das Entfernen von Überschreibungen mit einer App versucht wird, die nicht im Debug-Modus ausgeführt wird Bei aktivierten Entwickleroptionen wird mit AdServiceException angegeben, IllegalStateException als Ursache.

Einen Reporting-Server einrichten

Wenn Sie Überschreibungen für Remote-Abrufe verwenden, müssen Sie trotzdem einen Server einrichten. die Ihr Gerät oder Ihren Emulator erreichen kann, um auf Berichtsereignisse zu reagieren. Eine einfache Endpunkt, der 200 zurückgibt, zum Testen ausreicht. Das GitHub-Repository umfasst OpenAPI-Dienstdefinitionen, die in einem unterstützten Modell oder Mikrodienstplattform. Weitere Informationen finden Sie im Projekt README-Datei.

Suchen Sie bei den OpenAPI-Definitionen nach der Datei „reporting-server.json“. Diese Datei enthält einen einfachen Endpunkt, der 200 zurückgibt. Dies ist ein HTTP- -Antwortcode. Dieser Endpunkt wird während selectAds() verwendet und signalisiert, dass die Protected Audience API verwenden, um die Berichterstellung zu Impressionen erfolgreich abgeschlossen zu haben.

Zu testende Funktionalität

• Wenn Sie dem Training beitreten oder es verlassen, und eine benutzerdefinierte Zielgruppe basierend auf früheren Aktionen von Nutzenden.
• Initiieren der Anzeigenauswahl auf dem Gerät über gehostete JavaScripts Remote-Zugriff.
• Beobachten, wie sich die Verknüpfung einer App mit benutzerdefinierten Zielgruppeneinstellungen auf die Anzeige auswirken kann Auswahlergebnisse.
• Führen Sie nach der Anzeigenauswahl die Impressionsberichte durch.

Beschränkungen

In der folgenden Tabelle sind Einschränkungen für die Verarbeitung durch die Protected Audience API aufgeführt. Die Limits können sich je nach Feedback ändern. Für in Arbeit, erhalten Sie in den Versionshinweisen.

Komponente	Beschreibung des Limits	Limitwert
Benutzerdefinierte Zielgruppe (Kanada)	Maximale Anzahl von Anzeigen pro Zertifizierungsstelle	100
	Maximale Anzahl Zertifizierungsstellen pro Anwendung	1000
	Maximale Anzahl von Apps, die eine Zertifizierungsstelle erstellen können	1000
	Maximale Verzögerung der Aktivierungszeit einer Zertifizierungsstelle ab ihrer Erstellung	60 Tage
	Maximale Ablaufzeit einer Zertifizierungsstelle ab ihrer Aktivierungszeit	60 Tage
	Maximale Anzahl von Zertifizierungsstellen auf dem Gerät	4000
	Maximale Größe des CA-Namens	200 Byte
	Maximale Größe des täglichen Abruf-URI	400 Byte
	Maximale Größe des URI für die Gebotslogik	400 Byte
	Maximale Größe von Daten für vertrauenswürdige Gebote	10 KB
	Maximale Größe von Gebotssignalen für Nutzer	10 KB
	Maximale Anrufrate für leaveCustomAudience pro Käufer	1 pro Sekunde
	Maximale Anrufrate für joinCustomAudience pro Käufer	1 pro Sekunde
CA-Hintergrundabruf	Zeitüberschreitung beim Verbindungsaufbau	5 Sekunden
	HTTP-Lesezeitlimit	30 Sekunden
	Maximale Downloadgröße insgesamt	10 KB
	Maximale Dauer einer Abrufiteration	5 Minuten
	Maximale Anzahl von Zertifizierungsstellen pro Job aktualisiert	1000
Anzeigenauswahl	Maximale Anzahl von Käufern	Noch offen
	Maximale Anzahl Zertifizierungsstellen pro Käufer	Noch offen
	Maximale Anzahl von Anzeigen in einer Auktion	Noch offen
	Zeitüberschreitung bei der ersten Verbindung	5 Sekunden
	Zeitlimit für Verbindungslesevorgang	5 Sekunden
	Maximale Ausführungszeit von AdSelection insgesamt	10 Sekunden
	Maximale Ausführungszeit von Bidding pro Zertifizierungsstelle in AdSelection	5 Sekunden
	Maximale Ausführungszeit der Bewertung in AdSelection	5 Sekunden
	Maximale Ausführungszeit für pro Käufer in AdSelection	Noch offen
	Maximale Größe der Anzeigenauswahl-/Verkäufer-/Käufersignale	Noch offen
	Maximale Größe von Verkäufer-/Käuferskripts	Noch offen
	Maximale Anrufrate für selectAds	1 Abfragen pro Sekunde
Berichte zu Impressionen	Mindestzeit, bevor die Anzeigenauswahl aus der Persistenz entfernt wird	24 Stunden
	Maximale Anzahl der für Speicheranzeigen ausgewählten Anzeigen	Noch offen
	Maximale Größe der URL für die Berichtsausgabe	Noch offen
	Maximale Zeit für Impressionsberichte	Noch offen
	Maximale Anzahl von Wiederholungsversuchen für Benachrichtigungsaufrufe	Noch offen
	Zeitüberschreitung der Verbindung	5 Sekunden
	Maximale Gesamtausführungszeit für reportImpression	2 Sekunden
	Maximale Anrufrate für reportImpressions	1 Abfragen pro Sekunde
Ereignisberichte	Maximale Anzahl von Beacons pro Käufer und Auktion	10
	Maximale Anzahl von Beacons pro Verkäufer und Auktion	10
	Maximale Größe des Ereignisschlüssels	40 Byte
	Maximale Größe von Ereignisdaten	64KB
Anzeigen	Maximale Größe der Anzeigenliste	10 KB für alle freigegeben AdData in einer einzigen Zertifizierungsstelle für kontextabhängige
URLs	Maximale Länge eines als Eingabe verwendeten URL-Strings	Noch offen
JavaScript	Maximale Ausführungszeit	1 Sekunde für Gebote und Bewertung im Impressionsbericht
	Maximal verwendeter Arbeitsspeicher	10 MB

Fehler und Probleme melden

Ihr Feedback ist ein wichtiger Teil der Privacy Sandbox für Android. Feedback geben alle Probleme, die Sie gefunden haben, oder Ideen zur Verbesserung der Privacy Sandbox für Android.