Gestore selezione annunci
public
class
AdSelectionManager
extends Object
java.lang.Object | |
↳ | android.adservices.adselection.AdSelectionManager |
AdSelection Manager fornisce API per SDK per app e annunci per eseguire processi di selezione degli annunci e generare report sulle impressioni.
Riepilogo
Metodi pubblici | |
---|---|
static
AdSelectionManager
|
get(Context context)
Metodo di sviluppo per la creazione di un'istanza di AdSelectionManager. |
void
|
getAdSelectionData(GetAdSelectionDataRequest request, Executor executor, OutcomeReceiver<GetAdSelectionDataOutcome, Exception> receiver)
Raccoglie dati sul pubblico personalizzati dal dispositivo. |
TestAdSelectionManager
|
getTestAdSelectionManager()
|
void
|
persistAdSelectionResult(PersistAdSelectionResultRequest request, Executor executor, OutcomeReceiver<AdSelectionOutcome, Exception> receiver)
Conserva i risultati della selezione di annunci dal lato server. |
void
|
reportEvent(ReportEventRequest request, Executor executor, OutcomeReceiver<Object, Exception> receiver)
Comunica al servizio la presenza di un nuovo evento da segnalare per l'annuncio selezionato
dall'esecuzione di selezione degli annunci identificata da |
void
|
reportImpression(ReportImpressionRequest request, Executor executor, OutcomeReceiver<Object, Exception> receiver)
Comunica al servizio che è presente una nuova impressione da segnalare per l'annuncio selezionato
dall'esecuzione di selezione degli annunci identificata da |
void
|
selectAds(AdSelectionFromOutcomesConfig adSelectionFromOutcomesConfig, Executor executor, OutcomeReceiver<AdSelectionOutcome, Exception> receiver)
Seleziona un annuncio dai risultati delle selezioni di annunci eseguite in precedenza. |
void
|
selectAds(AdSelectionConfig adSelectionConfig, Executor executor, OutcomeReceiver<AdSelectionOutcome, Exception> receiver)
Esegue il processo di selezione degli annunci sul dispositivo per selezionare un annuncio di remarketing per l'applicazione chiamante. |
void
|
updateAdCounterHistogram(UpdateAdCounterHistogramRequest updateAdCounterHistogramRequest, Executor executor, OutcomeReceiver<Object, Exception> outcomeReceiver)
Consente di aggiornare gli istogrammi del contatore per un annuncio precedentemente selezionato tramite una chiamata a |
Metodi ereditati | |
---|---|
Metodi pubblici
ricevi
public static AdSelectionManager get (Context context)
Metodo di sviluppo per la creazione di un'istanza di AdSelectionManager.
Parametri | |
---|---|
context |
Context : il valore di Context da utilizzare
Questo valore non può essere null . |
Ritorni | |
---|---|
AdSelectionManager |
Un'istanza AdSelectionManager
Questo valore non può essere null . |
getAdSelectionData
public void getAdSelectionData (GetAdSelectionDataRequest request, Executor executor, OutcomeReceiver<GetAdSelectionDataOutcome, Exception> receiver)
Raccoglie dati sul pubblico personalizzati dal dispositivo. Restituisce un blob compresso e criptato da inviare ai server di aste per la selezione degli annunci. Per ulteriori dettagli, consulta la sezione Spiegazione dei servizi di offerte e aste.
Gli annunci dei segmenti di pubblico personalizzati devono avere un ad_render_id
per essere idonei a essere raccolti.
Consulta la pagina AdSelectionManager#persistAdSelectionResult
per scoprire come elaborare i risultati della selezione degli annunci eseguita sul lato server con il blob generato da questa API.
L'output viene passato dal destinatario, che restituisce un GetAdSelectionDataOutcome
per un'esecuzione riuscita oppure un Exception
include il tipo di eccezione generata e il messaggio di errore corrispondente.
Se viene generato un valore IllegalArgumentException
, ciò è dovuto a un argomento di input non valido
che l'API ha ricevuto per eseguire la selezione degli annunci.
Se IllegalStateException
viene visualizzato con il messaggio di errore "Errore dei servizi di
selezione annunci", significa che il problema interno del servizio di selezione degli annunci non è riuscito.
Se viene visualizzato TimeoutException
, si verifica un timeout durante l'offerta, il punteggio o il processo di selezione complessivo per trovare un annuncio vincente.
Se viene lanciato LimitExceededException
, si verifica quando il pacchetto chiamante supera i limiti di frequenza consentiti ed è limitato.
Se viene generato il messaggio SecurityException
, si verifica quando il chiamante non è autorizzato
o non è richiesta l'autorizzazione.
Richiede AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE
Parametri | |
---|---|
request |
GetAdSelectionDataRequest : questo valore non può essere null . |
executor |
Executor : questo valore non può essere null .
Gli eventi di callback e di listener vengono inviati tramite questo
Executor , offrendo un modo semplice per controllare quale thread viene
utilizzato. Per inviare eventi tramite il thread principale della tua
applicazione, puoi utilizzare
Context.getMainExecutor() .
In caso contrario, specifica un Executor che verrà inviato al thread appropriato. |
receiver |
OutcomeReceiver : questo valore non può essere null . |
getTestAdSelectionManager
public TestAdSelectionManager getTestAdSelectionManager ()
Ritorni | |
---|---|
TestAdSelectionManager |
Questo valore non può essere null . |
PersistentAdSelectionResult
public void persistAdSelectionResult (PersistAdSelectionResultRequest request, Executor executor, OutcomeReceiver<AdSelectionOutcome, Exception> receiver)
Conserva i risultati della selezione di annunci dal lato server. Per ulteriori dettagli, consulta la sezione Spiegazione dei servizi di offerte e aste
Visita la pagina AdSelectionManager#getAdSelectionData
per scoprire come generare un blob criptato per eseguire una selezione di annunci sul lato server.
L'output viene passato dal destinatario, che restituisce un AdSelectionOutcome
per un'esecuzione riuscita oppure un Exception
include il tipo di eccezione generata e il
messaggio di errore corrispondente.
Se viene generato un valore IllegalArgumentException
, ciò è dovuto a un argomento di input non valido
che l'API ha ricevuto per eseguire la selezione degli annunci.
Se IllegalStateException
viene visualizzato con il messaggio di errore "Errore dei servizi di
selezione annunci", significa che il problema interno del servizio di selezione degli annunci non è riuscito.
Se viene visualizzato TimeoutException
, si verifica un timeout durante l'offerta, il punteggio o il processo di selezione complessivo per trovare un annuncio vincente.
Se viene lanciato LimitExceededException
, si verifica quando il pacchetto chiamante supera i limiti di frequenza consentiti ed è limitato.
Se viene generato il messaggio SecurityException
, si verifica quando il chiamante non è autorizzato
o non è richiesta l'autorizzazione.
Richiede AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE
Parametri | |
---|---|
request |
PersistAdSelectionResultRequest : questo valore non può essere null . |
executor |
Executor : questo valore non può essere null .
Gli eventi di callback e di listener vengono inviati tramite questo
Executor , offrendo un modo semplice per controllare quale thread viene
utilizzato. Per inviare eventi tramite il thread principale della tua
applicazione, puoi utilizzare
Context.getMainExecutor() .
In caso contrario, specifica un Executor che verrà inviato al thread appropriato. |
receiver |
OutcomeReceiver : questo valore non può essere null . |
reportEvent
public void reportEvent (ReportEventRequest request, Executor executor, OutcomeReceiver<Object, Exception> receiver)
Comunica al servizio la presenza di un nuovo evento da segnalare per l'annuncio selezionato
dall'esecuzione di selezione degli annunci identificata da adSelectionId
. Un evento dell'annuncio è qualsiasi occorrenza che si verifica a un annuncio associato all'elemento adSelectionId
specificato. Non vi è alcuna garanzia su quando verrà registrato l'evento relativo all'annuncio. Il reporting sugli eventi potrebbe subire ritardi e i report potrebbero essere raggruppati.
Utilizzando ReportEventRequest#getKey()
, il servizio recupererà il reportingUri
che è stato registrato in registerAdBeacon
. Consulta la documentazione di reportImpression(ReportImpressionRequest, Executor, OutcomeReceiver)
per maggiori dettagli su registerAdBeacon
. Successivamente, il servizio
collegherà ReportEventRequest#getData()
al corpo di una richiesta POST e
invierà la richiesta. Il corpo della richiesta POST avrà content-type
di text/plain
e i dati verranno trasmessi in charset=UTF-8
.
L'output viene passato dal destinatario, che restituisce un Object
vuoto per
un'esecuzione riuscita oppure un Exception
include il tipo di eccezione generata e il
messaggio di errore corrispondente.
Se IllegalArgumentException
viene generato, questo è dovuto a un argomento di input non valido
che l'API ha ricevuto per segnalare l'evento annuncio.
Se IllegalStateException
viene visualizzato con il messaggio di errore "Errore dei servizi di
selezione annunci", significa che il problema interno del servizio di selezione degli annunci non è riuscito.
Se viene lanciato LimitExceededException
, si verifica quando il pacchetto chiamante supera i limiti di frequenza consentiti ed è limitato.
Se viene generato il messaggio SecurityException
, si verifica quando il chiamante non è autorizzato
o non è richiesta l'autorizzazione.
Gli eventi verranno riportati al massimo una sola volta come tentativo migliore.
Richiede AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE
Parametri | |
---|---|
request |
ReportEventRequest : questo valore non può essere null . |
executor |
Executor : questo valore non può essere null . |
receiver |
OutcomeReceiver : questo valore non può essere null . |
Impressione report
public void reportImpression (ReportImpressionRequest request, Executor executor, OutcomeReceiver<Object, Exception> receiver)
Comunica al servizio che è presente una nuova impressione da segnalare per l'annuncio selezionato
dall'esecuzione di selezione degli annunci identificata da adSelectionId
. Non esiste alcuna garanzia su quando verrà registrata l'impressione. I report sulle impressioni potrebbero subire ritardi e i report potrebbero essere raggruppati.
Per calcolare l'URL dei report per il venditore vincente, il servizio recupera la logica JavaScript del venditore
dal AdSelectionConfig#getDecisionLogicUri()
che si trova all'indirizzo ReportImpressionRequest.getAdSelectionConfig()
. Quindi, il servizio esegue una delle
funzioni presenti nel codice JS del venditore chiamato reportResult
, fornendo indicatori on-device
e ReportImpressionRequest#getAdSelectionConfig()
come parametri di input.
La definizione della funzione di 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 } }; }
Per calcolare l'URL report dell'acquirente vincente, il servizio recupera la logica JavaScript dell'acquirente
vincente, che viene recuperata tramite il CustomAudience.getBiddingLogicUri()
dell'acquirente. Successivamente, il servizio esegue una delle funzioni presenti nel codice JS dell'acquirente chiamato reportWin
, fornendo indicatori on-device, signals_for_buyer
calcolati da reportResult
e campi specifici di ReportImpressionRequest#getAdSelectionConfig()
come parametri di input.
La definizione della funzione di reportWin
è:
function reportWin(ad_selection_signals, per_buyer_signals, signals_for_buyer,
contextual_signals, custom_audience_reporting_signals) { return {'status': 0, 'results':
{'reporting_url': reporting_url } }; }
Inoltre, acquirenti e venditori hanno la possibilità di registrarsi per ricevere report su specifici eventi relativi agli annunci. Per farlo, possono richiamare la funzione registerAdBeacon
fornita dalla piattaforma
all'interno di reportWin
e reportResult
, rispettivamente, per acquirenti e venditori.
La definizione della funzione di registerBeacon
è:
function registerAdBeacon(beacons)
, dove beacons
è un dito da stringa a coppie di stringhe
Per ogni evento relativo all'annuncio per cui un acquirente/venditore è interessato ai report, deve aggiungere una coppia event_key
: event_reporting_uri
alla dettatura beacons
, dove event_key
è un identificatore per quell'evento specifico. Questo event_key
deve corrispondere a
ReportEventRequest#getKey()
quando l'SDK richiama reportEvent(ReportEventRequest, Executor, OutcomeReceiver)
. Inoltre, ogni event_reporting_uri
deve essere analizzato correttamente in un Uri
. Questo
sarà il valore Uri
segnalato quando l'SDK richiama reportEvent(ReportEventRequest, Executor, OutcomeReceiver)
.
Dopo che l'acquirente/venditore ha aggiunto tutti gli abbinamenti per cui vuole ricevere eventi, può richiamare registerAdBeacon(beacons)
, dove beacons
è il nome del detto a cui ha aggiunto le coppie.
registerAdBeacon
genererà TypeError
nelle seguenti situazioni:
registerAdBeacon
viene chiamato più di una volta. Se questo errore viene rilevato in reportWin/reportResult, verrà registrato l'insieme originale di abbinamentiregisterAdBeacon
non ha esattamente un argomento dict.- I contenuti dell'argomento 1 dict non sono tutti abbinamenti
String: String
.
L'output viene passato da receiver
, che restituisce un Object
vuoto per un'esecuzione riuscita oppure un Exception
include il tipo di eccezione generata e il messaggio di errore corrispondente.
Se viene generato un valore IllegalArgumentException
, questo è dovuto a un argomento di input non valido
ricevuto dall'API per segnalare l'impressione.
Se IllegalStateException
viene visualizzato con il messaggio di errore "Errore dei servizi di
selezione annunci", significa che il problema interno del servizio di selezione degli annunci non è riuscito.
Se viene lanciato LimitExceededException
, si verifica quando il pacchetto chiamante supera i limiti di frequenza consentiti ed è limitato.
Se viene generato il messaggio SecurityException
, si verifica quando il chiamante non è autorizzato
o non è richiesta l'autorizzazione.
Le impressioni verranno registrate al massimo una sola volta come tentativo migliore.
Richiede AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE
Parametri | |
---|---|
request |
ReportImpressionRequest : questo valore non può essere null . |
executor |
Executor : questo valore non può essere null . |
receiver |
OutcomeReceiver : questo valore non può essere null . |
selectAds
public void selectAds (AdSelectionFromOutcomesConfig adSelectionFromOutcomesConfig, Executor executor, OutcomeReceiver<AdSelectionOutcome, Exception> receiver)
Seleziona un annuncio dai risultati delle selezioni di annunci eseguite in precedenza.
L'input adSelectionFromOutcomesConfig
è fornito dall'SDK per gli annunci e l'oggetto AdSelectionFromOutcomesConfig
viene trasferito tramite una chiamata a Binder. Per questo motivo, la dimensione totale di questi oggetti è vincolata alle limitazioni degli IPC Android. Se il trasferimento non viene eseguito,
AdSelectionFromOutcomesConfig
genererà un TransactionTooLargeException
.
L'output viene passato dal destinatario, che restituisce un AdSelectionOutcome
per un'esecuzione riuscita oppure un Exception
include il tipo di eccezione generata e il
messaggio di errore corrispondente.
L'input adSelectionFromOutcomesConfig
contiene:
Seller
deve essere unAdTechIdentifier
registrato. In caso contrario, verrà lanciatoIllegalStateException
.List of ad selection ids
deve esistere e provenire da chiamateselectAds(AdSelectionConfig, Executor, OutcomeReceiver)
provenienti dalla stessa applicazione. In caso contrario,IllegalArgumentException
per la convalida dell'input aumenterà gli ID di selezione degli annunci in violazione della scheda.Selection logic URI
che potrebbero seguire gli schemi HTTPS o predefiniti di selezione degli annunci.Se l'URI segue lo schema HTTPS, l'host deve corrispondere a
seller
. In caso contrario, verrà lanciatoIllegalArgumentException
.Gli URI predefiniti sono un modo per sostituire una logica predefinita generica con i JavaScript richiesti per
selectOutcome
. L'URI predefinito per questo endpoint deve seguire:ad-selection-prebuilt://ad-selection-from-outcomes/<name>?<script-generation-parameters>
Se viene trasmesso un URI predefinito non supportato o se la funzionalità dell'URI predefinito viene disabilitata dal servizio, verrà restituito
IllegalArgumentException
.Consulta
AdSelectionFromOutcomesConfig.Builder#setSelectionLogicUri
per le<name>
supportate e le<script-generation-parameters>
richieste.
Se viene generato un valore IllegalArgumentException
, ciò è dovuto a un argomento di input non valido
che l'API ha ricevuto per eseguire la selezione degli annunci.
Se IllegalStateException
viene visualizzato con il messaggio di errore "Errore dei servizi di
selezione annunci", significa che il problema interno del servizio di selezione degli annunci non è riuscito.
Se viene visualizzato TimeoutException
, si verifica un timeout durante l'offerta, il punteggio o il processo di selezione complessivo per trovare un annuncio vincente.
Se viene lanciato LimitExceededException
, si verifica quando il pacchetto chiamante supera i limiti di frequenza consentiti ed è limitato.
Se viene generato il messaggio SecurityException
, si verifica quando il chiamante non è autorizzato
o non è richiesta l'autorizzazione.
Richiede AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE
Parametri | |
---|---|
adSelectionFromOutcomesConfig |
AdSelectionFromOutcomesConfig : questo valore non può essere null . |
executor |
Executor : questo valore non può essere null .
Gli eventi di callback e di listener vengono inviati tramite questo
Executor , offrendo un modo semplice per controllare quale thread viene
utilizzato. Per inviare eventi tramite il thread principale della tua
applicazione, puoi utilizzare
Context.getMainExecutor() .
In caso contrario, specifica un Executor che verrà inviato al thread appropriato. |
receiver |
OutcomeReceiver : questo valore non può essere null . |
selectAds
public void selectAds (AdSelectionConfig adSelectionConfig, Executor executor, OutcomeReceiver<AdSelectionOutcome, Exception> receiver)
Esegue il processo di selezione degli annunci sul dispositivo per selezionare un annuncio di remarketing per l'applicazione chiamante.
L'input adSelectionConfig
è fornito dall'SDK per gli annunci e l'oggetto AdSelectionConfig
viene trasferito tramite una chiamata a Binder. Per questo motivo, la dimensione totale di questi oggetti è vincolata alle limitazioni degli IPC per Android. Se il trasferimento non viene effettuato, AdSelectionConfig
genererà un TransactionTooLargeException
.
L'input adSelectionConfig
contiene Decision Logic Uri
che potrebbe seguire
gli schemi HTTPS o predefiniti di selezione degli annunci.
Se l'URI segue lo schema HTTPS, l'host deve corrispondere a seller
. In caso contrario, verrà lanciato
IllegalArgumentException
.
Gli URI predefiniti sono un modo per sostituire una logica predefinita generica con i JavaScript richiesti per scoreAds
. L'URI predefinito per questo endpoint deve seguire:
ad-selection-prebuilt://ad-selection/<name>?<script-generation-parameters>
Se viene trasmesso un URI predefinito non supportato o se la funzionalità dell'URI predefinito viene disabilitata dal
servizio, verrà restituito IllegalArgumentException
.
Consulta AdSelectionConfig.Builder#setDecisionLogicUri
per le <name>
supportate e
le <script-generation-parameters>
richieste.
L'output viene passato dal destinatario, che restituisce un AdSelectionOutcome
per un'esecuzione riuscita oppure un Exception
include il tipo di eccezione generata e il
messaggio di errore corrispondente.
Se viene generato un valore IllegalArgumentException
, ciò è dovuto a un argomento di input non valido
che l'API ha ricevuto per eseguire la selezione degli annunci.
Se IllegalStateException
viene visualizzato con il messaggio di errore "Errore dei servizi di
selezione annunci", significa che il problema interno del servizio di selezione degli annunci non è riuscito.
Se viene visualizzato TimeoutException
, si verifica un timeout durante l'offerta, il punteggio o il processo di selezione complessivo per trovare un annuncio vincente.
Se viene lanciato LimitExceededException
, si verifica quando il pacchetto chiamante supera i limiti di frequenza consentiti ed è limitato.
Se viene generato il messaggio SecurityException
, si verifica quando il chiamante non è autorizzato
o non è richiesta l'autorizzazione.
Richiede AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE
Parametri | |
---|---|
adSelectionConfig |
AdSelectionConfig : questo valore non può essere null . |
executor |
Executor : questo valore non può essere null .
Gli eventi di callback e di listener vengono inviati tramite questo
Executor , offrendo un modo semplice per controllare quale thread viene
utilizzato. Per inviare eventi tramite il thread principale della tua
applicazione, puoi utilizzare
Context.getMainExecutor() .
In caso contrario, specifica un Executor che verrà inviato al thread appropriato. |
receiver |
OutcomeReceiver : questo valore non può essere null . |
aggiorna Istogramma ContatoreAnnunci
public void updateAdCounterHistogram (UpdateAdCounterHistogramRequest updateAdCounterHistogramRequest, Executor executor, OutcomeReceiver<Object, Exception> outcomeReceiver)
Consente di aggiornare gli istogrammi del contatore per un annuncio precedentemente selezionato tramite una chiamata a selectAds(android.adservices.adselection.AdSelectionConfig, java.util.concurrent.Executor, android.os.OutcomeReceiver)
.
Gli istogrammi dei contatori vengono utilizzati nella selezione degli annunci per fornire informazioni sul filtro della quota limite sugli annunci candidati, in cui gli annunci le cui quote limite vengono raggiunte o superate vengono rimossi dal processo di offerta durante la selezione degli annunci.
Gli istogrammi dei contatori possono essere aggiornati solo per gli annunci specificati dal valore adSelectionId
specificato restituito da una chiamata recente alla selezione di annunci FLEDGE dalla stessa app chiamante.
Un SecurityException
viene restituito tramite outcomeReceiver
se:
- l'app non ha dichiarato le autorizzazioni corrette nel file manifest; oppure
- L'app o l'entità identificata da
callerAdTechIdentifier
non è autorizzata a utilizzare l'API.
IllegalStateException
tramite outcomeReceiver
se la chiamata non
proviene da un'app con un'attività in primo piano.
Un LimitExceededException
viene restituito tramite outcomeReceiver
se la chiamata supera la limitazione dell'API dell'app di chiamata.
In tutti gli altri casi di errore, outcomeReceiver
restituirà un valore Object
vuoto. Tieni presente che, al fine di proteggere la privacy degli utenti, gli errori interni non verranno restituiti tramite
un'eccezione.
Richiede AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE
Parametri | |
---|---|
updateAdCounterHistogramRequest |
UpdateAdCounterHistogramRequest : questo valore non può essere null . |
executor |
Executor : questo valore non può essere null .
Gli eventi di callback e di listener vengono inviati tramite questo
Executor , offrendo un modo semplice per controllare quale thread viene
utilizzato. Per inviare eventi tramite il thread principale della tua
applicazione, puoi utilizzare
Context.getMainExecutor() .
In caso contrario, specifica un Executor che verrà inviato al thread appropriato. |
outcomeReceiver |
OutcomeReceiver : questo valore non può essere null . |