Mentre leggi Privacy Sandbox su Android documentazione, utilizza il pulsante Anteprima per sviluppatori o Beta per selezionare la versione del programma in uso, le istruzioni possono variare.
L'API Protected Audience su Android (precedentemente nota come FLEDGE) include il parametro l'API Custom Audience e l'API Ad Selection. Piattaforme e inserzionisti di tecnologia pubblicitaria puoi usare queste API per pubblicare annunci personalizzati in base alle precedenti interazioni in-app che limita la condivisione di identificatori tra le app e limita la condivisione dell'app di un utente informazioni sulle interazioni con terze parti.
L'API Custom Audience è incentrata sul "segmento di pubblico personalizzato" , che rappresenta un gruppo di utenti con intenzioni comuni. Un L'inserzionista può registrare un utente con un pubblico personalizzato e associare annunci pertinenti con essa. Queste informazioni vengono memorizzate localmente e possono essere utilizzate per informare l'inserzionista offerte, filtri degli annunci e rendering degli annunci.
L'API Ad Selection fornisce un framework che consente a più sviluppatori di eseguire un'asta localmente per un pubblico personalizzato. A questo scopo, il sistema prende in considerazione gli annunci pertinenti associati al segmento di pubblico personalizzato e ha un buon rendimento un'ulteriore elaborazione sugli annunci che una piattaforma di ad tech restituisce sul dispositivo.
Le piattaforme di ad tech possono integrare queste API per implementare il remarketing che tutela la privacy degli utenti. Supporto per casi d'uso aggiuntivi, inclusa l'installazione di app sono pianificati per le versioni future. Scopri di più su Protected Audience su Android nella proposta di progettazione.
Questa guida descrive come utilizzare l'API Protected Audience su Android per procedi nel seguente modo:
- Gestire i segmenti di pubblico personalizzati
- Configurare ed eseguire la selezione degli annunci su un dispositivo
- Registrare le impressioni degli annunci
Prima di iniziare
Prima di iniziare, completa i seguenti passaggi:
- Configura il tuo ambiente di sviluppo per Privacy Sandbox su Android.
- Installa un'immagine di sistema su un dispositivo supportato o configura un un emulatore che supporta Privacy Sandbox su Android.
In un terminale, abilita l'accesso all'API Protected Audience (disattivata) per impostazione predefinita) con il seguente comando adb.
adb shell device_config put adservices ppapi_app_allow_list \"*\"
Includi un'autorizzazione
ACCESS_ADSERVICES_CUSTOM_AUDIENCE
nella tua app manifest:<uses-permission android:name="android.permission.ACCESS_ADSERVICES_CUSTOM_AUDIENCE" />
Fare riferimento a una configurazione di servizi pubblicitari nell'elemento
<application>
di il tuo manifest:<property android:name="android.adservices.AD_SERVICES_CONFIG" android:resource="@xml/ad_services_config" />
Specifica la risorsa XML dei servizi pubblicitari a cui viene fatto riferimento nel file manifest, ad esempio
res/xml/ad_services_config.xml
. Scopri di più sulle autorizzazioni per i servizi pubblicitari e SDK Access Control.<ad-services-config> <custom-audiences allowAllToAccess="true" /> </ad-services-config>
Per impostazione predefinita, l'API Ad Selection applica i limiti sulla quantità massima di memoria utilizzata dai report su aste o impressioni che lo script può allocare. La funzionalità di limitazione della memoria richiede la versione WebView 105.0.5195.58 o successivo. La piattaforma applica un controllo della versione e chiama le API
selectAds
ereportImpression
hanno esito negativo se non è soddisfatto. Esistono due opzioni per l'impostazione:Opzione 1: esegui il comando adb riportato di seguito per disattivare questo controllo:
adb device_config put fledge_js_isolate_enforce_max_heap_size false
Opzione 2: installa WebView beta dal Google Play Store. Deve uguale o superiore alla versione dichiarata in precedenza.
Entrare a far parte di un segmento di pubblico personalizzato
Un segmento di pubblico personalizzato rappresenta un gruppo di utenti con intenzioni comuni o interessi deciso dall'app dell'inserzionista. Un'app o un SDK può utilizzare un'istanza per indicare un determinato segmento di pubblico, ad esempio qualcuno che ha lasciato alcuni elementi. in un carrello degli acquisti. Per creare o unirti a un segmento di pubblico personalizzato in modo asincrono, procedi nel seguente modo: seguenti:
- Inizializza l'oggetto
CustomAudienceManager
. - Crea un oggetto
CustomAudience
specificando parametri chiave come pacchetto dell'acquirente e un nome pertinente. Quindi, inizializzaJoinCustomAudienceRequest
con l'oggettoCustomAudience
. - Chiama l'
joinCustomAudience()
asincrono con OggettoJoinCustomAudienceRequest
eExecutor
eOutcomeReceiver
di oggetti.
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);
La combinazione dei seguenti parametri identifica in modo univoco
Oggetto CustomAudience
su un dispositivo:
owner
: nome pacchetto dell'app del proprietario. È implicitamente impostato sul nome del pacchetto dell'app del chiamante.buyer
: identificatore della rete pubblicitaria dell'acquirente che gestisce gli annunci per questa rete pubblicitaria personalizzata pubblico.name
: un nome o un identificatore arbitrario per il segmento di pubblico personalizzato.
Chiamata ripetuta a joinCustomAudience()
con un'istanza diversa di
CustomAudience
aggiorna tutte le CustomAudience
esistenti con
corrispondenti ai parametri owner, buyer
e name
. Per contribuire a preservare la privacy,
il risultato dell'API non fa distinzione tra "creazione" e "update".
Inoltre, è necessario creare la CustomAudience
con questi obbligatori
parametri:
- URL di aggiornamento giornaliero: un URL HTTPS sottoposto a query giornaliere in background su aggiornare gli indicatori di offerta per gli utenti di un segmento di pubblico personalizzato, i dati sulle offerte attendibili e eseguire il rendering di URL e metadati per gli annunci.
- URL logica di offerta: un URL HTTPS a cui è stato chiesto di eseguire una query durante la selezione dell'annuncio per recuperare un dalla logica di offerta JavaScript dell'acquirente. Vedi le firme delle funzioni richieste in questo codice JavaScript.
- ID rendering annuncio: un ID arbitrario impostato dalla tecnologia pubblicitaria dell'acquirente. Si tratta di un ottimizzazione per generare il payload per B&A.
I parametri facoltativi per un oggetto CustomAudience
possono includere:
- Ora di attivazione: un segmento di pubblico personalizzato può partecipare solo alla selezione degli annunci. e aggiornamenti giornalieri dopo l'attivazione. Può essere utile per coinvolgere ad esempio gli utenti non più attivi di un'app.
- Data di scadenza: un periodo di tempo futuro trascorso il quale il segmento di pubblico personalizzato è rimosso dal dispositivo.
- Indicatori di offerta per l'utente: una stringa JSON contenente indicatori relativi agli utenti, ad esempio la le impostazioni internazionali preferite dell'utente utilizzate dal codice JavaScript della logica di offerta dell'acquirente. per generare offerte durante il processo di selezione degli annunci. Questo formato consente le piattaforme riutilizzano il codice su più piattaforme e ne facilita l'utilizzo in JavaScript funzioni.
- Dati relativi a Offerte attendibili. Un URL HTTPS e un elenco di stringhe utilizzate durante processo di selezione degli annunci che recupera gli indicatori di offerta da un valore-chiave attendibile completamente gestito di Google Cloud.
- Annunci: un elenco di oggetti
AdData
corrispondenti agli annunci che partecipano alla selezione degli annunci. Ogni oggettoAdData
è costituito da:- URL di rendering: un URL HTTPS a cui viene richiesto di visualizzare l'annuncio finale.
- Metadati: un oggetto JSON serializzato come stringa contenente informazioni per essere consumati dalla logica di offerta dell'acquirente durante il processo di selezione degli annunci.
- Filtri annunci: un corso che contiene tutte le informazioni necessarie sull'app installare il filtro degli annunci e la quota limite durante la selezione degli annunci.
Di seguito è riportato un esempio di creazione di un'istanza di oggetto CustomAudience
:
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();
Gestire i risultati di joinCustomAudience()
Il metodo joinCustomAudience()
asincrono utilizza OutcomeReceiver
per segnalare il risultato della chiamata API.
- Il callback
onResult()
indica che il segmento di pubblico personalizzato è riuscito creato o aggiornato. - Il callback
onError()
rappresenta due condizioni possibili.- Se
JoinCustomAudienceRequest
è inizializzato con un valore non valido argomenti,AdServicesException
indica unIllegalArgumentException
come causa. - A tutti gli altri errori viene assegnato un valore
AdServicesException
con unIllegalStateException
come causa.
- Se
Ecco un esempio di come gestire il risultato di 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);
}
};
Uscire da un segmento di pubblico personalizzato
Se l'utente non soddisfa più i criteri aziendali per un determinato personalizzato
pubblico, un'app o un SDK può chiamare leaveCustomAudience()
per rimuovere l'elemento
pubblico dal dispositivo. Per rimuovere una CustomAudience
in base alla sua
, procedi nel seguente modo:
- Inizializza l'oggetto
CustomAudienceManager
. - Inizializza la
LeaveCustomAudienceRequest
con ilbuyer
ename
. Per saperne di più su questi campi di immissione, consulta "Unisciti a un segmento di pubblico personalizzato". - Chiama il metodo
leaveCustomAudience()
asincrono con OggettoLeaveCustomAudienceRequest
eExecutor
eOutcomeReceiver
di oggetti.
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);
Come per la chiamata di joinCustomAudience()
, gli indicatori OutcomeReceiver
al termine di una chiamata API. Per proteggere la privacy, il risultato di un errore
distinguere tra errori interni e argomenti non validi. onResult()
il callback viene chiamato al termine della chiamata API, indipendentemente dal fatto che
segmento di pubblico personalizzato rimosso.
Pubblica selezione annunci
Per utilizzare l'API Protected Audience per selezionare gli annunci, chiama il metodo selectAds()
:
- Inizializza un oggetto
AdSelectionManager
. - Crea un oggetto
AdSelectionConfig
. - Chiama il metodo
selectAds()
asincrono con OggettoAdSelectionConfig
eExecutor
eOutcomeReceiver
di oggetti.
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);
Il metodo selectAds()
richiede un input AdSelectionConfig
, dove
devi specificare i seguenti parametri obbligatori:
- Venditore: l'identificatore della rete pubblicitaria del venditore che avvia la selezione degli annunci.
- URL logica decisionale: un URL HTTPS che è stato oggetto di una query per ottenere l'URL della rete pubblicitaria del venditore
della logica JavaScript.
- URL HTTPS: viene eseguito una query per ottenere la logica JavaScript della rete pubblicitaria del venditore. Vedi le firme delle funzioni richieste.
- URI predefinito: segue il formato di selezione degli annunci di FLEDGE.
Viene restituito il valore
IllegalArgumentException
se un formato non è supportato o è in un formato non supportato l'URI predefinito viene passato.
- Acquirenti di segmenti di pubblico personalizzati: un elenco completo di identificatori per le reti pubblicitarie degli acquirenti
a cui il venditore ha consentito di partecipare al processo di selezione degli annunci.
Questi identificatori dell'acquirente corrispondono a
CustomAudience.getBuyer()
di segmenti di pubblico personalizzati partecipanti.
I seguenti parametri possono essere facoltativamente specificati per annunci più personalizzati selezione:
- Indicatori di selezione degli annunci: un oggetto JSON, serializzato come stringa, contenente
indicatori da utilizzare per la logica di offerta dell'acquirente recuperati da JavaScript
CustomAudience.getBiddingLogicUrl()
. - Indicatori del venditore: un oggetto JSON, serializzato come stringa, contenente indicatori.
consumata dalla logica decisionale JavaScript recuperata dal venditore
AdSelectionConfig.getDecisionLogicUrl()
. - Indicatori per acquirente: una mappa di oggetti JSON, serializzati come stringhe.
che contengono indicatori che possono essere consumati da specifici acquirenti JavaScript della logica di offerta
recuperate da
CustomAudience.getBiddingLogicUrl()
, identificate da campi relativi agli acquirenti dei segmenti di pubblico personalizzati partecipanti. - Annunci contestuali: una raccolta di candidati per gli annunci raccolti direttamente dagli acquirenti durante un'asta che si verifica al di fuori di Protected Audience in un'asta.
Dopo aver selezionato un annuncio, i risultati, le offerte e gli indicatori vengono mantenuti internamente
per i report. Il callback OutcomeReceiver.onResult()
restituisce un
AdSelectionOutcome
che contiene:
- Un URL di rendering per l'annuncio vincente, ottenuto da
AdData.getRenderUrl()
. - Un ID selezione annunci univoco per l'utente del dispositivo. Questo ID viene utilizzato per i report l'impressione dell'annuncio.
Se la selezione dell'annuncio non può essere completata correttamente per motivi quali
argomenti non validi, timeout o un consumo eccessivo di risorse,
La richiamata OutcomeReceiver.onError()
produce un AdServicesException
con i seguenti comportamenti:
- Se la selezione dell'annuncio viene avviata con argomenti non validi,
AdServicesException
indicaIllegalArgumentException
come causa. - A tutti gli altri errori viene assegnato un valore
AdServicesException
con unIllegalStateException
come causa.
Annunci contestuali
Protected Audience può incorporare annunci contestuali in un'asta protetta.
Gli annunci contestuali devono essere selezionati sul server ad tech e restituiti al
dispositivo al di fuori delle API Protected Audience. Gli annunci contestuali possono quindi essere
nell'asta utilizzando AdSelectionConfig
; a questo punto utilizzano
Uguale agli annunci sui dispositivi, inclusa l'idoneità al filtro degli annunci per esclusione. Una volta
L'asta Protected Audience è stata completata, devi richiamare
reportImpression()
. In questo modo viene chiamato reportWin()
nell'annuncio contestuale vincente, in
lo stesso pattern dei report sulle impressioni, per ricevere l'annuncio vincente su
dispositivo. Ciascun annuncio contestuale richiede un acquirente, un'offerta, un link alla logica di report,
l'URL di rendering e i metadati degli annunci.
Per implementare gli annunci contestuali nell'app, l'app target deve creare una
Oggetto 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();
L'oggetto ContextualAds
risultante può quindi essere passato durante la creazione
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);
Filtro degli annunci per l'installazione di app
Il filtro degli annunci per l'installazione di app ti permette di filtrare gli annunci di installazione per le app. già installati su un dispositivo.
Il primo passaggio di questo processo consiste nel definire quali inserzionisti possono per filtrare i dati in base al pacchetto installato. Questa operazione deve essere eseguita nell'app che vuoi scegliere come target di un annuncio.
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);
}
});
Quando viene eseguito il codice precedente, gli inserzionisti trasmessi sono in grado di ed escludere le app installate da te specificate durante la generazione delle offerte. Se devi rimuovere un inserzionista dall'accesso all'installazione di questa app , esegui nuovamente questo codice dopo aver rimosso le informazioni sull'inserzionista.
Il passaggio successivo consiste nel configurare il filtro degli annunci all'interno dell'app del publisher. La festa
pubblica l'annuncio all'interno dell'app del publisher (molto probabilmente si tratta di un SDK Supply-Side)
deve inizializzare l'oggetto AdFilters
con informazioni su quali annunci
relative alle app da escludere:
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();
I publisher lato domanda possono anche impostare un AdFilter
per gli annunci presenti all'interno di
segmenti di pubblico personalizzati.
AdFilters
può anche essere trasmesso nel momento di creare un'istanza di un nuovo AdData
:
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();
Filtro sulla quota limite
Il filtro della quota limite consente ai tecnici pubblicitari di limitare il numero di volte in cui un annuncio viene come mostrato nell'immagine. Il filtro della quota limite riduce la sovraesposizione degli annunci e ottimizza la selezione degli annunci per una determinata campagna pubblicitaria.
Un filtro per la quota limite ha due componenti principali: il tipo di evento dell'annuncio e la chiave del contatore annunci. I tipi di eventi dell'annuncio che possono essere utilizzati sono i seguenti:
- Vittoria (disponibile a breve): un evento con vincita indica che l'annuncio ha vinto un'asta. Gli eventi vittoria vengono aggiornati automaticamente dall'API Protected Audience e non possono essere chiamato direttamente dallo sviluppatore. I dati relativi alle vincite sono visibili solo agli annunci all'interno di un un determinato segmento di pubblico personalizzato.
- Impressione: separata da
reportImpression
, un chiamante sul dispositivo (SSP o MMP) utilizzaupdateAdCounterHistogram()
per richiamare gli eventi di impressione a livello di punto nel codice che scelgono. Gli eventi di impressione sono visibili a tutti gli annunci appartenenti a un determinato DSP e non solo agli annunci nello stesso segmento di pubblico personalizzato. - Visualizzazione: l'evento viene richiamato dal chiamante sul dispositivo (SSP o MMP) in un punto in
il codice scelto tramite una chiamata al numero
updateAdCounterHistogram()
. Gli eventi di visualizzazione sono visibile a tutti gli annunci appartenenti a un determinato DSP e non solo agli annunci nella stessa Segmento di pubblico personalizzato. - Clic: l'evento viene richiamato dal chiamante sul dispositivo (SSP o MMP) in un momento
il codice scelto tramite una chiamata al numero
updateAdCounterHistogram()
. Eventi di clic sono visibili a tutti gli annunci appartenenti a un determinato DSP e non solo agli annunci nella stesso segmento di pubblico personalizzato.
Nell'app del publisher, una piattaforma SSP o MMP che ha una presenza sul dispositivo richiama l'annuncio
eventi. Quando viene chiamato updateAdCounterHistogram()
, il contatore di una frequenza
il filtro del limite viene incrementato in modo che le aste future siano sempre aggiornate.
informazioni sull'esposizione di un utente a un determinato annuncio. I tipi di eventi dell'annuncio non sono
forzatamente vincolati all'azione corrispondente dell'utente e sono
linee guida fornite per aiutare
per strutturare il proprio sistema di eventi. Per incrementare i contatori di annunci nel momento in cui
un evento, l'attore sul dispositivo fornisce l'ID selezione annunci dell'asta dell'annuncio vincente.
Le chiavi del contatore di annunci sono numeri interi con segno a 32 bit arbitrari che sono stati assegnati da un annuncio dell'acquirente. tecnologia e corrispondono a un determinato insieme di annunci come definito dalla DSP. Poiché l'annuncio le chiavi contatore sono limitate solo agli annunci che appartengono a un determinato DSP, queste chiavi possono essere selezionati senza sovrapporsi agli istogrammi di un'altra tecnologia pubblicitaria. Contatore annunci le chiavi vengono utilizzate per incrementare gli identificatori specifici del DSP negli annunci di una DSP o all'interno a un determinato segmento di pubblico personalizzato per filtrare gli annunci da aste future.
Le chiavi contatore possono essere sfruttate per dare priorità agli annunci che hanno maggiori probabilità interessante per un determinato utente sulla base delle sue interazioni con altri annunci da un una determinata tecnologia pubblicitaria dell'acquirente. Ad esempio, un annuncio che ha ricevuto un alto livello il coinvolgimento derivante da aste di annunci vincenti, visualizzazioni e clic, rappresenta una punto dati. Per illustrare ulteriormente questo punto: un annuncio per mazze da golf mancini potrebbe indicare che all'utente non sarebbero interessati quelli per destrimani. R il filtro della quota limite impostato per una chiave contatore assegnato agli annunci sinistri può filtrare gli annunci per mazze per destrimani.
Per utilizzare la quota limite nell'asta, devi prima creare
KeyedFrequencyCap
oggetti come mostrato di seguito:
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();
Una volta creati gli oggetti KeyedFrequencyCap
, puoi passarli a un
Oggetto AdFilters
.
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();
Quando l'oggetto AdFilters
viene compilato con i filtri per la quota limite, è possibile
trasmesso al momento della creazione del segmento di pubblico personalizzato:
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();
Quando i filtri per la quota limite vengono implementati in un segmento di pubblico personalizzato, la piattaforma SSP può richiamare gli eventi necessari di clic, visualizzazione o impressione.
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();
Gli annunci che hanno raggiunto i limiti di filtro della quota limite preimpostati vengono esclusi dell'asta. L'applicazione dei filtri avviene prima dell'esecuzione della logica di offerta on-device e man mano che il payload viene generato per Offerte e Asta di Google Cloud.Questo toolkit offre ai tecnici pubblicitari la flessibilità di utilizzare interazioni tra gli utenti e gli annunci all'interno dei loro segmenti di pubblico personalizzati per e al minimo la sovraesposizione degli annunci.
Filtro degli annunci contestuali senza chiamate di rete
Se non c'è alcuna richiesta di remarketing sul dispositivo, puoi eseguire la selezione degli annunci per annunci contestuali senza chiamate di rete. Con URI predefiniti e un elenco di gli annunci contestuali con offerte, la piattaforma può saltare il recupero della logica di offerta indicatori di offerta e di punteggio. La piattaforma utilizza un URI predefinito per selezionare l'annuncio contestuale che presenta l'offerta più alta.
Per migliorare la latenza, i tecnici pubblicitari possono eseguire un flusso di selezione degli annunci che includa solo
annunci contestuali con funzionalità di filtro degli annunci senza chiamate di rete. Questo è
si ottengono utilizzando URI predefiniti per l'assegnazione di indicatori. Fai riferimento alla sezione
sezione dei nomi e dei casi d'uso degli URI predefiniti per un elenco di scoreAds
implementazioni.
Per eseguire la selezione degli annunci senza chiamate di rete:
- Configurare il filtro degli annunci
- Creare annunci contestuali
Crea un oggetto
AdSelectionConfig
con quanto segue:- Un elenco di acquirenti vuoto
- Un URI predefinito per selezionare l'offerta più alta
- Annunci contestuali
- Un URI vuoto per gli indicatori di punteggio. L'URI vuoto può indicare Non vuoi utilizzare il recupero degli indicatori attendibili per assegnare un punteggio:
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();
Pubblica selezione annunci:
adSelectionManager.selectAds( adSelectionConfig, executor, outcomeReceiver);
Esegui il tuo codice JavaScript di reporting mentre utilizzi URI predefiniti
Oggi, la piattaforma Privacy Sandbox ha solo un codice JavaScript di base per i report
per gli URI predefiniti. Se vuoi eseguire il tuo deployment
generare report su JavaScript pur continuando a usare URI predefiniti per un annuncio a bassa latenza
puoi sostituire il valore DecisionLogicUri
tra la selezione degli annunci e
il reporting è in esecuzione.
- Esegui i passaggi per eseguire la selezione degli annunci per gli annunci contestuali utilizzando URI predefiniti
Crea una copia del tuo
AdSelectionConfig
prima di eseguire il reportadSelectionConfigWithYourReportingJS = adSelectionConfig.cloneToBuilder() // Replace <urlToFetchYourReportingJS> with your own URL: .setDecisionLogicUri(Uri.parse(<urlToFetchYourReportingJS>)) .build();
Generare report sulle impressioni
// adSelectionId is from the result of the previous selectAds run ReportImpressionRequest request = new ReportImpressionRequest( adSelectionId, adSelectionConfigWithYourReportingJS); adSelectionManager.reportImpression( request, executor, outcomeReceiver);
Esegui la mediazione a cascata
La mediazione a cascata richiede più SDK di terze parti (reti di terze parti) orchestrate da una rete di mediazione SDK proprietaria. La mediazione a cascata è allo stesso modo, a prescindere dal fatto che l'asta si sia svolta sul dispositivo o il Offerte e Servizi di aste (B&A).
Reti di terze parti
Le reti di terze parti devono fornire un adattatore che consenta alla rete di mediazione richiamare i metodi necessari per eseguire un'asta:
- Pubblica selezione annunci
- Registra le impressioni
Ecco un esempio di adattatore di rete di mediazione:
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() {...}
}
Ciascun SDK dispone dei propri clienti e gestori del servizio di selezione degli annunci e di
Implementazione di selectAds
e reportImpressions
. I provider di SDK possono fare riferimento
le sezioni su come eseguire la selezione degli annunci per le aste on-device o il B&A
esplicativo per le aste B&A. Segui come segnalare l'annuncio
impressioni (in base ai report sulle singole impressioni SSP per
i report.
Rete di mediazione
Analogamente alle reti di terze parti, le reti di mediazione richiedono selectAds
e
reportImpression
implementazioni. Consulta le sezioni su come pubblicare un annuncio
selezione e su come generare report sulle impressioni degli annunci per saperne di più.
Le reti di mediazione sono responsabili della gestione della catena di mediazione e del posizionamento nella catena di mediazione. La prossima sezione illustra come impostare e questo processo.
Recuperare la catena di mediazione e i prezzi minimi di offerta
La rete di mediazione è responsabile del recupero della parte proprietaria
gli annunci contestuali, la catena di mediazione
e le reti di terze parti, prezzi minimi (terze parti). Questo
può verificarsi in una richiesta di recupero di annunci contestuali eseguiti dalla mediazione
in ogni rete. La catena di mediazione determina come eseguire l'iterazione attraverso le reti di terze parti.
e i prezzi minimi delle offerte possono essere trasmessi al processo dell'asta come adSelectionSignals
.
Posizionamento sulla rete nella catena di mediazione
Un SDK di mediazione può posizionarsi nella catena di mediazione in base al proprio eCPM in tempo reale
delle offerte per annunci proprietari. Nell'API Protected Audience, le offerte per gli annunci sono opache. Una mediazione
L'SDK deve usare AdSelectionFromOutcomesConfig
per poter confrontare una determinata proprietà proprietaria
l'offerta dell'annuncio all'offerta minima della successiva rete di terze parti nella catena. Se l'offerta proprietaria è
superiore all'offerta minima, significa che l'SDK di mediazione è posizionato in primo piano
della rete di terze parti.
Pubblica selezione annunci
Per recuperare un candidato per un annuncio proprietario, la rete di mediazione può eseguire una
seguendo i passaggi nella sezione Esegui selezione degli annunci. Questo genera
un candidato annuncio proprietario, un'offerta e un AdSelectionId
che viene utilizzato nella mediazione
e il processo di sviluppo.
Crea un AdSelectionFromRisultatosConfig
Un AdSelectionFromOutcomesConfig
consente alla rete di mediazione di trasmettere un elenco
di AdSelectionIds
(risultati di aste precedenti), indicatori di selezione degli annunci e
un URI per recuperare il codice JavaScript che seleziona un annuncio tra più candidati. Elenco
di AdSelectionId insieme alle relative offerte e gli indicatori vengono trasmessi
JavaScript che può restituire uno degli AdSelectionIds
se supera l'offerta
minimo o nessuno se la catena di mediazione deve continuare.
Le reti di mediazione creano un AdSelectionFromOutcomesConfig
utilizzando i dati proprietari
AdSelectionId
della sezione precedente e l'offerta minima per la rete di terze parti
essere presi in considerazione. È necessario creare un nuovo AdSelectionFromOutcomesConfig
per ogni passaggio della catena di mediazione.
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){}
}
L'override del metodo selectAds()
per la mediazione a cascata richiede un
Input AdSelectionFromOutcomesConfig
, in cui devi specificare quanto segue
parametri obbligatori:
- Venditore: l'identificatore della rete pubblicitaria del venditore che avvia la selezione degli annunci.
- AdSelectionIds: un elenco singleton di una precedente esecuzione di
selectAds()
per una proprietà annuncio. - Indicatori di selezione degli annunci: un oggetto JSON, serializzato come stringa, contenente indicatori da utilizzare dalla logica di offerta dell'acquirente. In questo caso, includi l'offerta minima recuperate per la rete di terze parti specificata.
- URI Selection Logic: un URL HTTPS che è stato oggetto di una query durante la selezione dell'annuncio per recuperare il valore
codice JavaScript della rete di mediazione per selezionare un annuncio vincente. Consulta i campi obbligatori
firme di funzione in questo codice JavaScript. Il codice JavaScript dovrebbe restituire l'oggetto
annuncio di terze parti se l'offerta è superiore all'offerta minima, altrimenti restituisce
null
. In questo modo l'SDK di mediazione può troncare la catena di mediazione quando un vincitore è un vincitore. trovato.
Dopo aver creato AdSelectionOutcomesConfig
, chiama il metodo selectAds()
di
la rete di terze parti che è la prima della catena.
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);
Orchestrare la mediazione a cascata
Di seguito è riportato l'ordine delle operazioni per eseguire la mediazione e il processo di sviluppo.
- Esegui la selezione di annunci proprietari.
- Ripeti la procedura sulla catena di mediazione. Per ogni rete di terze parti:
- Build
AdSelectionFromOutcomeConfig
che includeoutcomeId
proprietari e Offerta minima dell'SDK di terze parti. - Chiama
selectAds()
con la configurazione del passaggio precedente. - Se il risultato non è vuoto, restituisci l'annuncio.
- Chiama il metodo
selectAds()
dell'adattatore di rete SDK corrente. Se il risultato non è vuoto, restituisce l'annuncio.
- Build
- Se nella catena non viene trovato alcun vincitore, restituisci l'annuncio proprietario.
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) { ... }
}
Registra impressioni degli annunci
Esistono due flussi per segnalare un'impressione dell'annuncio a seconda di come si svolge l'asta viene eseguito. Se rappresenti una singola SSP che esegue un'asta, segui questa sezione. Se vuoi implementare la mediazione a cascata, segui i passaggi indicati sezione dei report sulle impressioni della mediazione a cascata.
Report sulle impressioni singole SSP
Dopo che è stato scelto un annuncio vincente dal flusso di lavoro di selezione degli annunci, è possibile
Segnalare l'impressione alle piattaforme lato acquisti e lato vendite partecipanti
con il metodo AdSelectionManager.reportImpression()
. Per segnalare un annuncio
impressione:
- Inizializza un oggetto
AdSelectionManager
. - Crea un oggetto
ReportImpressionRequest
con l'ID selezione annunci. - Chiama il metodo
reportImpression()
asincrono con OggettoReportImpressionRequest
eExecutor
eOutcomeReceiver
di oggetti.
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)
Inizializza ReportImpressionRequest
con quanto segue:
parametri:
- ID selezione annunci: un ID univoco solo per un utente del dispositivo che identifica un una selezione efficace degli annunci.
- Configurazione della selezione degli annunci: la stessa configurazione utilizzata in
selectAds()
. chiamata identificata dall'ID selezione annunci fornito.
Il metodo reportImpression()
asincrono utilizza OutcomeReceiver
per segnalare il risultato della chiamata API.
- Il callback
onResult()
indica se gli URL dei report sulle impressioni sono stati e la richiesta è stata pianificata. - Il callback
onError()
indica le seguenti condizioni possibili:- Se la chiamata viene inizializzata con un argomento di input non valido, il valore
AdServicesException
indicaIllegalArgumentException
come la causa. - A tutti gli altri errori viene assegnato un valore
AdServicesException
con unIllegalStateException
come causa.
- Se la chiamata viene inizializzata con un argomento di input non valido, il valore
Report sulle impressioni della mediazione a cascata
Un SDK di mediazione deve tenere traccia dell'SDK vincente per attivare la sua di generazione dei report. Gli SDK che partecipano a una catena di mediazione devono fornire una che il mediatore deve richiamare per attivare il proprio flusso di reporting. Un SDK la partecipazione a un'asta con mediazione può seguire la procedura descritta sopra per implementare i propri report.
Le SSP possono utilizzare questo esempio di codice SDK di terze parti come prototipo per le modalità di partecipazione flussi di mediazione:
Pair<AdSelectionOutcome, NetworkAdapter> winnerOutcomeAndNetwork =
mediationSdk.orchestrateMediation(mediationChain);
if (winner.first.hasOutcome()) {
winner.second.reportImpressions(winner.first.getAdSelectionId());
Endpoint per il reporting delle impressioni
L'API Report Impression emette richieste GET HTTPS agli endpoint forniti Sell-Side Platform e la piattaforma lato acquisti vincente:
Endpoint piattaforma lato acquisti:
- L'API utilizza l'URL della logica di offerta specificato nel segmento di pubblico personalizzato per recuperare il codice JavaScript fornito dall'acquirente, che include la logica per restituire nell'URL dei report sulle impressioni.
- Richiama la funzione JavaScript
reportWin()
, che dovrebbe restituire l'URL del report sulle impressioni dell'acquirente.
Endpoint piattaforma lato vendite:
- Utilizza l'URL della logica di decisione specificato in
AdSelectionConfig
per recuperare il codice JavaScript della logica decisionale del venditore. - Richiama la funzione JavaScript
reportResult()
, che dovrebbe restituire l'istruzione URL del report sulle impressioni del venditore.
Offerte e Report sui servizi di aste
Un'asta eseguita su Offerte e I servizi di aste disporranno di tutte le informazioni dei report, inclusi gli URL generati per i report sull'interazione con gli annunci; incluse nella risposta criptata dall'asta lato server. Quando la risposta viene decriptata, gli URL appropriati vengono registrati sulla piattaforma, i report sulle impressioni e sugli annunci seguono gli stessi passaggi elencati sopra.
Report sulle impressioni con il migliore sforzo
Il metodo reportImpression()
è progettato per garantire il completamento di
i report.
Segnala interazioni con gli annunci
Protected Audience consente di generare report su interazioni più granulari per di un annuncio con rendering. Possono essere incluse interazioni come tempo di visualizzazione, clic, passaggi del mouse, o qualsiasi altra metrica utile che può essere raccolta. La procedura per ricevere questi richiede due passaggi. Innanzitutto, acquirenti e venditori devono registrarsi per ricevere questi report nel codice JavaScript di reporting. Il cliente dovrà quindi segnalare questi eventi.
Registrazione per ricevere eventi di interazione
La registrazione per gli eventi di interazione avviene in reportWin()
e
funzioni JavaScript reportResult()
del venditore utilizzando una funzione JavaScript
fornita dalla piattaforma: registerAdBeacon
. Per registrarti e ricevere
report sugli eventi, richiama semplicemente la funzione JavaScript della piattaforma
JavaScript. Il seguente snippet utilizza l'reportWin()
di un acquirente, ma lo stesso
si applica a reportResult()
.
reportWin(
adSelectionSignals,
perBuyerSignals,
signalsForBuyer,
contextualSignals,
customAudienceSignals) {
...
// Calculate reportingUri, clickUri, viewUri, and hoverUri
registerAdBeacon("click", clickUri)
registerAdBeacon("view", viewUri)
registerAdBeacon("hover", hoverUri)
return reportingUrl;
}
Eventi di interazione con i report
Dopo aver registrato un'impressione, i clienti possono segnalare le interazioni al
le piattaforme lato acquisti e lato vendite vincenti registrate in precedenza con
AdSelectionManager.reportInteraction()
. Per segnalare un evento relativo agli annunci:
- Inizializza un oggetto
AdSelectionManager
. - Crea un oggetto
ReportInteractionRequest
con l'ID selezione annunci, chiave di interazione, dati delle interazioni e destinazione dei report. - Chiama il metodo
reportInteraction()
asincrono con l'oggettorequest
e oggettiExecutor
eOutcomeReceiver
pertinenti.
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);
Inizializza ReportInteractionRequest
con quanto segue:
parametri:
- ID selezione annunci: un ID selezione annunci recuperato da un valore precedentemente restituito.
AdSelectionOutcome
. - Chiave di interazione: una chiave stringa definita dal client che descrive l'azione essere segnalati. Deve corrispondere alla chiave registrata dal venditore oppure l'acquirente nelle funzioni JavaScript di reporting.
- Dati di interazione: una stringa contenente dati da includere nell'evento. report, per essere POSTATO ai server di reporting.
- Destinazioni report: una maschera di bit che specifica se gli eventi devono essere.
segnalato all'acquirente, al venditore o a entrambi. Questi flag sono forniti
e la maschera di destinazione finale possono essere create
operazioni. Per generare un report relativo a una destinazione, puoi utilizzare il flag fornito dal
direttamente dalla piattaforma. Per generare rapporti a più destinazioni, puoi utilizzare la funzione
OR (
|
) per combinare i valori del flag.
Il metodo reportInteraction()
asincrono utilizza OutcomeReceiver
per segnalare il risultato della chiamata API.
- Il callback
onResult()
indica che la chiamata dell'interazione con il report è valida. - Il callback
onError()
indica le seguenti condizioni possibili:- Se la chiamata viene effettuata mentre l'app è in esecuzione in background,
Viene restituito
IllegalStateException
con una descrizione dell'errore. - Se il client non è in grado di chiamare
reportInteraction()
, viene Viene restituitoLimitExceededException
. - Se il pacchetto non è registrato per chiamare le API incentrate sulla tutela della privacy, viene
Viene restituito
SecurityException()
. - Se le interazioni dei report sull'app sono diverse dall'app che ha chiamato
selectAds()
, viene restituito unIllegalStateException
.
- Se la chiamata viene effettuata mentre l'app è in esecuzione in background,
Viene restituito
- Se l'utente non ha acconsentito ad abilitare le API Privacy Sandbox, la chiamata smetterà di funzionare in silenzio.
Endpoint di reporting delle interazioni
L'API di interazione con i report invia richieste POST HTTPS agli endpoint forniti da la Sell-Side Platform e la piattaforma lato acquisti vincente. Protected Audience corrisponderà le chiavi di interazione con gli URI dichiarati nel report JavaScript ed emettono una richiesta POST a ciascun endpoint per ciascuna interazione segnalata. Il tipo di contenuti della richiesta è in testo normale, dove il corpo è Dati sulle interazioni.
Report sulle interazioni con il miglior sforzo
L'reportInteraction()
è progettata per garantire il completamento del
tramite HTTP POST.
Aggiornamento giornaliero in background
Quando crei un segmento di pubblico personalizzato, la tua app o il tuo SDK può inizializzare un segmento di pubblico personalizzato metadati. Inoltre, la piattaforma può aggiornare i seguenti elementi sui metadati dei segmenti di pubblico con un processo giornaliero di aggiornamento in background.
- Indicatori di offerta per utente
- Dati di Trusted Bidding
AdData
elenco
Questa procedura esegue una query sull'URL di aggiornamento giornaliero definito nel segmento di pubblico personalizzato e l'URL potrebbe restituire una risposta in formato JSON.
- La risposta JSON può contenere uno qualsiasi dei campi di metadati supportati che devono da aggiornare.
- Ogni campo JSON viene convalidato in modo indipendente. Il client ignora qualsiasi campi in formato non corretto che non comportano aggiornamenti a quel particolare campo in la risposta.
- Una risposta HTTP vuota o un oggetto JSON vuoto "
{}
" non genera aggiornamenti dei metadati. - La dimensione del messaggio di risposta deve essere limitata a 10 kB.
- Tutti gli URI devono utilizzare HTTPS.
trusted_bidding_uri
deve condividere lo stesso ETLD+1 dell'acquirente.
Esempio: risposta JSON per l'aggiornamento giornaliero in background
{
"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 per la selezione degli annunci
Il flusso di lavoro di selezione degli annunci orchestra l'esecuzione delle fornito dal venditore.
Il codice JavaScript fornito dall'acquirente viene recuperato dall'URL della logica di offerta specificato in segmento di pubblico personalizzato. Il codice JavaScript restituito dovrebbe includere le seguenti funzioni:
Il codice JavaScript fornito dal venditore viene recuperato dall'URL della logica decisionale specificato in
Il parametro AdSelectionConfig
per l'API di selezione degli annunci. L'oggetto restituito
JavaScript dovrebbe includere le seguenti funzioni:
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 };
}
Parametri di input:
ad
: un oggetto JSON con il formatovar ad = { 'render_url': url, 'metadata': json_metadata };
auction_signals, per_buyer_signals
: oggetti JSON specificati nell'asta oggetto di configurazionecustom_audience_bidding_signals
: oggetto JSON generato dalla piattaforma. La per questo oggetto JSON è: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" }
dove:
owner
,buyer
ename
sono stringhe prese dalle proprietà con lo stesso nome del segmento di pubblico personalizzato che partecipa alla selezione degli annunciactivation_time
eexpiration_time
sono l'ora di attivazione e scadenza del segmento di pubblico personalizzato, espressa in secondi dall'interfaccia Unix epocaca_user_bidding_signals
è una stringa JSON specificata nel CampouserBiddingSignals
diCustomAudience
al momento della creazionetrusted_bidding_signals, contextual_signals
euser_signals
sono in formato JSON di oggetti strutturati. Vengono passati come oggetti vuoti e verranno compilati nelle versioni future. Il loro formato non è applicato in modo forzato dalla piattaforma ed è gestito dalla tecnologia pubblicitaria.
Risultato:
ad
: è l'annuncio a cui fa riferimento l'offerta. Lo script può restituire una copia di l'annuncio ricevuto con metadati diversi. La proprietàrender_url
del si prevede che l'annuncio rimanga invariato.bid
: un valore in virgola mobile che rappresenta il valore dell'offerta per questo annunciostatus
: un valore intero che può essere:0
: per un'esecuzione corretta1
: (o qualsiasi valore diverso da zero) nel caso in cui uno qualsiasi degli indicatori di input non sia valido. Nella se viene restituito un valore diverso da zero da "Genera offerta", il processo di offerta invalidato per tutti gli annunci CA
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 };
}
Parametri di input:
ad
: visualizza la documentazione digenerateBid
bid
: il valore dell'offerta per l'annuncioad_selection_config
: un oggetto JSON che rappresenta ParametroAdSelectionConfig
dell'APIselectAds
. Il formato è: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
: gli oggetti JSON vengono letti dall'sellerSignals
Parametro APIAdSelectionConfig
trusted_scoring_signal
: viene letta dal campoadSelectionSignals
nella Parametro APIAdSelectionConfig
contextual_signals, user_signals
: oggetti JSON. Attualmente vengono passati come oggetti vuoti e verranno riempiti nelle versioni future. Il loro formato non è applicati dalla piattaforma ed è gestito dalla tecnologia pubblicitaria.per_buyer_signals
: oggetto JSON letto dalla mappaperBuyerSignal
nel Parametro APIAdSelectionConfig
utilizzando come chiave l'attuale Parametro API Acquirente del segmento di pubblico. Vuota se la mappa non contiene voci per il valore specificato acquirente.
Output:
score
: un valore in virgola mobile che rappresenta il valore del punteggio per questo annunciostatus
: un valore intero che può essere:- 0: per un'esecuzione corretta
- 1: se i valori
customAudienceSignals
non sono validi - 2: se
AdSelectionConfig
non è valido - 3: nel caso in cui uno degli altri indicatori non sia valido
- Qualsiasi valore diverso da zero causa l'errore del processo, il valore determina il tipo di eccezione generata
selectOutcome()
function selectOutcome(
outcomes,
selection_signals) {
return {'status': 0, 'result': null};
}
Parametri di input:
outcomes
: un oggetto JSON{"id": id_string, "bid": bid_double}
selection_signals
: oggetti JSON specificati nella configurazione dell'asta oggetto
Output:
status
:0
per l'esito positivo, diverso da zero per l'erroreresult
: uno dei risultati passati o nullo
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 }
};
}
Parametri di input:
ad_selection_config
: visualizza la documentazione discoreAds
render_url
: l'URL di rendering dell'annuncio vincentebid
: l'offerta offerta per l'annuncio vincentecontextual_signals
: visualizza la documentazione digenerateBid
Output:
status: 0
per le operazioni riuscite e un valore diverso da zero per gli erroriresults
: un oggetto JSON contenente:signals_for_buyer
: un oggetto JSON passato areportWin
funzionereporting_url
: un URL utilizzato dalla piattaforma per inviare notifiche a impressione per l'acquirente
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 } };
}
Parametri di input:
ad_selection_signals, per_buyer_signals
: visualizza la documentazione perscoreAd
signals_for_buyer
: un oggetto JSON restituito dareportResult
contextual_signals, custom_audience_signals
: visualizza la documentazione pergenerateBid
Output:
status: 0
per le operazioni riuscite e un valore diverso da zero per gli erroriresults
: un oggetto JSON contenente:reporting_url
: un URL utilizzato dalla piattaforma per inviare notifiche a impressione al venditore
registerAdBeacon()
function registerAdBeacon(
interaction_key,
reporting_uri
)
Parametri di input:
interaction_key
: una stringa che rappresenta l'evento. Questa è utilizzata alla piattaforma in un secondo momento, quando segnali le interazioni di eventi per cercarereporting_uri
che devono essere informati. Questa chiave deve corrispondere a l'acquirente o il venditore si stanno registrando e i dati segnalati dal venditore.reporting_uri
: un URI per ricevere i report sugli eventi. Dovrebbe essere specifico per il tipo di evento segnalato. Deve accettare una richiesta POST per gestire i dati riportati insieme all'evento.
URI predefiniti per la selezione degli annunci
Gli URI predefiniti consentono ai tecnici pubblicitari di assegnare funzioni JavaScript per gli annunci
logica decisionale di selezione in AdSelectionConfig
e
AdSelectionFromOutcomesConfig
corso. Gli URI predefiniti non richiedono la rete
per scaricare il codice JavaScript corrispondente. I tecnici pubblicitari possono utilizzare URI predefiniti
senza dover configurare un dominio registrato per ospitare il codice JavaScript.
Un URI predefinito viene creato utilizzando il seguente formato:
ad-selection-prebuilt:<use-case>/<name>?<required-script-generation-parameters>
La piattaforma Privacy Sandbox fornisce JavaScript utilizzando le informazioni URI nel runtime.
Viene lanciato un valore IllegalArgumentException
se:
- nessuno dei parametri richiesti è presente nell'URI
- Nell'URI sono presenti parametri non riconosciuti
Casi d'uso e nomi degli URI predefiniti supportati
Caso d'uso 1: selezione degli annunci
Gli URI predefiniti nel caso d'uso ad-selection
sono supportati nella
Flusso selectAds(AdSelectionConfig)
.
Nome URI predefinito: highest-bid-wins
Questo URI predefinito fornisce un codice JavaScript che sceglie l'annuncio con l'offerta più alta
dopo l'offerta. Fornisce inoltre una funzione di reporting di base per segnalare
render_uri
e bid
del vincitore.
Parametri obbligatori
reportingUrl
: l'URL del report di base parametrizzato con
render_uri
e bid
dell'annuncio vincente:
<reportingUrl>?render_uri=<renderUriOfWinnigAd>&bid=<bidOfWinningAd>
Utilizzo
Se l'URL report di base è https://www.ssp.com/reporting
, l'URL predefinito
L'URI sarebbe:
`ad-selection-prebuilt://ad-selection/highest-bid-wins/?reportingUrl=https://www.ssp.com/reporting`
Caso d'uso 2: selezione degli annunci dai risultati
Gli URI predefiniti nel caso d'uso ad-selection-from-outcomes
supportano
selectAds(AdSelectionFromOutcomesConfig)
.
Nome URI predefinito: waterfall-mediation-truncation
L'URI predefinito waterfall-mediation-truncation
fornisce JavaScript che
implementa la logica di troncamento della mediazione a cascata in cui il codice JavaScript restituisce
un annuncio proprietario se il valore di bid
è superiore o uguale a bid floor
e
altrimenti restituisce null
.
Parametri obbligatori
bidFloor
: la chiave del valore minimo dell'offerta trasmesso nel campo getSelectionSignals()
.
confrontato con l'annuncio dell'SDK di mediazione.
Utilizzo
Se gli indicatori di selezione degli annunci sono simili a {"bid_floor": 10}
, gli indicatori risultanti
l'URI predefinito sarebbe:
`ad-selection-prebuilt://ad-selection-from-outcomes/waterfall-mediation-truncation/?bidFloor=bid_floor`
Test
Per aiutarti a iniziare a utilizzare l'API Protected Audience, abbiamo creato un campione in Kotlin e Java, disponibili su GitHub.
Prerequisiti
L'API Protected Audience richiede del codice JavaScript durante la selezione degli annunci e report sulle impressioni. Esistono due metodi per fornire questo codice JavaScript in una di test dell'ambiente di test:
- Esegui un server con gli endpoint HTTPS richiesti che restituiscano il codice JavaScript
- Esegui l'override del recupero remoto fornendo il codice necessario da un'origine locale
Entrambi gli approcci richiedono la configurazione di un endpoint HTTPS per gestire le impressioni i report.
Endpoint HTTPS
Per testare la selezione degli annunci e i report sulle impressioni, è necessario configurare 7 HTTPS endpoint accessibili dal dispositivo di test o dall'emulatore:
- Endpoint dell'acquirente che pubblica la logica di offerta JavaScript.
- Un endpoint che pubblica gli indicatori di offerta.
- Endpoint del venditore che pubblica la logica decisionale in JavaScript.
- Un endpoint che fornisce indicatori di punteggio.
- Endpoint del report sulle impressioni dell'acquirente vincente.
- Endpoint per i report sulle impressioni del venditore.
- Un endpoint per pubblicare gli aggiornamenti giornalieri per un segmento di pubblico personalizzato.
Per praticità, il repository GitHub fornisce il codice JavaScript di base per i test scopi. Include inoltre definizioni del servizio OpenAPI di cui è possibile eseguire il deployment una piattaforma fittizia o di microservizi supportata. Per maggiori dettagli, consulta il progetto LEGGIMI.
Esegui l'override del recupero remoto di JavaScript
Questa funzionalità è stata pensata per essere utilizzata per test end-to-end. Per eseguire l'override del telecomando recupero, l'app deve essere eseguita in modalità di debug con le opzioni sviluppatore attivate.
Per attivare la modalità di debug per la tua applicazione, aggiungi la riga seguente alla nel tuo file AndroidManifest.xml:
<application
android:debuggable="true">
Per un esempio di come utilizzare queste sostituzioni, consulta il Centro Esempio di app dell'API Audience su GitHub.
Devi aggiungere il tuo codice JavaScript personalizzato per gestire le routine di selezione degli annunci, come per le offerte, le decisioni sulla valutazione e i report. Puoi trovare il codice JavaScript di base esempi che gestiscono tutte le richieste richieste nel repository GitHub. L'applicazione di esempio dell'API Protected Audience dimostra come leggere il codice da del file e prepararlo per l'uso come override.
È possibile eseguire l'override del recupero JavaScript lato vendite e lato acquisti in modo indipendente, anche se è necessario un endpoint HTTPS per pubblicare qualsiasi non stai fornendo override. Consulta README per informazioni su come configurare un server che gestisca questi casi.
È possibile eseguire l'override del recupero di JavaScript solo per i segmenti di pubblico personalizzati che sono di proprietà del tuo pacchetto.
Eseguire l'override del codice JavaScript lato vendite
Per configurare un'override di JavaScript lato vendite, procedi come indicato di seguito nel seguente esempio di codice:
- Inizializza un oggetto
AdSelectionManager
. - Ottieni un riferimento a
TestAdSelectionManager
dalAdSelectionManager
oggetto. - Crea un oggetto
AdSelectionConfig
. - Crea una
AddAdSelectionOverrideRequest
conAdSelectionConfig
e unString
che rappresenta il codice JavaScript che intendi utilizzare come override. - Chiama il metodo
overrideAdSelectionConfigRemoteInfo()
asincrono con OggettoAddAdSelectionOverrideRequest
eExecutor
pertinente eOutcomeReceiver
.
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);
Consulta la sezione Esegui selezione di annunci per ulteriori informazioni su ogni
rappresentate dai campi di AdSelectionConfig
. La differenza principale è
che decisionLogicUrl può essere impostato su un valore segnaposto, così come sarà
ignorato.
Per sostituire il codice JavaScript utilizzato durante la selezione degli annunci, il parametro
decisionLogicJs
deve contenere le firme delle funzioni lato venditore appropriate.
Per un esempio di come leggere un file JavaScript come stringa, consulta la
App di esempio dell'API Protected Audience su GitHub.
Il metodo overrideAdSelectionConfigRemoteInfo()
asincrono utilizza
OutcomeReceiver
per segnalare il risultato della chiamata API.
Il callback onResult()
indica che l'override è stato applicato correttamente.
Le chiamate future a selectAds()
utilizzeranno qualsiasi decisione e report
che hai trasmesso come override.
Il callback onError()
indica due possibili condizioni:
- Se si tenta di eseguire l'override con argomenti non validi,
AdServiceException
indicaIllegalArgumentException
come causa. - Se si tenta di eseguire l'override con un'app non in esecuzione in modalità di debug con
le opzioni sviluppatore attivate,
AdServiceException
indicaIllegalStateException
come causa.
Reimposta sostituzioni lato vendite
Questa sezione presuppone che tu abbia sostituito il codice JavaScript lato vendite e che
fai riferimento a TestAdSelectionManager
e
AdSelectionConfig
utilizzata nella sezione precedente.
Per reimpostare gli override per tutte le AdSelectionConfigs
:
- Chiama il metodo
resetAllAdSelectionConfigRemoteOverrides()
asincrono con l'oggettoOutcomeReceiver
pertinente.
Kotlin
// Resets overrides for all AdSelectionConfigs
testAadSelectionManager.resetAllAdSelectionConfigRemoteOverrides(
outComeReceiver)
Java
// Resets overrides for all AdSelectionConfigs
testAdSelectionManager.resetAllAdSelectionConfigRemoteOverrides(
outComeReceiver);
Dopo aver reimpostato gli override lato vendite, le chiamate a selectAds()
utilizzano qualsiasi
decisionLogicUrl viene archiviato in AdSelectionConfig
per tentare di
recuperare il codice JavaScript richiesto.
Se la chiamata a resetAllAdSelectionConfigRemoteOverrides()
non riesce,
Il callback OutComeReceiver.onError()
restituisce un valore AdServiceException
.
Se si tenta di rimuovere gli override con un'app non in esecuzione in modalità di debug
con le opzioni sviluppatore attivate, AdServiceException
indica
IllegalStateException
come causa.
Sostituire il codice JavaScript lato acquisti
- Segui i passaggi per entrare a far parte di un segmento di pubblico personalizzato
- Crea una
AddCustomAudienceOverrideRequest
con l'acquirente e il nome del segmento di pubblico personalizzato che vuoi sostituire, oltre al sulla logica e sui dati di offerta da utilizzare come sostituzione. - Chiama il metodo
overrideCustomAudienceRemoteInfo()
asincrono conAddCustomAudienceOverrideRequest
e pertinente OggettiExecutor
eOutcomeReceiver
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);
I valori per buyer e name sono gli stessi utilizzati per creare il segmento di pubblico personalizzato. Scopri di più su questi campi.
Inoltre, puoi specificare due parametri aggiuntivi:
biddingLogicJs
: codice JavaScript che contiene la logica dell'acquirente utilizzata durante la selezione degli annunci. Vedi le firme delle funzioni richieste in questa JavaScript.trustedBiddingSignals
: indicatori di offerta da utilizzare durante la selezione degli annunci. A scopo di test, può essere una stringa vuota.
Il metodo overrideCustomAudienceRemoteInfo()
asincrono utilizza
OutcomeReceiver
per segnalare il risultato della chiamata API.
Il callback onResult()
indica che l'override è stato applicato correttamente.
Le chiamate successive a selectAds()
utilizzano qualsiasi logica di offerta e generazione di report
che hai passato come override.
Il callback onError()
rappresenta due condizioni possibili.
- Se si tenta di eseguire l'override con argomenti non validi,
AdServiceException
indicaIllegalArgumentException
come causa. - Se si tenta di eseguire l'override con un'app non in esecuzione in modalità di debug con
le opzioni sviluppatore attivate,
AdServiceException
indicaIllegalStateException
come causa.
Reimposta sostituzioni lato acquisti
In questa sezione si presuppone che tu abbia eseguito l'override del codice JavaScript lato acquisti e che
fai riferimento a TestCustomAudienceManager
utilizzato
sezione precedente.
Per reimpostare gli override per tutti i segmenti di pubblico personalizzati:
- Chiama il metodo
resetAllCustomAudienceOverrides()
asincrono con oggettiExecutor
eOutcomeReceiver
pertinenti.
Kotlin
// Resets overrides for all custom audiences
testCustomAudienceManager.resetCustomAudienceRemoteInfoOverride(
executor,
outComeReceiver)
Java
// Resets overrides for all custom audiences
testCustomAudienceManager.resetCustomAudienceRemoteInfoOverride(
executor,
outComeReceiver)
Dopo aver reimpostato gli override del lato acquisti, le chiamate successive a selectAds()
utilizzare qualsiasi cosa siano biddingLogicUrl
e trustedBiddingData
archiviati in CustomAudience
per tentare di recuperare i dati
JavaScript.
Se la chiamata a resetCustomAudienceRemoteInfoOverride()
non riesce,
Il callback OutComeReceiver.onError()
restituisce un valore AdServiceException
.
Se si tenta di rimuovere gli override con un'app non in esecuzione in modalità di debug
con le opzioni sviluppatore attivate, AdServiceException
indica
IllegalStateException
come causa.
Configura un server di reporting
Quando utilizzi gli override del recupero remoto, devi comunque configurare un server che il dispositivo o l'emulatore può raggiungere per rispondere agli eventi di segnalazione. Un semplice che restituisce 200 è sufficiente per il test. Il repository GitHub include Definizioni del servizio OpenAPI di cui è possibile eseguire il deployment in una simulazione o di microservizi. Per maggiori dettagli, consulta il progetto LEGGIMI.
Quando cerchi le definizioni OpenAPI, cerca il file reporting-server.json.
Questo file contiene un semplice endpoint che restituisce 200, che rappresenta una richiesta
codice di risposta. Questo endpoint viene utilizzato durante selectAds()
e segnala
il report sulle impressioni è stato completato correttamente
all'API Protected Audience.
Funzionalità da testare
- Fare prove di partecipazione, abbandono e configurazione di un segmento di pubblico personalizzato in base alle azioni utente.
- Esercitare l'avvio della selezione degli annunci sul dispositivo tramite JavaScript in hosting da remoto.
- Osservare in che modo l'associazione di un'app alle impostazioni dei segmenti di pubblico personalizzati può influire sull'annuncio i risultati della selezione.
- Esercitati con i report sulle impressioni dopo la selezione degli annunci.
Limitazioni
La seguente tabella elenca le limitazioni per l'elaborazione dell'API Protected Audience. I limiti presentati potrebbero essere soggetti a modifica in base al feedback. Per funzionalità in corso, leggi le note di rilascio.
Componente | Descrizione limite | Valore limite |
---|---|---|
Segmento di pubblico personalizzato (CA) | Numero massimo di annunci per CA | 100 |
Numero massimo di CA per applicazione | 1000 | |
Numero massimo di app che possono creare una CA | 1000 | |
Ritardo massimo nel tempo di attivazione di una CA dal momento della creazione | 60 giorni | |
Tempo massimo per la scadenza di una CA dall'ora di attivazione | 60 giorni | |
Numero massimo di CA sul dispositivo | 4000 | |
Dimensione massima del nome CA | 200 byte | |
Dimensione massima dell'URI di recupero giornaliero | 400 byte | |
Dimensione massima URI della logica di offerta | 400 byte | |
Dimensione massima dei dati di Trusted Bidding | 10 kB | |
Dimensione massima degli indicatori di offerta per l'utente | 10 kB | |
Tariffa massima di chiamata a leaveCustomAudience per acquirente |
1 al secondo | |
Tariffa massima di chiamata a joinCustomAudience per acquirente |
1 al secondo | |
Recupero in background CA | Timeout connessione | 5 secondi |
Timeout lettura HTTP | 30 secondi | |
Dimensioni massime totali di download | 10 kB | |
Durata massima di un'iterazione di recupero | 5 minuti | |
Numero massimo di CA aggiornate per job | 1000 | |
Selezione degli annunci | Numero massimo di acquirenti | Da definire |
Numero massimo di CA per acquirente | Da definire | |
Numero massimo di annunci in un'asta | Da definire | |
Timeout iniziale della connessione | 5 secondi | |
Timeout di lettura della connessione | 5 secondi | |
Tempo di esecuzione massimo per AdSelection nel complesso |
10 secondi | |
Tempo massimo di esecuzione delle offerte per CA in AdSelection |
5 secondi | |
Tempo massimo di esecuzione per il punteggio in AdSelection |
5 secondi | |
Tempo di esecuzione massimo per acquirente in AdSelection |
Da definire | |
Dimensione massima degli indicatori selezione annunci/venditore/per acquirente | Da definire | |
Dimensione massima degli script venditore/acquirente | Da definire | |
Tariffa massima chiamate per selectAds |
1 QPS | |
Report sulle impressioni | Tempo minimo prima di rimuovere la selezione di annunci dalla persistenza | 24 ore |
Numero massimo di selezioni di annunci per spazio di archiviazione | Da definire | |
Dimensione massima dell'URL di output del report | Da definire | |
Tempo massimo per i report sulle impressioni | Da definire | |
Numero massimo di nuovi tentativi per le chiamate di notifica | Da definire | |
Connessione in timeout | 5 secondi | |
Tempo di esecuzione complessivo massimo per reportImpression |
2 secondi | |
Tariffa massima chiamate per reportImpressions |
1 QPS | |
Report sugli eventi | Numero massimo di beacon per acquirente per asta | 10 |
Numero massimo di beacon per venditore per asta |
10 |
|
Dimensione massima della chiave evento |
40 byte |
|
Dimensione massima dei dati sugli eventi |
64 kB |
|
Annunci | Dimensione massima dell'elenco di annunci | 10 kB condivisi da tutti
AdData
in un'unica CA per l'analisi |
URL | Lunghezza massima di qualsiasi stringa URL presa come input | Da definire |
JavaScript | Tempo massimo di esecuzione | 1 secondo per le offerte e il punteggio per i report sulle impressioni |
Memoria utilizzata massima | 10 MB |
Segnalare bug e problemi
Il tuo feedback è una parte fondamentale di Privacy Sandbox su Android. Contattaci di eventuali problemi trovati o di idee per migliorare Privacy Sandbox su Android.
Consigliati per te
- Nota: il testo del link viene visualizzato quando JavaScript è disattivato
- Supportare il targeting per pubblico personalizzato con l'API Protected Audience
- Note di rilascio
- Protected Audience: guida all'integrazione