Gestore selezione annunci

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:

1. registerAdBeaconviene chiamato più di una volta. Se questo errore viene rilevato in reportWin/reportResult, verrà registrato l'insieme originale di abbinamenti
2. registerAdBeacon non ha esattamente un argomento dict.
3. 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 un AdTechIdentifier registrato. In caso contrario, verrà lanciato IllegalStateException.
• List of ad selection ids deve esistere e provenire da chiamate selectAds(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à lanciato IllegalArgumentException.

  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:

1. l'app non ha dichiarato le autorizzazioni corrette nel file manifest; oppure
2. L'app o l'entità identificata da callerAdTechIdentifier non è autorizzata a utilizzare l'API.

Viene restituito un 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.