Wählen Sie beim Lesen der Dokumentation zur Privacy Sandbox für Android über die Schaltfläche Entwicklervorschau oder Beta die Programmversion aus, mit der Sie arbeiten. Die genaue Vorgehensweise kann variieren.
Die Protected Audience API für Android (früher FLEDGE) umfasst die Custom Audience API und die Ad Selection API. AdTech-Plattformen und Werbetreibende können diese APIs verwenden, um auf Grundlage früherer App-Interaktionen interessenspezifische Anzeigen auszuliefern. Dadurch wird die Weitergabe von Kennungen in Apps und die Weitergabe von App-Interaktionsinformationen eines Nutzers an Dritte eingeschränkt.
Die Custom Audience API konzentriert sich auf die Abstraktion „Benutzerdefinierte Zielgruppe“, die eine Gruppe von Nutzern mit gemeinsamen Absichten repräsentiert. Ein Werbetreibender kann einen Nutzer mit einer benutzerdefinierten Zielgruppe registrieren und ihr relevante Anzeigen zuordnen. Diese Informationen werden lokal gespeichert und können für die Gebotsabgabe, die Anzeigenfilterung 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. Zu diesem Zweck berücksichtigt das System relevante Anzeigen, die mit der benutzerdefinierten Zielgruppe verknüpft sind, und führt zusätzliche Verarbeitung für Anzeigen durch, die eine AdTech-Plattform an das Gerät zurückgibt.
AdTech-Plattformen können diese APIs integrieren, um Remarketing zu implementieren, das die Privatsphäre der Nutzer wahrt. In zukünftigen Releases sollen weitere Anwendungsfälle unterstützt werden, einschließlich App-Installationsanzeigen. Weitere Informationen zur Protected Audience API für Android finden Sie im Designvorschlag.
In diesem Leitfaden wird beschrieben, wie Sie mit der Protected Audience API unter Android Folgendes tun:
- Benutzerdefinierte Zielgruppen verwalten
- Anzeigenauswahl auf einem Gerät einrichten und ausführen
- Berichte zu Anzeigenimpressionen erstellen
Hinweis
Führen Sie die folgenden Schritte aus, bevor Sie beginnen:
- Richten Sie Ihre Entwicklungsumgebung für die Privacy Sandbox für Android ein.
- Installieren Sie entweder ein System-Image auf einem unterstützten Gerät oder richten Sie einen Emulator ein, der die Privacy Sandbox für Android unterstützt.
Aktivieren Sie in einem Terminal den Zugriff auf die Protected Audience API (standardmäßig deaktiviert) mit dem folgenden ADB-Befehl.
adb shell device_config put adservices ppapi_app_allow_list \"*\"
Fügen Sie Ihrem App-Manifest die Berechtigung
ACCESS_ADSERVICES_CUSTOM_AUDIENCE
hinzu:<uses-permission android:name="android.permission.ACCESS_ADSERVICES_CUSTOM_AUDIENCE" />
Verweisen Sie im Element
<application>
Ihres Manifests auf eine Anzeigendienstkonfiguration:<property android:name="android.adservices.AD_SERVICES_CONFIG" android:resource="@xml/ad_services_config" />
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>
Standardmäßig erzwingt die Ad Selection API ein Limit für den maximalen Speicher, der von einem Script für die Berichterstellung zu Impressionen oder Auktionen zugewiesen werden kann. Für die Speicherbeschränkungsfunktion ist WebView-Version 105.0.5195.58 oder höher erforderlich. Die Plattform erzwingt eine Versionsprüfung und Aufrufe der APIs
selectAds
undreportImpression
schlagen fehl, wenn dies nicht erfüllt wird. Dafür gibt es zwei Möglichkeiten: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 muss der zuvor genannten Version entsprechen oder höher sein.
Einer benutzerdefinierten Zielgruppe beitreten
Eine benutzerdefinierte Zielgruppe ist eine Gruppe von Nutzern mit gemeinsamen Absichten oder Interessen, die von der App eines Werbetreibenden 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 Sie eine benutzerdefinierte Zielgruppe oder treten sie asynchron bei:
- Initialisieren Sie das Objekt
CustomAudienceManager
. - Erstellen Sie ein
CustomAudience
-Objekt. Geben Sie dazu wichtige Parameter wie das Paket des Käufers und einen relevanten Namen an. Initialisieren Sie dann das ObjektJoinCustomAudienceRequest
mit dem ObjektCustomAudience
. - Rufen Sie das asynchrone
joinCustomAudience()
mit demJoinCustomAudienceRequest
-Objekt und relevantenExecutor
- undOutcomeReceiver
-Objekten auf.
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 wird jedes CustomAudience
-Objekt auf einem Gerät eindeutig identifiziert:
owner
: Paketname der Inhaber-App. Er wird implizit auf den Paketnamen der aufrufenden App festgelegt.buyer
: ID des Käufernetzwerks, über das Anzeigen für diese benutzerdefinierte Zielgruppe verwaltet werden.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. Aus Datenschutzgründen unterscheidet das Ergebnis der API nicht zwischen „Erstellen“ und „Aktualisieren“.
Außerdem muss das CustomAudience
-Element mit den folgenden erforderlichen Parametern erstellt werden:
- URL für tägliche Aktualisierung: Eine HTTPS-URL, die täglich im Hintergrund abgefragt wird, um die Gebotssignale für Nutzer einer benutzerdefinierten Zielgruppe, vertrauenswürdige Gebotsdaten sowie Rendering-URLs und -Metadaten für Anzeigen zu aktualisieren.
- Gebotslogik-URL: Eine HTTPS-URL, die während der Anzeigenauswahl abgefragt wird, um die JavaScript-Gebotslogik eines Käufers abzurufen. Erforderliche Funktionssignaturen in diesem JavaScript-Code
- IDs für das Anzeigenrendering: Eine beliebige ID, die von der Anzeigentechnologie des Käufers festgelegt wird. Dies ist eine 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 erst nach der Aktivierungszeit an der Anzeigenauswahl und täglichen Aktualisierungen teilnehmen. Das kann beispielsweise nützlich sein, um inaktive Nutzer einer App anzusprechen.
- Ablaufzeit: Eine zukünftige Zeit, nach der die benutzerdefinierte Zielgruppe vom Gerät entfernt wird.
- Gebotssignale für Nutzer: Ein JSON-String mit Nutzersignalen (z. B. die bevorzugte Sprache des Nutzers), die das JavaScript der Gebotslogik eines Käufers verwendet, um bei der Anzeigenauswahl Gebote zu generieren. Dieses Format erleichtert AdTech-Plattformen die Wiederverwendung von Code plattformübergreifend und vereinfacht die Verwendung von JavaScript-Funktionen.
- Trusted Bidding-Daten: Eine HTTPS-URL und eine Liste von Strings, die bei der Anzeigenauswahl verwendet werden, um Gebotssignale von einem vertrauenswürdigen Schlüssel/Wert-Dienst abzurufen.
- Anzeigen: Eine Liste von
AdData
-Objekten für die Anzeigen, die an der Anzeigenauswahl beteiligt sind. JedesAdData
-Objekt besteht aus:- Render-URL: Eine HTTPS-URL, die abgefragt wird, um die finale Anzeige zu rendern.
- Metadaten: Ein JSON-Objekt, das als String formatiert ist und Informationen enthält, die von der Gebotslogik des Käufers während der Anzeigenauswahl verarbeitet werden sollen.
- Anzeigenfilter: Eine Klasse, die alle erforderlichen Informationen für die Filterung von App-Installationsanzeigen und das Frequency Capping bei der Anzeigenauswahl enthält.
Hier ein Beispiel für eine CustomAudience
-Objektinstanziierung:
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();
Ergebnisse von „joinCustomAudience()“ verarbeiten
Die asynchrone joinCustomAudience()
-Methode verwendet das Objekt OutcomeReceiver
, um das Ergebnis des API-Aufrufs zu signalisieren.
- Der Callback
onResult()
gibt an, dass die benutzerdefinierte Zielgruppe erfolgreich erstellt oder aktualisiert wurde. - Der Callback
onError()
steht für zwei mögliche Bedingungen.- Wenn
JoinCustomAudienceRequest
mit ungültigen Argumenten initialisiert wird, gibtAdServicesException
einIllegalArgumentException
als Ursache an. - Bei allen anderen Fehlern wird ein
AdServicesException
mitIllegalStateException
als Ursache zurückgegeben.
- Wenn
Hier ein Beispiel für den Umgang mit dem Ergebnis 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 Nutzer die Geschäftskriterien für eine bestimmte benutzerdefinierte Zielgruppe nicht mehr erfüllt, kann eine App oder ein SDK leaveCustomAudience()
aufrufen, um die benutzerdefinierte Zielgruppe vom Gerät zu entfernen. So entfernen Sie ein CustomAudience
-Element anhand seiner eindeutigen Parameter:
- Initialisieren Sie das Objekt
CustomAudienceManager
. - Initialisieren Sie
LeaveCustomAudienceRequest
mitbuyer
undname
der benutzerdefinierten Zielgruppe. Weitere Informationen zu diesen Eingabefeldern finden Sie unter Einer benutzerdefinierten Zielgruppe beitreten. - Rufen Sie die asynchrone
leaveCustomAudience()
-Methode mit demLeaveCustomAudienceRequest
-Objekt und den relevantenExecutor
- undOutcomeReceiver
-Objekten auf.
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()
signalisiert OutcomeReceiver
das Ende eines API-Aufrufs. Zum Schutz der Privatsphäre wird bei einem Fehlerergebnis nicht zwischen internen Fehlern und ungültigen Argumenten unterschieden. Der onResult()
-Callback wird nach Abschluss des API-Aufrufs aufgerufen, unabhängig davon, ob eine übereinstimmende benutzerdefinierte Zielgruppe entfernt wurde oder nicht.
Anzeigenauswahl ausführen
Wenn Sie die Protected Audience API zur Auswahl von Anzeigen verwenden möchten, rufen Sie die Methode selectAds()
auf:
- Initialisieren Sie ein
AdSelectionManager
-Objekt. - Erstellen Sie ein
AdSelectionConfig
-Objekt. - Rufen Sie die asynchrone
selectAds()
-Methode mit demAdSelectionConfig
-Objekt und den relevantenExecutor
- undOutcomeReceiver
-Objekten auf.
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);
Für die Methode selectAds()
ist eine Eingabe AdSelectionConfig
erforderlich, in der Sie die folgenden erforderlichen Parameter angeben müssen:
- Verkäufer: Kennung des Verkäufer-Werbenetzwerks, das die Anzeigenauswahl initiiert.
- URL für die Entscheidungslogik: Eine HTTPS-URL, die abgefragt wird, um die JavaScript-Logik des Verkäufer-Werbenetzwerks zu erhalten.
- HTTPS-URL: Wird abgefragt, um die JavaScript-Logik des Verkäufer-Werbenetzwerks zu erhalten. Erforderliche Funktionssignaturen
- Vordefinierter URI: Er entspricht dem Format für die Anzeigenauswahl von FLEDGE.
IllegalArgumentException
wird ausgelöst, wenn ein nicht unterstützter oder fehlerhafter vordefinierter URI übergeben wird.
- Benutzerdefinierte Zielgruppenkäufer: Eine vollständige Liste der Kennungen für Werbenetzwerke von Käufern, die vom Verkäufer zur Teilnahme an der Anzeigenauswahl zugelassen wurden.
Diese Käuferkennungen entsprechen den
CustomAudience.getBuyer()
der teilnehmenden benutzerdefinierten Zielgruppen.
Die folgenden Parameter können optional für eine individuellere Anzeigenauswahl angegeben werden:
- Signale zur Anzeigenauswahl: Ein JSON-Objekt, das als String formatiert ist und Signale enthält, die vom JavaScript-Code für die Gebotslogik des Käufers verarbeitet werden, der von
CustomAudience.getBiddingLogicUrl()
abgerufen wird. - Verkäufersignale: Ein JSON-Objekt, das als String formatiert ist und Signale enthält, die von der vom Verkäufer abgerufenen JavaScript-Entscheidungslogik von
AdSelectionConfig.getDecisionLogicUrl()
verarbeitet werden. - Pro Käufersignale: Eine Zuordnung von JSON-Objekten, die als Strings formatiert sind und Signale enthalten, die vom JavaScript-Code für die Gebotslogik bestimmter Käufer verarbeitet werden, der von
CustomAudience.getBiddingLogicUrl()
abgerufen wird und von den Käuferfeldern teilnehmender benutzerdefinierter Zielgruppen identifiziert wird. - Kontextbezogene Anzeigen:Eine Sammlung von Anzeigenkandidaten, die während einer Auktion, die nicht im Rahmen einer Protected Audience-Auktion stattfindet, direkt von Käufern gesammelt werden.
Nachdem eine Anzeige ausgewählt wurde, werden die Ergebnisse, Gebote und Signale intern zur Berichterstellung gespeichert. Der OutcomeReceiver.onResult()
-Callback gibt ein AdSelectionOutcome
zurück, das Folgendes enthält:
- Eine Rendering-URL für die erfolgreiche Anzeige, die von
AdData.getRenderUrl()
abgerufen wurde. - Eine für den Gerätenutzer eindeutige Anzeigenauswahl-ID. Mit dieser ID wird die Anzeigenimpression erfasst.
Wenn die Anzeigenauswahl aufgrund von ungültigen Argumenten, Zeitüberschreitungen oder einem übermäßigen Ressourcenverbrauch nicht erfolgreich abgeschlossen werden kann, gibt der OutcomeReceiver.onError()
-Callback ein AdServicesException
mit folgendem Verhalten zurück:
- Wenn die Anzeigenauswahl mit ungültigen Argumenten initiiert wird, gibt
AdServicesException
einIllegalArgumentException
als Ursache an. - Bei allen anderen Fehlern wird ein
AdServicesException
mitIllegalStateException
als Ursache zurückgegeben.
Kontextbezogene Anzeigen
Protected Audience kann kontextbezogene Anzeigen in eine Protected Auktion einbinden.
Kontextbezogene Anzeigen müssen auf dem AdTech-Server ausgewählt und außerhalb der Protected Audience APIs an das Gerät zurückgegeben werden. Kontextbezogene Anzeigen können dann mithilfe von AdSelectionConfig
in die Auktion aufgenommen werden. Dann haben sie dieselbe Funktion wie bei Anzeigen auf Geräten, einschließlich der Möglichkeit zur Filterung nach auszuschließenden Anzeigen. Sobald die Protected Audience-Auktion abgeschlossen ist, müssen Sie reportImpression()
aufrufen. Dadurch wird reportWin()
in der erfolgreichen kontextbezogenen Anzeige aufgerufen, und zwar nach dem gleichen Muster wie bei Berichten zu Impressionen, um die erfolgreiche Anzeige auf einem Gerät zu erhalten. Für jede kontextbezogene Anzeige sind ein Käufer, ein Gebot, ein Link zur Berichtslogik, eine Rendering-URL und Anzeigenmetadaten erforderlich.
Zum Bereitstellen kontextbezogener Anzeigen in der App muss die Ziel-App ein ContextualAds
-Objekt erstellen:
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 von AdSelectionConfig
übergeben werden:
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);
Filterung von App-Installationsanzeigen
Mit dem Filter für App-Installationsanzeigen können Sie Installationsanzeigen für Apps filtern, die bereits auf einem Gerät installiert sind.
Zuerst legen Sie fest, welche Werbetreibenden nach dem installierten Paket filtern können. Dies muss in der App geschehen, auf die Sie eine Anzeige ausrichten möchten.
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 dann die installierten Apps herausfiltern, die Sie während der Gebotserstellung angegeben haben. Wenn Sie einem Werbetreibenden den Zugriff auf den Installationsstatus dieser App entziehen möchten, führen Sie den Code noch einmal aus und entfernen Sie die Informationen des Werbetreibenden.
Im nächsten Schritt richten Sie die Anzeigenfilterung in der Publisher-App ein. Der Anbieter, der die Anzeige in der Publisher-App bereitstellt (wahrscheinlich ein Supply-Side-SDK), muss sein AdFilters
-Objekt mit Informationen dazu initialisieren, welche Anzeigen für die Apps herausgefiltert werden sollen:
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 einen AdFilter
für Anzeigen festlegen, die in ihren benutzerdefinierten Zielgruppen enthalten sind.
AdFilters
kann auch bei der Instanziierung eines neuen AdData
-Objekts übergeben werden:
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();
Frequency Capping-Filter
Mithilfe von Frequency Capping können Anzeigentechnologie-Anbieter die Häufigkeit begrenzen, mit der eine Anzeige ausgeliefert wird. Durch das Filtern mit Frequency Capping wird eine übermäßige Auslieferung von Anzeigen verringert und die alternative Anzeigenauswahl für eine bestimmte Werbekampagne optimiert.
Es gibt zwei Hauptkomponenten eines Frequency Capping-Filters: den Anzeigenereignistyp und den Anzeigenzähler-Schlüssel. Folgende Anzeigenereignistypen können verwendet werden:
- Gewonnen (demnächst verfügbar): Ein Gewinnereignis bedeutet, 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. Gewinndaten sind nur für Anzeigen innerhalb einer bestimmten benutzerdefinierten Zielgruppe sichtbar.
- Impression: Unabhängig von
reportImpression
verwendet ein On-Device-Aufrufer (SSP oder MMP)updateAdCounterHistogram()
, um Impressionsereignisse an der gewünschten Stelle im Code aufzurufen. Impressionsereignisse sind für alle Anzeigen einer bestimmten DSP sichtbar und nicht auf Anzeigen in derselben benutzerdefinierten Zielgruppe beschränkt. - Anzeigen: Das Ereignis wird vom On-Device-Aufrufer (SSP oder MMP) an einer bestimmten Stelle im Code durch 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 Aufrufer auf dem Gerät (SSP oder MMP) an einer bestimmten Stelle im Code durch 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 Sell-Side 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, sodass zukünftige Auktionen aktuelle Informationen zur Auslieferung einer bestimmten Anzeige für einen Nutzer enthalten. Die Anzeigenereignistypen sind nicht zwingend an die entsprechende Nutzeraktion gebunden und stellen Richtlinien dar, mit denen Aufrufer ihr Ereignissystem strukturieren können. Um die Anzeigenzähler zum Zeitpunkt eines Ereignisses zu erhöhen, gibt der Akteur auf dem Gerät die Anzeigenauswahl-ID der erfolgreichen Anzeigenauktion an.
Anzeigenzählerschlüssel sind beliebige vorzeichenbehaftete 32-Bit-Ganzzahlen, die von einem Käufer in der Anzeigentechnologie zugewiesen werden. Sie entsprechen einem bestimmten Satz von Anzeigen, wie von der DSP definiert. Da Anzeigenzählerschlüssel nur auf Anzeigen einer bestimmten DSP beschränkt sind, können diese Schlüssel ausgewählt werden, ohne dass sie sich mit Histogrammen einer anderen Anzeigentechnologie überschneiden. Anzeigenzählerschlüssel werden verwendet, um DSP-spezifische Kennungen in den Anzeigen einer DSP oder innerhalb einer bestimmten benutzerdefinierten Zielgruppe zu erhöhen und Anzeigen aus zukünftigen Auktionen herauszufiltern.
Zählerschlüssel können verwendet werden, um Anzeigen zu priorisieren, die für einen bestimmten Nutzer basierend auf den Interaktionen mit anderen Anzeigen eines bestimmten Käufer-Anzeigentechnologien wahrscheinlich interessanter sind. So stellt beispielsweise eine Anzeige, die durch gewonnene Anzeigenauktionen, Aufrufe und Klicks ein hohes Maß an Engagement erzielt hat, einen abgeleiteten Datenpunkt dar. Zur Veranschaulichung: Eine Anzeige für Linkshänder Golfschläger könnte darauf hinweisen, dass der Nutzer nicht an Rechtshänder interessiert ist. Ein Frequency Capping-Filter für einen Zählerschlüssel, der linkshändigen Anzeigen zugewiesen ist, könnte Anzeigen für Rechtshänder herausfiltern.
Wenn Sie Frequency Capping in Ihrer Auktion verwenden möchten, müssen Sie zuerst KeyedFrequencyCap
-Objekte erstellen, wie unten gezeigt:
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 übergeben.
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 Objekt AdFilters
mit Frequency Capping-Filtern gefüllt ist, kann es beim Erstellen der benutzerdefinierten Zielgruppe übergeben werden:
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 die erforderlichen Klick-, Aufruf- oder Impressionsereignisse aufrufen.
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 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 die Nutzlast für Auktionen für Bidding- und Auktionsdienste generiert wird.Mit diesem Toolkit können Anzeigentechnologien die Interaktionen zwischen Nutzern und den Anzeigen innerhalb ihrer benutzerdefinierten Zielgruppen flexibel nutzen, um das Anzeigen-Targeting zu optimieren und gleichzeitig die übermäßige Auslieferung von Anzeigen zu minimieren.
Kontextbezogene Anzeigenfilterung ohne Netzwerkaufrufe
Wenn auf dem Gerät keine Remarketing-Nachfrage besteht, können Sie die Anzeigenauswahl für kontextbezogene Anzeigen ohne Netzwerkaufrufe ausführen. Mit vordefinierten URIs und einer Liste von kontextbezogenen Anzeigen mit Geboten muss die Plattform keine Gebotslogik, Gebotssignale und Bewertungssignale abrufen. Die Plattform verwendet einen vordefinierten URI, um die kontextbezogene Anzeige mit dem höchsten Gebot auszuwählen.
Zur Verbesserung der Latenz können Anzeigentechnologie-Anbieter einen Ablauf zur Anzeigenauswahl ausführen, der nur kontextbezogene Anzeigen mit Funktionen zur Anzeigenfilterung ohne Netzwerkaufrufe umfasst. Dazu werden vorgefertigte URIs zum Bewerten von Signalen 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 aus:
- Anzeigenfilterung einrichten
- Kontextbezogene Anzeigen erstellen
Erstellen Sie ein
AdSelectionConfig
-Objekt mit Folgendem:- Eine leere Liste mit Käufern
- Einen vordefinierten URI zur Auswahl des höchsten Gebots
- Kontextbezogene Anzeigen
- Ein leerer URI für die Bewertungssignale. Ein leerer URI darf darauf hinweisen, dass Sie keine vertrauenswürdigen Signale 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();
Anzeigenauswahl ausführen:
adSelectionManager.selectAds( adSelectionConfig, executor, outcomeReceiver);
Eigenen JavaScript-Code für die Berichterstellung unter Verwendung vordefinierter URIs ausführen
Derzeit bietet die Privacy Sandbox-Plattform nur eine grundlegende JavaScript-Implementierung für die Berichterstellung, die für vordefinierte URIs verfügbar ist. Wenn Sie Ihr eigenes JavaScript für die Berichterstellung ausführen und dabei vordefinierte URIs für eine Anzeigenauswahl mit niedriger Latenz verwenden möchten, können Sie die DecisionLogicUri
zwischen der Anzeigenauswahl und der Berichterstellung überschreiben.
- Schritte zur Anzeigenauswahl für kontextbezogene Anzeigen mit vordefinierten URIs ausführen
Erstellen Sie eine Kopie von „
AdSelectionConfig
“, bevor Sie Berichte erstellenadSelectionConfigWithYourReportingJS = adSelectionConfig.cloneToBuilder() // Replace <urlToFetchYourReportingJS> with your own URL: .setDecisionLogicUri(Uri.parse(<urlToFetchYourReportingJS>)) .build();
Berichte zu Impressionen 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
Für die Wasserfall-Vermittlung müssen mehrere Drittanbieter-SDKs (Drittanbieter-Netzwerke) von einem eigenen SDK-Vermittlungsnetzwerk orchestriert werden. Die abfolgebasierte Vermittlung funktioniert auf die gleiche Weise, unabhängig davon, ob die Auktion auf einem Gerät oder über Gebots- und Auktionsdienste (B&A) stattfand.
Drittanbieternetzwerke
Drittanbieternetzwerke müssen einen Adapter bereitstellen, mit dem das Vermittlungsnetzwerk die erforderlichen Methoden zur Durchführung einer Auktion aufrufen kann:
- Anzeigenauswahl ausführen
- Impressionen in Berichten
Hier ein Beispiel für einen Vermittlungsnetzwerkadapter:
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() {...}
}
Jedes SDK hat eigene Dienst-Manager und Clients 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-Erklärung für B&A-Auktionen lesen. Berichte zu Anzeigenimpressionen erstellen (siehe Berichte zu Impressionen für einzelne SSPs)
Vermittlungsnetzwerk
Ähnlich wie bei Drittanbieter-Netzwerken benötigen Vermittlungsnetzwerke selectAds
- und reportImpression
-Implementierungen. Weitere Informationen finden Sie in den Abschnitten zum Ausführen der Anzeigenauswahl und zum Melden von Anzeigenimpressionen.
Vermittlungsnetzwerke sind für die Ausführung der Vermittlungskette und ihre Platzierung in der Vermittlungskette verantwortlich. Im nächsten Abschnitt wird beschrieben, wie dieser Prozess eingerichtet und ausgeführt wird.
Vermittlungskette und Mindestpreise abrufen
Das Vermittlungsnetzwerk ist dafür verantwortlich, die kontextbezogenen Anzeigen von Erstanbieter, die Vermittlungskette und die Mindestpreise der Drittanbieter-Netzwerke abzurufen. Dies kann bei einer Anfrage zum Abrufen kontextbezogener Anzeigen vorkommen, die vom Vermittlungsnetzwerk ausgeführt werden. Die Vermittlungskette bestimmt, wie die Drittanbieternetzwerke durchlaufen werden, und die Mindestpreise können als adSelectionSignals
an den Auktionsprozess übergeben werden.
Netzwerk-Placement in der Vermittlungskette
Ein Vermittlungs-SDK kann sich basierend auf seinem Live-eCPM von eigenen Anzeigengeboten in die Vermittlungskette einfügen. In der Protected Audience API sind Anzeigengebote intransparent. Ein Mediation SDK sollte AdSelectionFromOutcomesConfig
verwenden, damit das Gebot einer bestimmten Anzeige mit dem Mindestpreis des nächsten Drittanbieternetzwerks in der Kette verglichen werden kann. Ist das eigene Gebot höher als der Mindestpreis, wird das Mediation SDK vor diesem Drittanbieternetzwerk platziert.
Anzeigenauswahl ausführen
Zum Abrufen eines Anzeigenkandidaten mit selbst erhobenen Daten kann das Vermittlungsnetzwerk eine On-Device-Auktion ausführen, wobei die Schritte im Abschnitt Anzeigenauswahl ausführen ausgeführt werden. Dadurch werden eine mögliche Anzeige mit selbst erhobenen Daten, ein Gebot und ein AdSelectionId
generiert, die im Vermittlungsprozess verwendet werden.
„AdSelectionFromResultsConfig“ erstellen
Mit AdSelectionFromOutcomesConfig
kann das Vermittlungsnetzwerk eine Liste von AdSelectionIds
(Ergebnissen aus früheren Auktionen), Signale zur Anzeigenauswahl und einen URI übergeben, um JavaScript-Code abzurufen, mit dem eine Anzeige aus mehreren möglichen Anzeigen ausgewählt wird. Die Liste der AdSelectionIds zusammen mit ihren Geboten und Signalen wird an den JavaScript-Code übergeben. Dieser kann eines der AdSelectionIds
zurückgeben, wenn es den Mindestpreis des Gebots übersteigt, oder gar keine, wenn die Vermittlungskette fortgesetzt werden soll.
Vermittlungsnetzwerke erstellen ein AdSelectionFromOutcomesConfig
anhand des selbst erhobenen AdSelectionId
aus dem vorherigen Abschnitt und dem Mindestpreis für das entsprechende Drittanbieternetzwerk. Für jeden Schritt in der Vermittlungskette sollte eine neue AdSelectionFromOutcomesConfig
erstellt werden.
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){}
}
Die selectAds()
-Methodenüberschreibung für die abfolgebasierte Vermittlung erfordert eine AdSelectionFromOutcomesConfig
-Eingabe, in der Sie die folgenden erforderlichen Parameter angeben müssen:
- Verkäufer: Kennung des Verkäufer-Werbenetzwerks, das die Anzeigenauswahl initiiert.
- AdSelectionIds: Eine Singleton-Liste einer früheren
selectAds()
-Ausführung für eine eigene Anzeige. - Signale zur Anzeigenauswahl: Ein JSON-Objekt, das als String formatiert ist und Signale für die Gebotslogik des Käufers enthält. Fügen Sie in diesem Fall den für das jeweilige Drittanbieternetzwerk abgerufenen Mindestpreis hinzu.
- Auswahllogik-URI: Eine HTTPS-URL, die während der Anzeigenauswahl abgefragt wird, um das JavaScript des Vermittlungsnetzwerks für die Auswahl einer erfolgreichen Anzeige abzurufen. Erforderliche Funktionssignaturen finden Sie in diesem JavaScript-Code. Über das JavaScript sollte die Drittanbieteranzeige zurückgegeben werden, wenn das Gebot über dem Mindestpreis liegt. Andernfalls wird
null
zurückgegeben. So kann die Vermittlungskette vom Mediation SDK abgeschnitten werden, wenn ein Gewinner ermittelt wurde.
Rufen Sie mit der erstellten AdSelectionOutcomesConfig
die Methode selectAds()
des Drittanbieternetzwerks auf, das sich zuerst in der Kette befindet.
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
Im Folgenden finden Sie die Reihenfolge der Vorgänge, die den Vermittlungsprozess durchlaufen müssen.
- Wählen Sie eigene Anzeigen aus.
- Über die Vermittlungskette iterieren Gehen Sie für jedes Drittanbieter-Netzwerk so vor:
- Erstellen Sie
AdSelectionFromOutcomeConfig
, einschließlich desoutcomeId
des 1P und des Drittanbieter-SDKs als Mindestpreis. - Rufen Sie
selectAds()
mit der Konfiguration aus dem vorherigen Schritt auf. - Wenn das Ergebnis nicht leer ist, wird die Anzeige zurückgegeben.
- Rufen Sie die Methode
selectAds()
des aktuellen SDK-Netzwerkadapters auf. Wenn das Ergebnis nicht leer ist, wird die Anzeige zurückgegeben.
- Erstellen Sie
- Wird in der Kette kein Gewinner gefunden, wird die eigene Anzeige zurückgegeben.
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) { ... }
}
Anzeigenimpressionen melden
Je nachdem, wie die Auktion lä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, folgen Sie der Anleitung im Abschnitt zu Berichten zu Impressionen der abfolgebasierten Vermittlung.
Berichte zu Impressionen einer einzelnen SSP
Nachdem im Workflow zur Anzeigenauswahl eine erfolgreiche Anzeige ausgewählt wurde, können Sie die Impression mit der Methode AdSelectionManager.reportImpression()
an die teilnehmenden Buy-Side- und Sell-Side-Plattformen zurückmelden. So erfassen Sie eine Anzeigenimpression:
- Initialisieren Sie ein
AdSelectionManager
-Objekt. - Erstellen Sie ein
ReportImpressionRequest
-Objekt mit der Anzeigenauswahl-ID. - Rufen Sie die asynchrone
reportImpression()
-Methode mit demReportImpressionRequest
-Objekt und den relevantenExecutor
- undOutcomeReceiver
-Objekten auf.
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 Parametern:
- Anzeigenauswahl-ID: Eine ID, die nur für einen Gerätenutzer eindeutig ist und eine erfolgreiche Anzeigenauswahl kennzeichnet.
- Konfiguration für Anzeigenauswahl: Dies ist die gleiche Konfiguration, die im
selectAds()
-Aufruf verwendet wird, der durch die angegebene Anzeigenauswahl-ID identifiziert wird.
Die asynchrone reportImpression()
-Methode verwendet das Objekt OutcomeReceiver
, um das Ergebnis des API-Aufrufs zu signalisieren.
- Der Callback
onResult()
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
einIllegalArgumentException
als Ursache an. - Bei allen anderen Fehlern wird ein
AdServicesException
mitIllegalStateException
als Ursache zurückgegeben.
- Wenn der Aufruf mit einem ungültigen Eingabeargument initialisiert wird, gibt
Berichte zu Impressionen bei der abfolgebasierten Vermittlung
Ein Vermittlungs-SDK muss das erfolgreiche SDK erfassen, damit der zugehörige Berichtsprozess ausgelöst wird. Die SDKs, die Teil einer Vermittlungskette sind, sollten dem Vermittler eine Methode zur Verfügung stellen, die er aufrufen kann, um einen eigenen Berichtsprozess auszulösen. Ein SDK, das an einer vermittelten Auktion teilnimmt, kann anhand der oben genannten Schritte eigene Berichte erstellen.
SSPs können dieses Codebeispiel für das Drittanbieter-SDK als Prototyp für die Teilnahme an Vermittlungsabläufen verwenden:
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 Käuferplattform bereitgestellt werden:
Plattformendpunkt auf Käuferseite:
- Die API ruft mit der in der benutzerdefinierten Zielgruppe angegebenen URL der Gebotslogik den vom Käufer bereitgestellten JavaScript-Code ab, der die Logik enthält, um eine URL für Berichte zu Impressionen zurückzugeben.
- Rufen Sie die JavaScript-Funktion
reportWin()
auf. Damit soll die URL für Impressionsberichte des Käufers zurückgegeben werden.
Endpunkt der Sell-Side-Plattform:
- Verwenden Sie die im Objekt
AdSelectionConfig
angegebene URL für die Entscheidungslogik, um den JavaScript-Code der Entscheidungslogik des Verkäufers abzurufen. - Rufen Sie die JavaScript-Funktion
reportResult()
auf. Damit soll die URL für Berichte zu den Impressionen des Käufers zurückgegeben werden.
Berichte zu Gebots- und Auktionsdiensten
Eine Auktion, die über Gebots- und Auktionsdienste durchgeführt wird, enthält alle erforderlichen Berichtsinformationen, einschließlich der generierten URLs für Berichte zu Anzeigeninteraktionen, die in der verschlüsselten Antwort der serverseitigen Auktion enthalten sind. Nach der Entschlüsselung der Antwort werden die entsprechenden URLs bei der Plattform registriert, sodass für Berichte zu Anzeigen und Impressionen die oben genannten Schritte befolgt werden.
Best-Effort-Berichte zu Impressionen
Die Methode reportImpression()
ermöglicht eine optimale Berichterstellung.
Anzeigeninteraktionen melden
Protected Audience bietet Unterstützung für Berichte zu detaillierteren Interaktionen mit einer gerenderten Anzeige. Dazu können Interaktionen wie Aufrufdauer, Klicks, Mouseovers oder andere nützliche Messwerte gehören. Um diese Berichte zu erhalten, sind zwei Schritte erforderlich. Zunächst müssen Käufer und Verkäufer sich registrieren, um diese Berichte in ihrem JavaScript für die Berichterstellung zu erhalten. Dann muss der Kunde diese Ereignisse melden.
Registrierung für den Empfang von Interaktionsereignissen
Die Registrierung für Interaktionsereignisse erfolgt in den JavaScript-Funktionen reportWin()
und reportResult()
des Käufers über eine von der Plattform bereitgestellte JavaScript-Funktion: registerAdBeacon
. Wenn Sie sich registrieren möchten, um einen Ereignisbericht zu erhalten, rufen Sie einfach die Plattform-JavaScript-Funktion über Ihr Berichts-JavaScript auf. Im folgenden Snippet wird der reportWin()
eines Käufers verwendet. Dies gilt jedoch auch 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;
}
Interaktionsereignisse melden
Nachdem Kunden eine Impression erfasst haben, können sie die Interaktionen mit der Methode AdSelectionManager.reportInteraction()
an die zuvor registrierten erfolgreichen Buy-Side- und Sell-Side-Plattformen zurückmelden. So melden Sie ein Anzeigenereignis:
- Initialisieren Sie ein
AdSelectionManager
-Objekt. - Erstellen Sie ein
ReportInteractionRequest
-Objekt mit der Anzeigenauswahl-ID, dem Interaktionsschlüssel, den Interaktionsdaten und dem Ziel für die Berichterstellung. - Rufen Sie die asynchrone
reportInteraction()
-Methode mit demrequest
-Objekt und den relevanten ObjektenExecutor
undOutcomeReceiver
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. - Interaction Key: Ein vom Client definierter Stringschlüssel, der die gemeldete 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 an die Berichtsserver zurückgesendet werden sollen.
- Ziele für die Berichterstellung: Eine Bitmaske, die angibt, ob die Ereignisse dem Käufer, dem Verkäufer oder beiden gemeldet werden sollen. Diese Flags werden von der Plattform bereitgestellt und die endgültige Zielmaske kann mithilfe von bitweisen Vorgängen erstellt werden. Für Berichte an ein Ziel können Sie direkt das von der Plattform bereitgestellte Flag verwenden. Für Berichte an mehrere Ziele können Sie das bitweise ODER (
|
) verwenden, um Flag-Werte zu kombinieren.
Die asynchrone reportInteraction()
-Methode verwendet das Objekt OutcomeReceiver
, um das Ergebnis des API-Aufrufs zu signalisieren.
- Der Callback
onResult()
gibt an, dass der Aufruf der Berichtsinteraktion 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 ein
IllegalStateException
mit einer Beschreibung des Fehlers zurückgegeben. - Wenn der Aufruf von
reportInteraction()
für den Client gedrosselt wird, wird einLimitExceededException
zurückgegeben. - Wenn das Paket nicht zum Aufrufen der Privacy Preserving APIs registriert ist, wird ein
SecurityException()
zurückgegeben. - Wenn sich die App-Interaktionsberichte von der App unterscheidet, die
selectAds()
aufgerufen hat, wird einIllegalStateException
zurückgegeben.
- Wenn der Aufruf erfolgt, während die App im Hintergrund ausgeführt wird, wird ein
- Wenn der Nutzer der Aktivierung der Privacy Sandbox APIs nicht zugestimmt hat, schlägt der Aufruf im Hintergrund fehl.
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 erfolgreichen Plattform der Käuferseite bereitgestellt werden. Die Protected Audience API gleicht die Interaktionsschlüssel mit den URIs ab, die in JavaScript-Berichten deklariert wurden, und sendet für jede gemeldete Interaktion eine POST-Anfrage an jeden Endpunkt. Der Inhaltstyp der Anfrage ist Nur-Text, wobei der Text die Interaktionsdaten darstellen soll.
Best-Effort-Interaktionsbericht
Der reportInteraction()
ist so konzipiert, dass die Berichterstellung über HTTP POST bestmöglich durchgeführt werden kann.
Tägliches Hintergrundupdate
Wenn Sie eine benutzerdefinierte Zielgruppe erstellen, können Sie mit Ihrer App oder Ihrem SDK Metadaten für benutzerdefinierte Zielgruppen initialisieren. Außerdem können über die Plattform die folgenden Metadaten für benutzerdefinierte Zielgruppen täglich im Hintergrund aktualisiert werden.
- Signale für Gebote von Nutzern
- Trusted Bidding-Daten
AdData
Liste
Dabei werden Abfragen der URL für tägliche Updates verarbeitet, die in der benutzerdefinierten Zielgruppe definiert ist, und die URL gibt möglicherweise eine JSON-Antwort zurück.
- Die JSON-Antwort kann eines der unterstützten Metadatenfelder enthalten, die aktualisiert werden müssen.
- Jedes JSON-Feld wird unabhängig validiert. Der Client ignoriert alle falsch formatierten Felder, sodass das jeweilige Feld in der Antwort nicht aktualisiert wird.
- Eine leere HTTP-Antwort oder ein leeres JSON-Objekt „
{}
“ führt zu keinen Metadatenaktualisierungen. - Die Größe der Antwortnachricht muss auf 10 KB begrenzt sein.
- Alle URIs müssen HTTPS verwenden.
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 Workflow für die Anzeigenauswahl orchestriert die Ausführung des vom Käufer und vom Verkäufer bereitgestellten JavaScripts.
Vom Käufer bereitgestellter JavaScript-Code wird von der Gebotslogik-URL abgerufen, die in der benutzerdefinierten Zielgruppe angegeben ist. Der zurückgegebene JavaScript-Code sollte die folgenden Funktionen enthalten:
Vom Verkäufer bereitgestelltes JavaScript wird von der URL der Entscheidungslogik abgerufen, die im Parameter AdSelectionConfig
für die API zur Anzeigenauswahl angegeben ist. Der zurückgegebene JavaScript-Code sollte die folgenden Funktionen enthalten:
GeneriertBid()
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 Formatvar ad = { 'render_url': url, 'metadata': json_metadata };
auction_signals, per_buyer_signals
: JSON-Objekte, die im Auktionskonfigurationsobjekt angegeben sindcustom_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
undname
sind Strings aus den Properties mit demselben Namen der benutzerdefinierten Zielgruppe, die an der Anzeigenauswahl beteiligt istactivation_time
undexpiration_time
sind die Zeit der Aktivierung und der Ablauf der benutzerdefinierten Zielgruppe in Sekunden seit der Unixzeit.ca_user_bidding_signals
ist ein JSON-String, der bei der Erstellung im FelduserBiddingSignals
derCustomAudience
angegeben wurde.trusted_bidding_signals, contextual_signals
unduser_signals
sind JSON-Objekte. Sie werden als leere Objekte übergeben und in zukünftigen Versionen aufgefüllt. Ihr Format wird nicht von der Plattform durchgesetzt, sondern von der AdTech verwaltet.
Ergebnis:
ad
: die Anzeige, auf die sich das Gebot bezieht. Das Skript darf eine Kopie der Anzeige mit unterschiedlichen Metadaten zurückgeben. Die Eigenschaftrender_url
der Anzeige sollte unverändert bleiben.bid
: Gleitkommawert, der den Gebotswert für diese Anzeige darstelltstatus
: eine Ganzzahl, die Folgendes sein kann:0
: für eine erfolgreiche Ausführung1
: (oder ein Wert ungleich null), falls eines der Eingabesignale ungültig ist. Wenn von „Generate-Bid“ ein Wert ungleich null zurückgegeben wird, wird der Gebotsprozess 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
: siehegenerateBid
-Dokumentationbid
: der Gebotswert für die Anzeigead_selection_config
: ein JSON-Objekt, das den ParameterAdSelectionConfig
derselectAds
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-ParametersellerSignals
AdSelectionConfig
gelesen werdentrusted_scoring_signal
: Aus dem FeldadSelectionSignals
im API-ParameterAdSelectionConfig
contextual_signals, user_signals
: JSON-Objekte. Sie werden derzeit als leere Objekte übergeben und in zukünftigen Releases aufgefüllt. Ihr Format wird nicht von der Plattform erzwungen, sondern von der AdTech verwaltet.per_buyer_signals
: JSON-Objekt, das aus derperBuyerSignal
-Zuordnung imAdSelectionConfig
-API-Parameter gelesen wird. Es wird als Schlüssel des aktuellen Käufers der benutzerdefinierten Zielgruppe verwendet. Das Feld ist leer, wenn die Karte keinen Eintrag für den angegebenen Käufer enthält.
Ausgabe:
score
: Gleitkommawert, der den Wert für diese Anzeige darstelltstatus
: eine Ganzzahl, die Folgendes sein kann:- 0: für eine erfolgreiche Ausführung
- 1: für den Fall, dass
customAudienceSignals
ungültig sind - 2: wenn
AdSelectionConfig
ungültig ist - 3: falls eines der anderen Signale ungültig ist
- Jeder Wert ungleich null führt zum Fehlschlagen des Prozesses. Der Wert bestimmt die Art 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
: JSON-Objekte, die im Auktionskonfigurationsobjekt angegeben sind
Ausgabe:
status
:0
für Erfolg, nicht null für Fehlerresult
: 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 zuscoreAds
render_url
: die Rendering-URL der erfolgreichen Anzeigebid
: das für die erfolgreiche Anzeige angebotene Gebotcontextual_signals
: siehe Dokumentation zugenerateBid
Ausgabe:
status: 0
für Erfolg und ungleich null für Fehlerresults
: ein JSON-Objekt, das Folgendes enthält:signals_for_buyer
: ein JSON-Objekt, das an die FunktionreportWin
übergeben wirdreporting_url
: eine URL, die von der Plattform verwendet wird, um den Käufer über die Impression zu informieren
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
: Weitere Informationen finden Sie in der Dokumentation zuscoreAd
.signals_for_buyer
: ein vonreportResult
zurückgegebenes JSON-Objektcontextual_signals, custom_audience_signals
: Weitere Informationen finden Sie in der Dokumentation zugenerateBid
.
Ausgabe:
status: 0
für Erfolg und ungleich null für Fehlerresults
: ein JSON-Objekt, das Folgendes enthält:reporting_url
: eine URL, die von der Plattform verwendet wird, um den Verkäufer über die Impression zu informieren
registerAdBeacon()
function registerAdBeacon(
interaction_key,
reporting_uri
)
Eingabeparameter:
interaction_key
: Ein String, der das Ereignis darstellt. Sie wird von der Plattform später verwendet, wenn Ereignisinteraktionen gemeldet werden, um diereporting_uri
zu ermitteln, die benachrichtigt werden sollen. Dieser Schlüssel muss mit den Angaben des Käufers oder Verkäufers und den vom Verkäufer gemeldeten Daten übereinstimmen.reporting_uri
: URI zum Empfangen von Ereignisberichten. Sie sollte für den gemeldeten Ereignistyp spezifisch sein. Sie muss eine POST-Anfrage akzeptieren, um alle zusammen mit dem Ereignis gemeldeten Daten zu verarbeiten.
Vordefinierte URIs für die Anzeigenauswahl
Mit vordefinierten URIs können Anzeigentechnologie-Anbieter JavaScript-Funktionen für die Entscheidungslogik zur Anzeigenauswahl in den Klassen AdSelectionConfig
und AdSelectionFromOutcomesConfig
festlegen. Bei vordefinierten URIs sind keine Netzwerkaufrufe zum Herunterladen des entsprechenden JavaScript-Codes erforderlich. AdTech-Unternehmen können vordefinierte URIs verwenden, ohne eine registrierte Domain zum Hosten des JavaScripts 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 mithilfe der Informationen aus diesem URI in der Laufzeit bereit.
Ein IllegalArgumentException
wird in folgenden Fällen ausgelöst:
- Einer der erforderlichen Parameter ist im URI nicht vorhanden
- Der URI enthält unbekannte Parameter
Unterstützte Anwendungsfälle und Namen für vordefinierte URIs
Anwendungsfall 1: Anzeigenauswahl
Vordefinierte URIs unter dem Anwendungsfall ad-selection
werden im selectAds(AdSelectionConfig)
-Ablauf unterstützt.
Vordefinierter URI-Name: highest-bid-wins
Dieser vordefinierte URI stellt JavaScript-Code bereit, mit dem nach der Gebotsabgabe die Anzeige mit dem höchsten Gebot ausgewählt wird. Es bietet auch eine einfache Berichtsfunktion, mit der render_uri
und bid
des Gewinners gemeldet werden können.
Erforderliche Parameter
reportingUrl
: Das ist die grundlegende Berichts-URL, die mit dem render_uri
und dem bid
der erfolgreichen Anzeige parametrisiert wird:
<reportingUrl>?render_uri=<renderUriOfWinnigAd>&bid=<bidOfWinningAd>
Nutzung
Wenn die grundlegende Berichts-URL https://www.ssp.com/reporting
ist, lautet der vordefinierte URI:
`ad-selection-prebuilt://ad-selection/highest-bid-wins/?reportingUrl=https://www.ssp.com/reporting`
Anwendungsfall 2: Anzeigenauswahl-aus-Ergebnissen
Vordefinierte URIs im Anwendungsfall ad-selection-from-outcomes
unterstützen den Workflow selectAds(AdSelectionFromOutcomesConfig)
.
Vordefinierter URI-Name: waterfall-mediation-truncation
Der vordefinierte URI waterfall-mediation-truncation
stellt JavaScript bereit, das eine Kürzungslogik für die abfolgebasierte Vermittlung implementiert. Hierbei wird eine eigene Anzeige zurückgegeben, wenn bid
größer oder gleich bid floor
ist. Andernfalls wird null
zurückgegeben.
Erforderliche Parameter
bidFloor
: Der Schlüssel des im getSelectionSignals()
übergebenen Mindestpreises, der mit der Anzeige des Mediation SDK verglichen wird.
Nutzung
Wenn die Signale für die Anzeigenauswahl so aussehen: {"bid_floor": 10}
, sieht der vordefinierte URI aus:
`ad-selection-prebuilt://ad-selection-from-outcomes/waterfall-mediation-truncation/?bidFloor=bid_floor`
Testen
Um Ihnen den Einstieg in die Protected Audience API zu erleichtern, haben wir Beispiel-Apps in Kotlin und Java erstellt, die Sie auf GitHub finden.
Voraussetzungen
Für die Protected Audience API ist JavaScript für die Anzeigenauswahl und für Berichte zu Impressionen erforderlich. Es gibt zwei Methoden, um diesen JavaScript-Code in einer Testumgebung bereitzustellen:
- Einen Server mit den erforderlichen HTTPS-Endpunkten ausführen, der das JavaScript zurückgibt
- Remote-Abruf durch Bereitstellen des erforderlichen Codes aus einer lokalen Quelle überschreiben
Bei beiden Ansätzen muss ein HTTPS-Endpunkt eingerichtet werden, um Impressionsberichte zu verarbeiten.
HTTPS-Endpunkte
Wenn Sie die Anzeigenauswahl und Berichte zu Impressionen testen möchten, müssen Sie sieben HTTPS-Endpunkte einrichten, auf die das Testgerät oder der Emulator zugreifen kann:
- Käuferendpunkt, der den JavaScript-Code für die Gebotslogik bereitstellt.
- Ein Endpunkt, der die Gebotssignale bereitstellt.
- Verkäuferendpunkt, der das JavaScript für die Entscheidungslogik bereitstellt.
- Ein Endpunkt, der Bewertungssignale bereitstellt.
- Endpunkt für Berichte zu Impressionen des erfolgreichen Käufers.
- Endpunkt für Berichte zu Impressionen für Verkäufer
- Ein Endpunkt, über den die täglichen Aktualisierungen für eine benutzerdefinierte Zielgruppe bereitgestellt werden.
Der Einfachheit halber enthält das GitHub-Repository grundlegenden JavaScript-Code zu Testzwecken. Sie umfasst auch OpenAPI-Dienstdefinitionen, die auf einer unterstützten Simulations- oder Mikrodienstplattform bereitgestellt werden können. Weitere Informationen finden Sie in der Readme-Datei für das Projekt.
Remote-Abruf von JavaScript überschreiben
Diese Funktion ist für End-to-End-Tests vorgesehen. Zum Überschreiben des Remote-Abrufs muss Ihre App im Debug-Modus mit aktivierten Entwickleroptionen ausgeführt werden.
Um den Debug-Modus für Ihre App zu aktivieren, fügen Sie dem Anwendungsattribut in der Datei "AndroidManifest.xml" die folgende Zeile hinzu:
<application
android:debuggable="true">
Ein Beispiel für die Verwendung dieser Überschreibungen finden Sie in der Protected Audience API-Beispiel-App auf GitHub.
Sie müssen Ihren eigenen benutzerdefinierten JavaScript-Code hinzufügen, um Routinen für die Anzeigenauswahl wie Gebote, Bewertungsentscheidungen und Berichte zu verarbeiten. Im GitHub-Repository finden Sie grundlegende JavaScript-Codebeispiele, die alle erforderlichen Anfragen verarbeiten. Die Protected Audience API-Beispielanwendung zeigt, wie Code aus dieser Datei gelesen und für die Verwendung als Überschreibung vorbereitet wird.
Es ist möglich, den JavaScript-Abruf auf Verkäuferseite und Käuferseite unabhängig voneinander zu überschreiben. Sie benötigen jedoch einen HTTPS-Endpunkt, um JavaScript-Code bereitzustellen, für den Sie keine Überschreibungen bereitstellen. In der Readme-Datei finden Sie Informationen zum Einrichten eines Servers, der diese Fälle verarbeitet.
Der JavaScript-Abruf kann nur für benutzerdefinierte Zielgruppen überschrieben werden, die zu Ihrem Paket gehören.
JavaScript für Verkäufer überschreiben
So richten Sie eine Überschreibung des Verkaufsseitens JavaScript ein, wie im folgenden Codebeispiel veranschaulicht:
- Initialisieren Sie ein
AdSelectionManager
-Objekt. - Rufen Sie einen Verweis auf
TestAdSelectionManager
aus demAdSelectionManager
-Objekt ab. - Erstellen Sie ein
AdSelectionConfig
-Objekt. - Erstellen Sie ein
AddAdSelectionOverrideRequest
mit demAdSelectionConfig
-Objekt und einemString
, das den JavaScript-Code darstellt, den Sie als Überschreibung verwenden möchten. - Rufen Sie die asynchrone
overrideAdSelectionConfigRemoteInfo()
-Methode mit demAddAdSelectionOverrideRequest
-Objekt und den relevantenExecutor
- undOutcomeReceiver
-Objekten auf.
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);
Weitere Informationen dazu, was die einzelnen Felder in AdSelectionConfig
bedeuten, finden Sie im Abschnitt Anzeigenauswahl ausführen. Der Hauptunterschied besteht darin, dass die decisionLogicUrl auf einen Platzhalterwert gesetzt werden kann, da sie ignoriert wird.
Damit das bei der Anzeigenauswahl verwendete JavaScript überschrieben werden kann, muss decisionLogicJs
die korrekten Funktionssignaturen der Verkäufer enthalten.
Ein Beispiel zum Lesen einer JavaScript-Datei als String finden Sie in der Protected Audience API-Beispiel-App auf GitHub.
Bei der asynchronen overrideAdSelectionConfigRemoteInfo()
-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.
Für zukünftige Aufrufe von selectAds()
wird die Entscheidungs- und Berichtslogik verwendet, die Sie als Überschreibung übergeben haben.
Der Callback onError()
steht für zwei mögliche Bedingungen:
- Wenn das Überschreiben mit ungültigen Argumenten versucht wird, gibt
AdServiceException
einIllegalArgumentException
als Ursache an. - Wenn das Überschreiben mit einer App versucht wird, die nicht im Debug-Modus mit aktivierten Entwickleroptionen ausgeführt wird, gibt
AdServiceException
IllegalStateException
als Ursache an.
Überschreibungen auf Verkäuferseite zurücksetzen
In diesem Abschnitt wird davon ausgegangen, dass Sie das JavaScript auf Verkäuferseite überschrieben haben und einen Verweis auf die im vorherigen Abschnitt verwendeten TestAdSelectionManager
und AdSelectionConfig
haben.
So setzen Sie die Überschreibungen für alle AdSelectionConfigs
zurück:
- Rufen Sie die asynchrone
resetAllAdSelectionConfigRemoteOverrides()
-Methode mit dem entsprechendenOutcomeReceiver
-Objekt auf.
Kotlin
// Resets overrides for all AdSelectionConfigs
testAadSelectionManager.resetAllAdSelectionConfigRemoteOverrides(
outComeReceiver)
Java
// Resets overrides for all AdSelectionConfigs
testAdSelectionManager.resetAllAdSelectionConfigRemoteOverrides(
outComeReceiver);
Nachdem Sie die Überschreibungen auf Verkäuferseite zurückgesetzt haben, wird für selectAds()
-Aufrufe die im AdSelectionConfig
gespeicherte decisionLogicUrl verwendet, um den erforderlichen JavaScript-Code abzurufen.
Wenn der Aufruf von resetAllAdSelectionConfigRemoteOverrides()
fehlschlägt, liefert der OutComeReceiver.onError()
-Callback ein AdServiceException
.
Wenn das Entfernen von Überschreibungen mit einer App versucht wird, die nicht im Debug-Modus ausgeführt wird und die Entwickleroptionen aktiviert sind, gibt AdServiceException
IllegalStateException
als Ursache an.
JavaScript auf Käuferseite überschreiben
- Folgen Sie der Anleitung zum Verknüpfen einer benutzerdefinierten Zielgruppe.
- Erstellen Sie eine
AddCustomAudienceOverrideRequest
mit dem Käufer und dem Namen der benutzerdefinierten Zielgruppe, die Sie überschreiben möchten (zusätzlich zur Gebotslogik und den Daten, die Sie als Überschreibung verwenden möchten). - Rufen Sie die asynchrone
overrideCustomAudienceRemoteInfo()
-Methode mit demAddCustomAudienceOverrideRequest
-Objekt und den relevantenExecutor
- undOutcomeReceiver
-Objekten auf.
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 mit denen identisch, die zum Erstellen der benutzerdefinierten Zielgruppe verwendet wurden. Weitere Informationen zu diesen Feldern
Außerdem können Sie zwei zusätzliche Parameter angeben:
biddingLogicJs
: JavaScript-Code, der die Käuferlogik 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. 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.
Nachfolgende Aufrufe von selectAds()
verwenden die Gebots- und Berichtslogik, die Sie bei der Überschreibung übergeben haben.
Der Callback onError()
steht für zwei mögliche Bedingungen.
- Wenn das Überschreiben mit ungültigen Argumenten versucht wird, gibt
AdServiceException
einIllegalArgumentException
als Ursache an. - Wenn das Überschreiben mit einer App versucht wird, die nicht im Debug-Modus mit aktivierten Entwickleroptionen ausgeführt wird, gibt
AdServiceException
IllegalStateException
als Ursache an.
Überschreibungen auf Käuferseite zurücksetzen
In diesem Abschnitt wird davon ausgegangen, dass Sie das JavaScript auf Käuferseite überschrieben haben und einen Verweis auf die im vorherigen Abschnitt verwendete TestCustomAudienceManager
haben.
So setzen Sie Überschreibungen für alle benutzerdefinierten Zielgruppen zurück:
- Rufen Sie die asynchrone
resetAllCustomAudienceOverrides()
-Methode mit den relevanten ObjektenExecutor
undOutcomeReceiver
auf.
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, verwenden nachfolgende Aufrufe von selectAds()
den im CustomAudience
gespeicherten biddingLogicUrl
und trustedBiddingData
, um den erforderlichen JavaScript-Code abzurufen.
Wenn der Aufruf von resetCustomAudienceRemoteInfoOverride()
fehlschlägt, liefert der OutComeReceiver.onError()
-Callback ein AdServiceException
.
Wenn das Entfernen von Überschreibungen mit einer App versucht wird, die nicht im Debug-Modus ausgeführt wird und die Entwickleroptionen aktiviert sind, wird IllegalStateException
als Ursache in AdServiceException
angegeben.
Reporting-Server einrichten
Wenn Sie Remote-Abrufüberschreibungen verwenden, müssen Sie trotzdem einen Server einrichten, den Ihr Gerät oder Emulator erreichen kann, um auf Berichtsereignisse zu reagieren. Ein einfacher Endpunkt, der 200 zurückgibt, ist zum Testen ausreichend. Das GitHub-Repository enthält OpenAPI-Dienstdefinitionen, die auf einer unterstützten Mock- oder Mikrodienstplattform bereitgestellt werden können. Weitere Informationen finden Sie in der Readme-Datei für das Projekt.
Suchen Sie bei den OpenAPI-Definitionen nach der Datei „reporting-server.json“.
Diese Datei enthält einen einfachen Endpunkt, der 200 zurückgibt, was einen HTTP-Antwortcode darstellt. Dieser Endpunkt wird während des selectAds()
-Vorgangs verwendet und signalisiert der Protected Audience API, dass die Berichte zu Impressionen erfolgreich abgeschlossen wurden.
Zu testende Funktionalität
- Sie können üben, wie Sie einer Zielgruppe beitreten oder sie verlassen und eine benutzerdefinierte Zielgruppe basierend auf früheren Nutzeraktionen einrichten.
- Starten Sie die Anzeigenauswahl auf dem Gerät durch remote gehostete JavaScripts.
- Sie können beobachten, wie sich die Verknüpfung einer App mit benutzerdefinierten Zielgruppeneinstellungen auf die Ergebnisse der Anzeigenauswahl auswirken kann.
- Impressionsberichte nach Anzeigenauswahl ausführen.
Beschränkungen
In der folgenden Tabelle sind die Einschränkungen für die Verarbeitung durch die Protected Audience API aufgeführt. Die vorgestellten Limits können sich je nach Feedback ändern. Informationen zu aktiven Funktionen finden Sie in den Versionshinweisen.
Komponente | Beschreibung des Limits | Limitwert |
---|---|---|
Benutzerdefinierte Zielgruppe | Maximale Anzahl von Anzeigen pro Zertifizierungsstelle | 100 |
Maximale Anzahl Zertifizierungsstellen pro Anwendung | 1.000 | |
Maximale Anzahl von Apps, die eine Zertifizierungsstelle erstellen können | 1.000 | |
Maximale Verzögerung der Aktivierungszeit einer Zertifizierungsstelle ab dem Erstellungszeitpunkt | 60 Tage | |
Maximale Ablaufzeit einer Zertifizierungsstelle ab ihrer Aktivierungszeit | 60 Tage | |
Maximale Anzahl von Zertifizierungsstellen auf Gerät | 4.000 | |
Maximale Größe des Zertifizierungsstellennamens | 200 Byte | |
Maximale Größe des täglichen Abruf-URI | 400 Byte | |
Maximale Größe des Gebotslogik-URI | 400 Byte | |
Maximale Größe von Daten zu vertrauenswürdigen Geboten | 10 KB | |
Maximale Größe der Gebotssignale 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 | |
Hintergrundabruf für CA | Zeitüberschreitung beim Verbindungsaufbau | 5 Sekunden |
HTTP-Lesezeitlimit | 30 Sekunden | |
Maximale Downloadgröße | 10 KB | |
Maximale Dauer einer Abrufiteration | 5 Minuten | |
Maximale Anzahl von Zertifizierungsstellen, die pro Job aktualisiert werden | 1.000 | |
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 | |
Zeitlimit für Erstverbindung | 5 Sekunden | |
Zeitüberschreitung beim Lesen der Verbindung | 5 Sekunden | |
Maximale Ausführungszeit von insgesamt AdSelection |
10 Sekunden | |
Maximale Ausführungszeit von Geboten 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/pro Käufer-Signale | Noch offen | |
Maximale Größe von Verkäufer-/Käufer-Skripts | Noch offen | |
Maximale Anrufrate für selectAds |
1 Abfragen pro Sekunde | |
Berichte zu Impressionen | Mindestzeit, bevor die Anzeigenauswahl aus Persistenz entfernt wird | 24 Stunden |
Maximale Anzahl der ausgewählten Speicheranzeigen | Noch offen | |
Maximale Größe der Ausgabe-URL für Berichte | Noch offen | |
Maximale Zeit für Berichte zu Impressionen | Noch offen | |
Maximale Anzahl der Wiederholungsversuche 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 | |
Berichte zu Ereignissen | 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 von allen AdData in einer einzigen Zertifizierungsstelle für kontextbezogene |
URLs | Maximale Länge eines URL-Strings, der als Eingabe verwendet wird | Noch offen |
JavaScript | Maximale Ausführungszeit | 1 Sekunde für Gebote und Bewertungen für Berichte zu Impressionen |
Maximal verwendeter Arbeitsspeicher | 10 MB |
Fehler und Probleme melden
Dein Feedback ist wichtig für die Privacy Sandbox für Android. Teilen Sie uns bitte mit, wenn Sie Probleme finden oder Ideen zur Verbesserung der Privacy Sandbox für Android haben.
Persönliche Empfehlungen
- Hinweis: Der Linktext wird angezeigt, wenn JavaScript deaktiviert ist.
- Targeting auf benutzerdefinierte Zielgruppen mit der Protected Audience API unterstützen
- Versionshinweise
- Protected Audience: Integrationsanleitung