Mentre leggi la documentazione di Privacy Sandbox su Android, utilizza il pulsante Anteprima per sviluppatori o Beta per selezionare la versione del programma che stai utilizzando, poiché le istruzioni possono variare.
L'API Protected Audience su Android (precedentemente nota come FLEDGE) include l'API Custom Audience e l'API Ad Selection. Gli inserzionisti e le piattaforme di ad tech possono utilizzare queste API per pubblicare annunci personalizzati in base al coinvolgimento in app precedente, il che limita la condivisione degli identificatori tra le app e limita la condivisione delle informazioni sull'interazione con le app di un utente con terze parti.
L'API Custom Audience è incentrata sull'astrazione "segmento di pubblico personalizzato", che rappresenta un gruppo di utenti con intenzioni comuni. Un inserzionista può registrare un utente con un segmento di pubblico personalizzato e associare annunci pertinenti a questo segmento. Queste informazioni vengono memorizzate in locale e possono essere utilizzate per definire le offerte degli inserzionisti, i filtri degli annunci e il rendering degli annunci.
L'API Ad Selection fornisce un framework che consente a più sviluppatori di eseguire un'asta a livello locale per un segmento di pubblico personalizzato. Per ottenere questo risultato, il sistema prende in considerazione gli annunci pertinenti associati al segmento di pubblico personalizzato ed esegue un'ulteriore elaborazione sugli annunci che una piattaforma di tecnologia pubblicitaria restituisce al dispositivo.
Le piattaforme ad tech possono integrare queste API per implementare il remarketing che tutela la privacy dell'utente. Per le versioni future è previsto il supporto per casi d'uso aggiuntivi, inclusi gli annunci per l'installazione di app. Scopri di più sull'API Protected Audience su Android nella proposta di progettazione.
Questa guida descrive come utilizzare l'API Protected Audience su Android per:
- Gestire i segmenti di pubblico personalizzati
- Configurare e pubblicare la selezione degli annunci su un dispositivo
- Segnalare 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 emulatore che includa il supporto di Privacy Sandbox su Android.
In un terminale, abilita l'accesso all'API Protected Audience (disabilitata 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
nel file manifest dell'app:<uses-permission android:name="android.permission.ACCESS_ADSERVICES_CUSTOM_AUDIENCE" />
Fai riferimento a una configurazione di servizi pubblicitari nell'elemento
<application>
del 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 manifest, ad esempio
res/xml/ad_services_config.xml
. Scopri di più sulle autorizzazioni per i servizi pubblicitari e sul controllo dell'accesso agli SDK.<ad-services-config> <custom-audiences allowAllToAccess="true" /> </ad-services-config>
Per impostazione predefinita, l'API Ad Selection applica dei limiti alla quantità massima di memoria che può allocare uno script di report sull'asta o sulle impressioni. La funzionalità di limitazione della memoria richiede WebView versione 105.0.5195.58 o successiva. La piattaforma applica un controllo della versione e le chiamate alle API
selectAds
ereportImpression
non vanno a buon fine se questo non è soddisfatto. Sono disponibili due opzioni per l'impostazione:Opzione 1: esegui il comando adb riportato di seguito per disattivare questa verifica:
adb device_config put fledge_js_isolate_enforce_max_heap_size false
Opzione 2: installa WebView beta dal Google Play Store. Deve essere uguale o superiore alla versione indicata in precedenza.
Entra in un segmento di pubblico personalizzato
Un segmento di pubblico personalizzato rappresenta un gruppo di utenti con intenzioni o interessi comuni, come deciso dall'app di un inserzionista. Un'app o un SDK può utilizzare un segmento di pubblico personalizzato per indicare un determinato segmento di pubblico, ad esempio un utente che ha lasciato degli articoli in un carrello degli acquisti. Per creare o unirti a un segmento di pubblico personalizzato in modo asincrono:
- Inizializza l'oggetto
CustomAudienceManager
. - Crea un oggetto
CustomAudience
specificando parametri chiave come il pacchetto dell'acquirente e un nome pertinente. Quindi, inizializza l'oggettoJoinCustomAudienceRequest
con l'oggettoCustomAudience
. - Richiama l'elemento
joinCustomAudience()
asincrono con l'oggettoJoinCustomAudienceRequest
e gli oggettiExecutor
eOutcomeReceiver
pertinenti.
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 ciascun oggetto CustomAudience
su un dispositivo:
owner
: nome del pacchetto dell'app proprietario, impostato implicitamente sul nome del pacchetto dell'app chiamante.buyer
: identificatore della rete pubblicitaria dell'acquirente che gestisce gli annunci per questo segmento di pubblico personalizzato.name
: un nome o identificatore arbitrario per il segmento di pubblico personalizzato.
Chiamare joinCustomAudience()
ripetutamente con un'istanza diversa di
CustomAudience
aggiorna qualsiasi CustomAudience
esistente con
i parametri owner, buyer
e name
corrispondenti. Per contribuire a tutelare la privacy, il risultato dell'API non fa distinzione tra "creazione" e "aggiornamento".
Inoltre, CustomAudience
deve essere creato con questi
parametri obbligatori:
- URL di aggiornamento giornaliero: un URL HTTPS eseguito ogni giorno una query in background per aggiornare gli indicatori di offerte per gli utenti di un segmento di pubblico personalizzato, i dati sulle offerte attendibili e visualizzare gli URL e i metadati per gli annunci.
- URL logica di offerta: un URL HTTPS su cui è stata eseguita una query durante la selezione degli annunci per recuperare la logica di offerta JavaScript di un acquirente. Vedi le firme delle funzioni richieste in questo codice JavaScript.
- ID rendering dell'annuncio: un ID arbitrario impostato dalla tecnologia pubblicitaria dell'acquirente. Si tratta di un'ottimizzazione per la generazione del payload per B&A.
I parametri facoltativi per un oggetto CustomAudience
possono includere:
- Ora di attivazione: un segmento di pubblico personalizzato può partecipare alla selezione degli annunci e agli aggiornamenti giornalieri solo dopo il relativo tempo di attivazione. Questo può essere utile, ad esempio, per coinvolgere gli utenti non più attivi di un'app.
- Data di scadenza: un'ora futura dopo la quale il segmento di pubblico personalizzato viene rimosso dal dispositivo.
- Indicatori delle offerte dell'utente: una stringa JSON contenente indicatori sugli utenti, come le impostazioni internazionali preferite dell'utente, che vengono utilizzati da JavaScript per la logica di offerta di un acquirente per generare offerte durante il processo di selezione degli annunci. Questo formato consente alle piattaforme di ad tech di riutilizzare il codice su più piattaforme e di semplificarne l'utilizzo nelle funzioni JavaScript.
- Dati di offerta attendibili: un URL HTTPS e un elenco di stringhe utilizzate durante il processo di selezione degli annunci che recuperano gli indicatori di offerta da un servizio chiave/valore attendibile.
- 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 eseguita una query per eseguire il rendering dell'annuncio finale.
- Metadati: un oggetto JSON serializzato come stringa contenente informazioni che devono essere utilizzate dalla logica di offerta dell'acquirente durante il processo di selezione degli annunci.
- Filtri degli annunci: una classe contenente tutte le informazioni necessarie per il filtro degli annunci per l'installazione di app e la quota limite durante la selezione degli annunci.
Ecco 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 joinCustomAudience()
Il metodo joinCustomAudience()
asincrono utilizza l'oggetto OutcomeReceiver
per segnalare il risultato della chiamata API.
- Il callback
onResult()
indica che il segmento di pubblico personalizzato è stato creato o aggiornato correttamente. - Il callback
onError()
indica due possibili condizioni.- Se
JoinCustomAudienceRequest
viene inizializzato con argomenti non validi,AdServicesException
indica unaIllegalArgumentException
come causa. - Tutti gli altri errori ricevono un elemento
AdServicesException
conIllegalStateException
come causa.
- Se
Ecco un esempio di gestione del 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);
}
};
Esci da un segmento di pubblico personalizzato
Se l'utente non soddisfa più i criteri aziendali per un determinato segmento
di pubblico personalizzato, un'app o un SDK può chiamare leaveCustomAudience()
per rimuovere il segmento di pubblico
personalizzato dal dispositivo. Per rimuovere una CustomAudience
in base ai suoi parametri
univoci:
- Inizializza l'oggetto
CustomAudienceManager
. - Inizializza
LeaveCustomAudienceRequest
con i valoribuyer
ename
del segmento di pubblico personalizzato. Per saperne di più su questi campi di immissione, consulta "Utilizzare un segmento di pubblico personalizzato". - Richiama il metodo
leaveCustomAudience()
asincrono con l'oggettoLeaveCustomAudienceRequest
e gli oggettiExecutor
eOutcomeReceiver
pertinenti.
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);
Analogamente alla chiamata a joinCustomAudience()
, OutcomeReceiver
segnala la fine di una chiamata API. Per proteggere la privacy, un risultato di errore non distingue tra errori interni e argomenti non validi. Il callback onResult()
viene chiamato al termine della chiamata API, indipendentemente dal fatto che un segmento di pubblico personalizzato corrispondente sia stato rimosso o meno.
Pubblica selezione degli annunci
Per utilizzare l'API Protected Audience per selezionare gli annunci, chiama il metodo selectAds()
:
- Inizializza un oggetto
AdSelectionManager
. - Crea un oggetto
AdSelectionConfig
. - Richiama il metodo
selectAds()
asincrono con l'oggettoAdSelectionConfig
e gli oggettiExecutor
eOutcomeReceiver
pertinenti.
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
, in cui
devi specificare i seguenti parametri obbligatori:
- Venditore: identificatore della rete pubblicitaria del venditore che avvia la selezione degli annunci.
- URL logica di decisione: un URL HTTPS a cui è stata eseguita una query per ottenere la logica JavaScript della rete pubblicitaria del venditore.
- URL HTTPS: è stata eseguita una query per ottenere la logica JavaScript della rete pubblicitaria del venditore. Scopri le firme delle funzioni richieste.
- URI predefinito: che segue il formato di selezione degli annunci di FLEDGE.
Viene generato
IllegalArgumentException
se viene passato un URI predefinito non supportato o in un formato non corretto.
- 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 acquirente corrispondono a
CustomAudience.getBuyer()
dei segmenti di pubblico personalizzati partecipanti.
I seguenti parametri possono essere specificati facoltativamente per una selezione di annunci più personalizzata:
- Indicatori di selezione degli annunci: un oggetto JSON, serializzato come stringa, contenente
indicatori che devono essere utilizzati dal codice JavaScript della logica di offerta dell'acquirente recuperato da
CustomAudience.getBiddingLogicUrl()
. - Indicatori del venditore: un oggetto JSON, serializzato come stringa, contenente gli indicatori utilizzati dalla logica di decisione JavaScript recuperata del venditore da
AdSelectionConfig.getDecisionLogicUrl()
. - Indicatori per acquirente: una mappa di oggetti JSON, serializzati come stringhe, contenente indicatori che devono essere utilizzati dal codice JavaScript della logica di offerta di acquirenti specifici recuperato da
CustomAudience.getBiddingLogicUrl()
, che vengono identificati dai campi acquirente dei segmenti di pubblico personalizzati partecipanti. - Annunci contestuali: una raccolta di candidati di annunci raccolti direttamente dagli acquirenti durante un'asta al di fuori di un'asta di Protected Audience.
Una volta selezionato un annuncio, i risultati, le offerte e gli indicatori vengono conservati internamente per la generazione di 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 di annunci univoco dell'utente del dispositivo. Questo ID viene utilizzato per generare report sull'impressione dell'annuncio.
Se la selezione degli annunci non può essere completata correttamente per motivi quali argomenti non validi, timeout o un consumo eccessivo di risorse, il callback OutcomeReceiver.onError()
fornisce un AdServicesException
con i seguenti comportamenti:
- Se la selezione degli annunci viene avviata con argomenti non validi,
AdServicesException
indicaIllegalArgumentException
come causa. - Tutti gli altri errori ricevono un elemento
AdServicesException
conIllegalStateException
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 essere inclusi
nell'asta utilizzando il AdSelectionConfig
; a quel punto funzionano come
gli annunci sui dispositivi, inclusa l'idoneità al filtro degli annunci per esclusione. Una volta completata l'asta di Protected Audience, devi richiamare reportImpression()
. In questo modo viene richiamato reportWin()
nell'annuncio contestuale vincente, nello stesso pattern dei report sulle impressioni, per ricevere l'annuncio vincente su un dispositivo. Ogni annuncio contestuale ha bisogno di un acquirente, un'offerta, un link alla logica di reporting, un
URL di rendering e i metadati dell'annuncio.
Per implementare annunci contestuali nell'app, l'app di destinazione deve creare un 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ò essere trasmesso durante la creazione di
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 consente di filtrare gli annunci di installazione per le app già installate su un dispositivo.
Il primo passaggio di questa procedura consiste nel definire quali inserzionisti possono filtrare in base al pacchetto installato. Questo deve avvenire nell'app che vuoi scegliere come target con 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 possono quindi escludere le app installate specificate durante la generazione delle offerte. Se devi impedire a un inserzionista di accedere allo stato di installazione di questa app, esegui di nuovo questo codice rimuovendo le informazioni sull'inserzionista.
Il passaggio successivo consiste nell'impostare il filtro degli annunci all'interno dell'app del publisher. La parte che pubblica l'annuncio nell'app del publisher (che molto probabilmente è un SDK Supply-Side) deve inizializzare l'oggetto AdFilters
con le informazioni relative agli annunci relativi 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 che esistono all'interno dei
loro segmenti di pubblico personalizzati.
AdFilters
può essere trasmesso anche al momento di creare un'istanza di un nuovo oggetto 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 per la quota limite
Il filtro della quota limite consente alle tecnologie pubblicitarie di limitare il numero di volte in cui un annuncio viene mostrato. Il filtro della quota limite riduce la sovraesposizione degli annunci e ottimizza la selezione degli annunci alternativi per una determinata campagna pubblicitaria.
Esistono due componenti principali di un filtro quota limite: il tipo di evento annuncio e la chiave del contatore annunci. I tipi di eventi dell'annuncio disponibili che possono essere utilizzati sono:
- Vincere (disponibile a breve): un evento vincente indica che l'annuncio ha vinto un'asta. Gli eventi vincenti vengono aggiornati automaticamente dall'API Protected Audience e non possono essere chiamati direttamente dallo sviluppatore. Questi dati sono visibili solo agli annunci all'interno di un determinato segmento di pubblico personalizzato.
- Impressione: separatamente da
reportImpression
, un chiamante on-device (SSP o MMP) utilizzaupdateAdCounterHistogram()
per richiamare gli eventi di impressioni nel punto del codice scelto. Gli eventi di impressione sono visibili a tutti gli annunci appartenenti a una determinata DSP e non si limitano agli annunci dello stesso segmento di pubblico personalizzato. - Visualizza: l'evento viene richiamato dal chiamante sul dispositivo (SSP o MMP) in un punto del codice scelto tramite una chiamata al numero
updateAdCounterHistogram()
. Gli eventi di visualizzazione sono visibili a tutti gli annunci appartenenti a una determinata DSP e non solo agli annunci nello stesso pubblico personalizzato. - Clic: l'evento viene richiamato dal chiamante sul dispositivo (SSP o MMP) in un momento nel codice scelto tramite una chiamata al numero
updateAdCounterHistogram()
. Gli eventi di clic sono visibili a tutti gli annunci appartenenti a una determinata DSP e non solo agli annunci dello stesso segmento di pubblico personalizzato.
Nell'app del publisher, una SSP o una MMP con una presenza sul dispositivo richiama gli eventi relativi agli annunci. Quando viene chiamato updateAdCounterHistogram()
, il contatore di un filtro
della quota limite viene incrementato in modo che le aste future abbiano informazioni
aggiornate sull'esposizione di un utente a un determinato annuncio. I tipi di eventi dell'annuncio non sono
forzati associati all'azione dell'utente corrispondente e sono linee guida fornite per aiutare
i chiamanti a strutturare il proprio sistema di eventi. Per aumentare i contatori degli annunci al momento di un evento, l'attore on-device fornisce l'ID selezione degli annunci dell'asta dell'annuncio vincente.
Le chiavi del contatore degli annunci sono numeri interi arbitrari con firma a 32 bit assegnati dalla tecnologia pubblicitaria di un acquirente e corrispondono a un determinato insieme di annunci come definito dalla DSP. Poiché le chiavi del contatore annunci sono limitate solo agli annunci appartenenti a una determinata DSP, queste possono essere selezionate senza sovrapporsi agli istogrammi di un'altra tecnologia pubblicitaria. Le chiavi dei contatori degli annunci vengono utilizzate per incrementare gli identificatori specifici di DSP negli annunci di una DSP o all'interno di un determinato segmento di pubblico personalizzato, in modo da escludere gli annunci di aste future.
Le chiavi dei contatori possono essere utilizzate per dare priorità agli annunci che hanno maggiori probabilità di essere interessanti per un determinato utente in base alle sue interazioni con altri annunci di una determinata tecnologia pubblicitaria dell'acquirente. Ad esempio, un annuncio che ha ricevuto un elevato livello di coinvolgimento grazie alla vincita di aste dell'annuncio, visualizzazioni e clic rappresenta un punto dati dedotto. Per chiarire meglio questo punto, un annuncio relativo a mazze da golf mancini potrebbe indicare che l'utente non sarebbe interessato a quelli per destri. Un filtro per la quota limite impostato per un tasto del contatore assegnato agli annunci della mano sinistra potrebbe filtrare gli annunci per i club della mano destra.
Per utilizzare la quota limite nella tua 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 trasferirli in 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, puoi trasmetterlo 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 SSP può richiamare gli eventi di clic, visualizzazione o impressione necessari.
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 preimpostati del filtro per la quota limite vengono esclusi dall'asta. I filtri vengono applicati prima dell'esecuzione della logica di offerta per le aste on-device e durante la generazione del payload per le aste dei servizi di offerte e aste.Questo toolkit offre ai tecnici pubblicitari la flessibilità di utilizzare le interazioni tra gli utenti e gli annunci all'interno dei loro segmenti di pubblico personalizzati per concentrare il targeting degli annunci, riducendo al minimo la sovraesposizione degli annunci.
Filtro contestuale degli annunci senza chiamate di rete
Se sul dispositivo non è presente alcuna domanda di remarketing, puoi pubblicare la selezione degli annunci per gli annunci contestuali senza chiamate di rete. Grazie agli URI predefiniti e a un elenco di annunci contestuali con offerte, la piattaforma può saltare il recupero della logica di offerta, degli indicatori di offerta e degli indicatori di punteggio. La piattaforma utilizza un URI predefinito per selezionare l'annuncio contestuale con l'offerta più alta.
Per migliorare la latenza, gli ad tech possono eseguire un flusso di selezione degli annunci che include solo
annunci contestuali con funzionalità di filtro degli annunci senza chiamate di rete. Ciò si ottiene utilizzando gli URI predefiniti per gli indicatori di punteggio. Consulta la sezione relativa ai nomi e ai casi d'uso degli URI predefiniti supportati per un elenco di implementazioni scoreAds
.
Per eseguire la selezione degli annunci senza chiamate di rete:
- Configurare il filtro degli annunci
- Creare annunci contestuali
Crea un oggetto
AdSelectionConfig
con il seguente codice:- Un elenco vuoto di acquirenti
- Un URI predefinito per selezionare l'offerta più alta
- Annunci contestuali
- Un URI vuoto per gli indicatori di punteggio. L'URI vuoto può indicare che non vuoi utilizzare il recupero di indicatori attendibili per il 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 degli annunci:
adSelectionManager.selectAds( adSelectionConfig, executor, outcomeReceiver);
Esegui il tuo codice JavaScript per i report utilizzando gli URI predefiniti
Attualmente, la piattaforma Privacy Sandbox dispone di un'implementazione JavaScript di base per i report solo per gli URI predefiniti. Se vuoi eseguire codice JavaScript dei report continuando a usare gli URI predefiniti per la selezione degli annunci a bassa latenza, puoi sostituire il valore DecisionLogicUri
tra la selezione degli annunci e le esecuzioni dei report.
- Esegui i passaggi per eseguire la selezione degli annunci per gli annunci contestuali che utilizzano URI predefiniti
Crea una copia del tuo
AdSelectionConfig
prima di eseguire il reportingadSelectionConfigWithYourReportingJS = adSelectionConfig.cloneToBuilder() // Replace <urlToFetchYourReportingJS> with your own URL: .setDecisionLogicUri(Uri.parse(<urlToFetchYourReportingJS>)) .build();
Eseguire il 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 mediazione a cascata
La mediazione con struttura a cascata richiede che più SDK di terze parti (reti di terze parti) siano orchestrati da una rete di mediazione SDK proprietaria. La mediazione con struttura a cascata viene eseguita allo stesso modo indipendentemente dal fatto che l'asta si sia svolta sul dispositivo o nei servizi di offerte e aste (B&A).
Reti di terze parti
Le reti di terze parti devono fornire un adattatore che consenta alla rete di mediazione di richiamare i metodi necessari per l'esecuzione di un'asta:
- Pubblica selezione degli annunci
- Impressioni del report
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() {...}
}
Ogni SDK ha i propri clienti e gestori dei servizi di selezione degli annunci e le proprie implementazioni di selectAds
e reportImpressions
. I provider di SDK possono consultare le sezioni su come eseguire la selezione degli annunci per le aste on-device o il documento esplicativo B&A per le aste B&A. Segui come segnalare le impressioni degli annunci (seguendo i singoli report sulle impressioni della SSP per la generazione di report.
Rete di mediazione
Analogamente alle reti di terze parti, le reti di mediazione richiedono implementazioni selectAds
e reportImpression
. Per ulteriori informazioni, consulta le sezioni su come eseguire la selezione degli annunci e su come generare report sulle impressioni degli annunci.
Le reti di mediazione sono responsabili dell'esecuzione della catena di mediazione e del loro posizionamento nella catena di mediazione. La prossima sezione spiega come impostare ed eseguire questo processo.
Recuperare la catena di mediazione e i prezzi minimi delle offerte
La rete di mediazione è responsabile del recupero degli annunci contestuali proprietari, della catena di mediazione e degli annunci minimi delle reti di terze parti. Ciò può accadere in una richiesta di recupero degli annunci contestuali eseguiti dalla rete di mediazione. 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 di asta come adSelectionSignals
.
Posizionamento nella rete nella catena di mediazione
Un SDK di mediazione può inserirsi nella catena di mediazione in base all'eCPM effettivo delle offerte per annunci proprietari. Nell'API Protected Audience, le offerte per gli annunci sono opache. Un SDK di mediazione deve utilizzare AdSelectionFromOutcomesConfig
per poter confrontare l'offerta di un determinato annuncio proprietario con l'offerta minima della rete di terze parti successiva nella catena. Se l'offerta proprietaria è superiore all'offerta minima, significa che l'SDK di mediazione viene posizionato davanti alla rete di terze parti.
Pubblica selezione degli annunci
Per recuperare un annuncio proprietario, la rete di mediazione può eseguire un'asta on-device seguendo i passaggi nella sezione Esegui selezione degli annunci. Ciò genera
un annuncio proprietario, un'offerta e un AdSelectionId
che vengono utilizzati nella procedura
di mediazione.
Crea un AdSelectionFromResultsConfig
Un AdSelectionFromOutcomesConfig
consente alla rete di mediazione di trasmettere un elenco di AdSelectionIds
(risultati delle aste precedenti), indicatori di selezione degli annunci e un URI per recuperare il codice JavaScript che seleziona un annuncio tra più candidati. L'elenco
di AdSelectionIds insieme alle relative offerte e agli indicatori viene passato al
JavaScript, che può restituire uno degli AdSelectionIds
se supera il prezzo minimo dell'offerta
o nessuno se la catena di mediazione deve continuare.
Le reti di mediazione creano un AdSelectionFromOutcomesConfig
utilizzando il AdSelectionId
proprietario della sezione precedente e il prezzo minimo per la rete di terze parti che viene presa 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 i seguenti
parametri obbligatori:
- Venditore: identificatore della rete pubblicitaria del venditore che avvia la selezione degli annunci.
- AdSelectionIds: un elenco singolo di un'esecuzione precedente di
selectAds()
per un annuncio proprietario. - 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 recuperata per la rete di terze parti specificata.
- URI della logica di selezione: un URL HTTPS su cui è stata eseguita una query durante la selezione degli annunci per recuperare il codice JavaScript della rete di mediazione per la selezione di un annuncio vincente. Vedi le firme delle funzioni richieste in questo codice JavaScript. JavaScript dovrebbe restituire
l'annuncio di terze parti se l'offerta è superiore all'offerta minima, altrimenti restituire
null
. In questo modo, l'SDK di mediazione può troncare la catena di mediazione quando viene trovato un vincitore.
Dopo aver creato AdSelectionOutcomesConfig
, chiama il metodo selectAds()
della rete di terze parti che si trova per prima nella 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 l'esecuzione del processo di mediazione.
- Esegui la selezione degli annunci proprietari.
- Eseguire l'iterazione sulla catena di mediazione. Per ogni rete di terze parti:
- Crea una
AdSelectionFromOutcomeConfig
che includa iloutcomeId
proprietario e l'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, restituisci l'annuncio.
- Crea una
- Se la catena non trova un 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 viene eseguita l'asta. Se hai una sola SSP che esegue un'asta, segui questa sezione. Se vuoi implementare la mediazione con struttura a cascata, segui la procedura descritta nella sezione dei report sulle impressioni della mediazione con struttura a cascata.
Report sulle singole impressioni della SSP
Dopo aver scelto l'annuncio vincente dal flusso di lavoro di selezione degli annunci, puoi
segnalare l'impressione alle piattaforme lato acquisti e Sell-Side Platform partecipanti
con il metodo AdSelectionManager.reportImpression()
. Per segnalare un'impressione dell'annuncio:
- Inizializza un oggetto
AdSelectionManager
. - Crea un oggetto
ReportImpressionRequest
con l'ID selezione degli annunci. - Richiama il metodo
reportImpression()
asincrono con l'oggettoReportImpressionRequest
e gli oggettiExecutor
eOutcomeReceiver
pertinenti.
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 i seguenti
parametri obbligatori:
- ID selezione annunci: un ID univoco di un utente del dispositivo che identifica una selezione di annunci riuscita.
- Configurazione della selezione degli annunci: la stessa configurazione utilizzata nella chiamata
selectAds()
identificata dall'ID selezione degli annunci fornito.
Il metodo reportImpression()
asincrono utilizza l'oggetto OutcomeReceiver
per segnalare il risultato della chiamata API.
- Il callback
onResult()
indica se gli URL dei report sulle impressioni sono stati creati 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,
AdServicesException
indicaIllegalArgumentException
come causa. - Tutti gli altri errori ricevono un elemento
AdServicesException
conIllegalStateException
come causa.
- Se la chiamata viene inizializzata con un argomento di input non valido,
Report sulle impressioni della mediazione con struttura a cascata
Un SDK di mediazione deve tenere traccia dell'SDK vincente per attivare i flussi di report. Gli SDK che partecipano a una catena di mediazione devono fornire al mediatore un metodo da richiamare per attivare il proprio flusso di report. Gli SDK che partecipano a un'asta con mediazione possono seguire i passaggi riportati sopra per implementare i propri report.
Le SSP possono usare questo esempio di codice dell'SDK di terze parti come prototipo per partecipare ai flussi di mediazione:
Pair<AdSelectionOutcome, NetworkAdapter> winnerOutcomeAndNetwork =
mediationSdk.orchestrateMediation(mediationChain);
if (winner.first.hasOutcome()) {
winner.second.reportImpressions(winner.first.getAdSelectionId());
Endpoint dei report sulle impressioni
L'API Report delle impressioni invia richieste HTTPS GET agli endpoint forniti dalla Sell-Side Platform e dalla Buy-Side Platform vincente:
Endpoint della piattaforma lato acquisti:
- L'API utilizza l'URL logica di offerta specificato nel segmento di pubblico personalizzato per recuperare il codice JavaScript fornito dall'acquirente che include la logica al fine di restituire un URL dei report sulle impressioni.
- Richiama la funzione JavaScript
reportWin()
, che dovrebbe restituire l'URL del report sulle impressioni dell'acquirente.
Endpoint della piattaforma lato vendita:
- Utilizza l'URL logica di decisione specificato nell'oggetto
AdSelectionConfig
per recuperare il codice JavaScript della logica di decisione del venditore. - Richiama la funzione JavaScript
reportResult()
, che dovrebbe restituire l'URL del report sulle impressioni dell'acquirente.
Report sui servizi di asta e offerta
Un'asta eseguita nei servizi di offerte e aste avrà tutte le informazioni dei report necessarie, inclusi gli URL generati per i report sulle interazioni con gli annunci, incluse nella risposta criptata dell'asta lato server. Quando la risposta viene decriptata, gli URL appropriati vengono registrati nella piattaforma e, di conseguenza, i report sulle impressioni e sugli annunci seguono gli stessi passaggi elencati sopra.
Report sulle impressioni con il massimo sforzo
Il metodo reportImpression()
è progettato per consentire il completamento della generazione di report secondo il criterio del "best effort".
Segnala interazioni con gli annunci
Protected Audience supporta la generazione di report sulle interazioni più granulari di un annuncio visualizzato. Ciò può includere interazioni come tempo di visualizzazione, clic, passaggi del mouse o qualsiasi altra metrica utile che è possibile raccogliere. La procedura per ricevere questi report prevede due passaggi. In primo luogo, acquirenti e venditori devono registrarsi per ricevere questi report nel codice JavaScript dei report. Successivamente, il cliente dovrà segnalare questi eventi.
Registrazione per ricevere eventi di interazione
La registrazione degli eventi di interazione viene eseguita nelle funzioni JavaScript reportResult()
dell'acquirente e del venditore reportWin()
utilizzando una funzione JavaScript fornita dalla piattaforma registerAdBeacon
. Per ricevere un
report su un evento, basta chiamare la funzione JavaScript della piattaforma
dal codice JavaScript dei report. Il seguente snippet utilizza reportWin()
di un acquirente, ma lo stesso approccio 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;
}
Segnalare gli eventi di interazione
Dopo aver segnalato un'impressione, i clienti possono segnalare le interazioni alle piattaforme lato acquisti e Sell-Side Platform registrate in precedenza con il metodo AdSelectionManager.reportInteraction()
. Per segnalare un evento relativo all'annuncio:
- Inizializza un oggetto
AdSelectionManager
. - Crea un oggetto
ReportInteractionRequest
con l'ID selezione degli annunci, la chiave di interazione, i dati sull'interazione e la destinazione del report. - Richiama il metodo
reportInteraction()
asincrono con l'oggettorequest
e gli 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 i seguenti
parametri obbligatori:
- ID selezione annunci: un ID selezione annuncio recuperato da un elemento
AdSelectionOutcome
restituito in precedenza. - Chiave di interazione: una chiave stringa definita dal client che descrive l'azione segnalata. Deve corrispondere alla chiave registrata dal venditore o dall'acquirente nelle funzioni JavaScript dei report.
- Dati di interazione: una stringa contenente dati da includere nel report sugli eventi da POSTARE ai server di reporting.
- Destinazioni report: una maschera di bit che specifica se gli eventi devono essere
segnalati all'acquirente, al venditore o a entrambi. Questi flag sono forniti dalla piattaforma e la maschera di destinazione finale può essere creata utilizzando operazioni a bit. Per generare report su una destinazione, puoi utilizzare il flag fornito direttamente dalla piattaforma. Per generare report per più destinazioni, puoi utilizzare l'operatore bit a bit (
|
) per combinare i valori dei flag.
Il metodo reportInteraction()
asincrono utilizza l'oggetto OutcomeReceiver
per segnalare il risultato della chiamata API.
- Il callback
onResult()
indica che la chiamata di interazione con il report è valida. - Il callback
onError()
indica le seguenti condizioni possibili:- Se la chiamata viene effettuata quando l'app è in esecuzione in background, viene restituito un
IllegalStateException
con una descrizione dell'errore. - Se il client viene limitato per chiamare
reportInteraction()
, viene restituito unLimitExceededException
. - Se il pacchetto non è registrato per chiamare le API Privacy Preserve, viene restituito un
SecurityException()
. - Se le interazioni con i report dell'app sono diverse dall'app che ha chiamato
selectAds()
, viene restituito unIllegalStateException
.
- Se la chiamata viene effettuata quando l'app è in esecuzione in background, viene restituito un
- Se l'utente non ha acconsentito ad abilitare le API Privacy Sandbox, la chiamata non andrà a buon fine e non verrà eseguita.
Endpoint dei report sull'interazione
L'API Report Interop invia richieste HTTPS POST agli endpoint forniti dalla Sell-Side Platform e dalla Buy-Side Platform vincente. Protected Audience corrisponderà le chiavi di interazione agli URI dichiarati nel codice JavaScript dei report e invierà una richiesta POST a ciascun endpoint per ogni interazione segnalata. Il tipo di contenuto della richiesta è in testo normale, mentre il corpo corrisponde ai dati sull'interazione.
Report sulle interazioni con il massimo sforzo
reportInteraction()
è progettato per consentire il completamento
con il massimo sforzo della generazione di report tramite HTTP POST.
Aggiornamento giornaliero in background
Quando crei un segmento di pubblico personalizzato, la tua app o il tuo SDK possono inizializzare i metadati dei segmenti di pubblico personalizzati. Inoltre, la piattaforma può aggiornare i seguenti metadati dei segmenti di pubblico personalizzati con una procedura di aggiornamento in background giornaliera.
- Indicatori di offerta utente
- Dati sulle offerte attendibili
AdData
elenco
Questo processo esegue query sull'URL di aggiornamento giornaliero definito nel segmento di pubblico personalizzato e l'URL potrebbe restituire una risposta JSON.
- La risposta JSON può contenere uno qualsiasi dei campi di metadati supportati che devono essere aggiornati.
- Ogni campo JSON viene convalidato in modo indipendente. Il client ignora tutti i campi non corretti, il che non comporta aggiornamenti a quel particolare campo nella risposta.
- Una risposta HTTP vuota o un oggetto JSON vuoto "
{}
" non comportano l'aggiornamento dei metadati. - Le dimensioni del messaggio di risposta devono essere limitate a 10 kB.
- Tutti gli URI sono obbligatori per l'utilizzo del protocollo 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 per la selezione degli annunci orchestra l'esecuzione del codice JavaScript fornito dall'acquirente e dal venditore.
Il codice JavaScript fornito dall'acquirente viene recuperato dall'URL della logica delle offerte specificato nel segmento di pubblico personalizzato. Il codice JavaScript restituito deve includere le seguenti funzioni:
Il codice JavaScript fornito dal venditore viene recuperato dall'URL della logica di decisione specificato nel
parametro AdSelectionConfig
per l'API di selezione degli annunci. Il codice JavaScript restituito deve 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'oggetto di configurazione dell'astacustom_audience_bidding_signals
: oggetto JSON generato dalla piattaforma. Il formato di 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 tratte dalle proprietà con lo stesso nome del segmento di pubblico personalizzato che partecipa alla selezione degli annunciactivation_time
eexpiration_time
indicano il tempo di attivazione e scadenza del segmento di pubblico personalizzato, espresso in secondi dall'epoca di Unix.ca_user_bidding_signals
è una stringa JSON specificata nel campouserBiddingSignals
dell'elementoCustomAudience
al momento della creazionetrusted_bidding_signals, contextual_signals
euser_signals
sono oggetti JSON. Vengono passati come oggetti vuoti e verranno riempiti nelle versioni future. Il loro formato non viene applicato dalla piattaforma ed è gestito dalla tecnologia pubblicitaria.
Risultato:
ad
: è l'annuncio a cui fa riferimento l'offerta. Lo script può restituire una copia dell'annuncio ricevuto con metadati diversi. La proprietàrender_url
dell'annuncio dovrebbe rimanere inalterata.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 degli indicatori di input non sia valido. Nel caso in cui l'offerta generate-bid restituisca un valore diverso da zero, il processo di offerta viene invalidato per tutti gli annunci dell'autorità di certificazione
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
: consulta la documentazione digenerateBid
bid
: il valore dell'offerta per l'annuncioad_selection_config
: un oggetto JSON che rappresenta il 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
: oggetti JSON letti dal parametro APIsellerSignals
AdSelectionConfig
trusted_scoring_signal
: lettura dal campoadSelectionSignals
nel parametro APIAdSelectionConfig
contextual_signals, user_signals
: oggetti JSON. Attualmente, vengono passati come oggetti vuoti e verranno riempiti nelle versioni future. Il loro formato non è applicato dalla piattaforma ed è gestito dalla tecnologia pubblicitaria.per_buyer_signals
: oggetto JSON letto dalla mappaperBuyerSignal
nel parametro APIAdSelectionConfig
utilizzando come chiave l'attuale acquirente del segmento di pubblico personalizzato. Vuota se la mappa non contiene voci per l'acquirente specificato.
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: nel caso in cui i
customAudienceSignals
non siano validi - 2: nel caso in cui
AdSelectionConfig
non sia 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 nell'oggetto di configurazione dell'asta
Output:
status
:0
per l'esito positivo, diverso da zero per gli erroriresult
: uno dei risultati trasmessi o nulli
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
: consulta la documentazione discoreAds
render_url
: l'URL di rendering dell'annuncio vincentebid
: l'offerta offerta per l'annuncio vincentecontextual_signals
: consulta la documentazione digenerateBid
Output:
status: 0
per l'esito positivo e un valore diverso da zero per gli erroriresults
: un oggetto JSON contenente:signals_for_buyer
: un oggetto JSON che viene passato alla funzionereportWin
reporting_url
: un URL utilizzato dalla piattaforma per notificare l'impressione all'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
: consulta la documentazione perscoreAd
signals_for_buyer
: un oggetto JSON restituito dareportResult
contextual_signals, custom_audience_signals
: consulta la documentazione pergenerateBid
Output:
status: 0
per l'esito positivo e un valore diverso da zero per gli erroriresults
: un oggetto JSON contenente:reporting_url
: un URL utilizzato dalla piattaforma per notificare l'impressione al venditore
registerAdBeacon()
function registerAdBeacon(
interaction_key,
reporting_uri
)
Parametri di input:
interaction_key
: una stringa che rappresenta l'evento. Questo viene utilizzato dalla piattaforma in un secondo momento quando vengono segnalate le interazioni degli eventi per cercare ilreporting_uri
che deve essere notificato. Questa chiave deve corrispondere a ciò che l'acquirente o il venditore sta registrando e ciò che il venditore sta segnalando.reporting_uri
: un URI per ricevere i report sugli eventi. Deve essere specifico per il tipo di evento segnalato. Deve accettare una richiesta POST per gestire tutti i dati segnalati insieme all'evento.
URI predefiniti per la selezione degli annunci
Gli URI predefiniti offrono agli ad tech la possibilità di designare le funzioni JavaScript per la logica decisionale per la selezione degli annunci nelle classi AdSelectionConfig
e AdSelectionFromOutcomesConfig
. Gli URI predefiniti non richiedono chiamate di rete
per scaricare il codice JavaScript corrispondente. Gli ad tech possono usare URI predefiniti
senza dover configurare un dominio registrato per ospitare 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 di questo URI nel runtime.
Viene generato un valore IllegalArgumentException
se:
- nessuno dei parametri richiesti è presente nell'URI
- sono presenti parametri non riconosciuti nell'URI
Casi d'uso e nomi degli URI predefiniti supportati
Caso d'uso 1: selezione di annunci
Gli URI predefiniti del caso d'uso ad-selection
sono supportati nel flusso selectAds(AdSelectionConfig)
.
Nome URI predefinito: highest-bid-wins
Questo URI predefinito fornisce un codice JavaScript che seleziona 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 del report di base è https://www.ssp.com/reporting
, l'URI predefinito sarà:
`ad-selection-prebuilt://ad-selection/highest-bid-wins/?reportingUrl=https://www.ssp.com/reporting`
Caso d'uso 2: ad-selection-from-outcomes
Gli URI predefiniti nel caso d'uso ad-selection-from-outcomes
supportano il flusso di lavoro selectAds(AdSelectionFromOutcomesConfig)
.
Nome URI predefinito: waterfall-mediation-truncation
L'URI predefinito waterfall-mediation-truncation
fornisce codice JavaScript che implementa la logica di troncamento della mediazione a cascata, in cui JavaScript restituisce un annuncio proprietario se bid
è maggiore o uguale a bid floor
e altrimenti restituisce null
.
Parametri obbligatori
bidFloor
: la chiave del valore minimo dell'offerta trasmesso nel getSelectionSignals()
che viene confrontata con l'annuncio dell'SDK di mediazione.
Utilizzo
Se gli indicatori di selezione degli annunci sono simili a {"bid_floor": 10}
, l'URI predefinito risultante sarà:
`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 app di esempio in Kotlin e Java, che puoi trovare su GitHub.
Prerequisiti
L'API Protected Audience richiede codice JavaScript durante la selezione degli annunci e i report sulle impressioni. Esistono due metodi per fornire questo codice JavaScript in un ambiente di test:
- Esegui un server con gli endpoint HTTPS richiesti che restituisca 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 i report sulle impressioni.
Endpoint HTTPS
Per testare la selezione degli annunci e i report sulle impressioni, devi configurare 7 endpoint HTTPS a cui può accedere il tuo emulatore o il tuo dispositivo di test:
- Endpoint dell'acquirente che pubblica il codice JavaScript della logica di offerta.
- Un endpoint che pubblica gli indicatori di offerta.
- Endpoint del venditore che pubblica il codice JavaScript della logica decisionale.
- Un endpoint che gestisce gli indicatori di punteggio.
- Endpoint del report sulle impressioni dell'acquirente vincente.
- Endpoint dei report sulle impressioni del venditore.
- Un endpoint per pubblicare gli aggiornamenti giornalieri per un segmento di pubblico personalizzato.
Per praticità, il repository GitHub fornisce codice JavaScript di base per lo scopo del test. Include inoltre le definizioni del servizio OpenAPI, di cui è possibile eseguire il deployment in una simulazione supportata o su una piattaforma di microservizi. Per maggiori dettagli, consulta il progetto README.
Esegui l'override del recupero remoto di JavaScript
Questa funzionalità è pensata per essere utilizzata per test end-to-end. Per eseguire l'override del recupero remoto, 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 seguente riga all'attributo nel tuo file AndroidManifest.xml:
<application
android:debuggable="true">
Per un esempio di come utilizzare questi override, consulta l'app di esempio dell'API Protected Audience su GitHub.
Devi aggiungere il tuo codice JavaScript personalizzato per gestire le routine di selezione degli annunci, ad esempio le offerte, le decisioni sui punteggi e i report. Puoi trovare esempi di codice JavaScript di base che gestiscono tutte le richieste richieste nel repository GitHub. L'applicazione di esempio dell'API Protected Audience dimostra come leggere il codice dal file e prepararlo per l'utilizzo come override.
È possibile eseguire l'override di JavaScript lato vendite e lato acquirente in modo indipendente, anche se è necessario un endpoint HTTPS per pubblicare qualsiasi codice JavaScript per cui non fornisci override. Leggi il file README per informazioni su come configurare un server per gestire questi casi.
È possibile eseguire l'override del recupero JavaScript solo per i segmenti di pubblico personalizzati di proprietà del tuo pacchetto.
Esegui override di JavaScript lato vendite
Per configurare un override di JavaScript lato vendita, segui questi passaggi come mostrato nell'esempio di codice riportato di seguito:
- Inizializza un oggetto
AdSelectionManager
. - Recupera un riferimento a
TestAdSelectionManager
dall'oggettoAdSelectionManager
. - Crea un oggetto
AdSelectionConfig
. - Crea un elemento
AddAdSelectionOverrideRequest
con l'oggettoAdSelectionConfig
e unString
che rappresenta il codice JavaScript che intendi utilizzare come override. - Richiama il metodo
overrideAdSelectionConfigRemoteInfo()
asincrono con l'oggettoAddAdSelectionOverrideRequest
e gli oggettiExecutor
eOutcomeReceiver
pertinenti.
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 la selezione degli annunci per ulteriori informazioni su ciò che ciascun campo della AdSelectionConfig
rappresenta. La differenza principale è che decisionLogicUrl può essere impostato su un valore segnaposto perché verrà ignorato.
Per eseguire l'override del codice JavaScript utilizzato durante la selezione degli annunci, decisionLogicJs
deve contenere le firme delle funzioni lato venditore appropriate.
Per un esempio di come leggere un file JavaScript come stringa, consulta
l'app di esempio dell'API Protected Audience su GitHub.
Il metodo overrideAdSelectionConfigRemoteInfo()
asincrono utilizza l'oggetto 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 logica di generazione dei report che hai trasmesso come override.
Il callback onError()
indica due possibili condizioni:
- Se viene tentata l'override con argomenti non validi,
AdServiceException
indicaIllegalArgumentException
come causa. - Se il tentativo di eseguire l'override viene eseguito con un'app non in esecuzione in modalità di debug con le opzioni sviluppatore abilitate,
AdServiceException
indicaIllegalStateException
come causa.
Reimpostare override lato vendite
Questa sezione presuppone che tu abbia eseguito l'override del codice JavaScript lato vendite e che tu abbia un riferimento a TestAdSelectionManager
e AdSelectionConfig
utilizzati nella sezione precedente.
Per reimpostare le sostituzioni per tutte le AdSelectionConfigs
:
- Richiama 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 archiviato in AdSelectionConfig
per tentare di recuperare il codice JavaScript richiesto.
Se la chiamata al numero resetAllAdSelectionConfigRemoteOverrides()
non va a buon fine, il callback
OutComeReceiver.onError()
fornisce un'AdServiceException
.
Se il tentativo di rimozione degli override viene eseguito con un'app non in esecuzione in modalità di debug e con le opzioni sviluppatore abilitate, AdServiceException
indica IllegalStateException
come causa.
Esegui override di JavaScript lato acquirente
- Segui la procedura per unirti a un segmento di pubblico personalizzato
- Crea una
AddCustomAudienceOverrideRequest
con l'acquirente e il nome del segmento di pubblico personalizzato da sostituire, oltre alla logica di offerta e ai dati che vuoi utilizzare come sostituzione. - Richiama il metodo
overrideCustomAudienceRemoteInfo()
asincrono con l'oggettoAddCustomAudienceOverrideRequest
e gli oggettiExecutor
eOutcomeReceiver
pertinenti
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 acquirente e nome sono gli stessi utilizzati per creare il segmento di pubblico personalizzato. Scopri di più su questi campi.
Inoltre, puoi specificare due parametri aggiuntivi:
biddingLogicJs
: JavaScript contenente la logica dell'acquirente che viene utilizzato durante la selezione degli annunci. Vedi le firme delle funzioni obbligatorie in questo codice JavaScript.trustedBiddingSignals
: indicatori di offerta da utilizzare durante la selezione degli annunci. A scopo di test, questa può essere una stringa vuota.
Il metodo overrideCustomAudienceRemoteInfo()
asincrono utilizza l'oggetto OutcomeReceiver
per segnalare il risultato della chiamata API.
Il callback onResult()
indica che l'override è stato applicato correttamente.
Le chiamate successive a selectAds()
utilizzano la logica di offerta e di generazione dei report che hai trasmesso come override.
Il callback onError()
indica due possibili condizioni.
- Se viene tentata l'override con argomenti non validi,
AdServiceException
indicaIllegalArgumentException
come causa. - Se il tentativo di eseguire l'override viene eseguito con un'app non in esecuzione in modalità di debug con le opzioni sviluppatore abilitate,
AdServiceException
indicaIllegalStateException
come causa.
Reimposta override lato acquirente
Questa sezione presuppone che tu abbia eseguito l'override del codice JavaScript lato acquirente e che tu abbia un riferimento a TestCustomAudienceManager
utilizzato nella sezione precedente.
Per reimpostare le sostituzioni per tutti i segmenti di pubblico personalizzati:
- Richiama il metodo
resetAllCustomAudienceOverrides()
asincrono con gli 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 lato acquirente, le chiamate successive a selectAds()
utilizzano qualsiasi elemento biddingLogicUrl
e trustedBiddingData
vengono memorizzati nel campo CustomAudience
per tentare di recuperare il codice
JavaScript richiesto.
Se la chiamata al numero resetCustomAudienceRemoteInfoOverride()
non va a buon fine, il callback
OutComeReceiver.onError()
fornisce un'AdServiceException
.
Se il tentativo di rimozione degli override viene eseguito con un'app non in esecuzione in modalità di debug e con le opzioni sviluppatore abilitate, la causa AdServiceException
indica IllegalStateException
come causa.
Imposta un server di reporting
Quando utilizzi gli override del recupero remoto, devi comunque configurare un server che il tuo dispositivo o l'emulatore possa raggiungere per rispondere agli eventi di reporting. Per il test è sufficiente un semplice endpoint che restituisca 200. Il repository GitHub include le definizioni del servizio OpenAPI di cui è possibile eseguire il deployment in una piattaforma di simulazione o microservizi supportata. Per maggiori dettagli, consulta il progetto README.
Quando cerchi le definizioni di OpenAPI, cerca il file reporting-server.json.
Questo file contiene un endpoint semplice che restituisce 200, che rappresenta un codice di risposta HTTP. Questo endpoint viene utilizzato durante il periodo selectAds()
e segnala
all'API Protected Audience che la generazione di report sulle impressioni è stata completata correttamente.
Funzionalità da testare
- Esercitati ad accedere, ad abbandonare e a configurare un segmento di pubblico personalizzato in base alle azioni precedenti dell'utente.
- Esercitati nell'avvio della selezione di annunci sul dispositivo tramite JavaScript ospitati da remoto.
- Osserva come l'associazione di un'app con impostazioni dei segmenti di pubblico personalizzati può influire sui risultati della selezione degli annunci.
- Report sulle impressioni dell'esercizio 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 ricevuto. Per conoscere le funzionalità in corso, leggi le note di rilascio.
Componente | Descrizione limite | Valore limite |
---|---|---|
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 dall'ora di creazione | 60 giorni | |
Scadenza massima di una CA dal suo tempo di attivazione | 60 giorni | |
Numero massimo di CA sul dispositivo | 4000 | |
Dimensione massima del nome della CA | 200 byte | |
Dimensione massima dell'URI di recupero giornaliero | 400 byte | |
Dimensione massima dell'URI della logica di offerta | 400 byte | |
Dimensione massima dei dati sulle offerte attendibili | 10 kB | |
Dimensione massima degli indicatori di offerta utente | 10 kB | |
Tariffa massima di chiamate per leaveCustomAudience per acquirente |
1 al secondo | |
Tariffa massima di chiamate per joinCustomAudience per acquirente |
1 al secondo | |
Recupero in background CA | Timeout connessione | 5 secondi |
Timeout lettura HTTP | 30 secondi | |
Dimensioni totali massime 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 lettura connessione | 5 secondi | |
Tempo massimo di esecuzione di AdSelection |
10 secondi | |
Tempo massimo di esecuzione delle offerte per CA in AdSelection |
5 secondi | |
Tempo massimo di esecuzione del punteggio in AdSelection |
5 secondi | |
Tempo massimo di esecuzione per acquirente in AdSelection |
Da definire | |
Dimensione massima degli indicatori di selezione degli annunci/del venditore/per acquirente | Da definire | |
Dimensioni massime degli script venditore/acquirente | Da definire | |
Percentuale massima di chiamate per selectAds |
1 QPS | |
Report sulle impressioni | Tempo minimo prima di rimuovere la selezione degli annunci dalla persistenza | 24 ore |
Numero massimo di selezioni di annunci per lo spazio di archiviazione | Da definire | |
Dimensione massima dell'URL di output dei 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 | |
Percentuale massima di 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 gli AdData in un'unica CA per scopi contestuali |
URL | Lunghezza massima di qualsiasi stringa URL presa come input | Da definire |
JavaScript | Tempo massimo di esecuzione | 1 secondo per offerte e punteggi per i report sulle impressioni |
Memoria massima utilizzata | 10 MB |
Segnala bug e problemi
Il tuo feedback è una parte fondamentale di Privacy Sandbox su Android. Comunicaci eventuali problemi riscontrati o 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