Guida per gli sviluppatori dell'API Protected Audience

Mentre leggi la documentazione di Privacy Sandbox su Android, utilizza il pulsante Anteprima per sviluppatori o Beta per selezionare la versione del programma con cui stai lavorando, poiché le istruzioni possono variare.

L'API Protected Audience su Android (in precedenza nota come FLEDGE) include l'API Custom Audience e l'API Ad Selection. Le piattaforme di tecnologia pubblicitaria e gli inserzionisti possono utilizzare queste API per pubblicare annunci personalizzati in base al coinvolgimento precedente con le app, il che limita la condivisione degli identificatori tra le app e 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 associarvi annunci pertinenti. Queste informazioni vengono memorizzate localmente e possono essere utilizzate per fornire informazioni sulle offerte, sul filtro e sul rendering degli annunci degli inserzionisti.

L'API Ad Selection fornisce un framework che consente a più sviluppatori di eseguire un'asta localmente per un segmento di pubblico personalizzato. Per raggiungere questo obiettivo, il sistema prende in considerazione gli annunci pertinenti associati al segmento di pubblico personalizzato ed esegue un'ulteriore elaborazione degli annunci restituiti al dispositivo da una piattaforma ad tech.

Le piattaforme di tecnologia pubblicitaria possono integrare queste API per implementare il remarketing che preserva la privacy degli utenti. Il supporto di altri casi d'uso, inclusi gli annunci per l'installazione di app, è previsto per le release future. Scopri di più sull'API Protected Audience su Android nella proposta di design.

Questa guida descrive come utilizzare l'API Protected Audience su Android per:

1. Gestire i segmenti di pubblico personalizzati
2. Configurare ed eseguire la selezione degli annunci su un dispositivo
3. Segnalare le impressioni degli annunci

Prima di iniziare

Prima di iniziare, completa quanto segue:

1. Configura l'ambiente di sviluppo per Privacy Sandbox su Android.
2. Installa un'immagine di sistema su un dispositivo supportato o configura un emulatore che includa il supporto di Privacy Sandbox su Android.

3. In un terminale, abilita l'accesso all'API Protected Audience (disattivata per impostazione predefinita) con il seguente comando adb.

     adb shell device_config put adservices ppapi_app_allow_list \"*\"
   

4. In un terminale, attiva i report sui beacon con i seguenti comandi adb.

    adb shell device_config put adservices fledge_beacon_reporting_metrics_enabled true
    adb shell device_config put adservices fledge_register_ad_beacon_enabled true
   

5. Includi un'autorizzazione ACCESS_ADSERVICES_CUSTOM_AUDIENCE nel manifest dell'app:

     <uses-permission android:name="android.permission.ACCESS_ADSERVICES_CUSTOM_AUDIENCE" />
   

6. Fai riferimento a una configurazione dei servizi pubblicitari nell'elemento <application> del tuo file manifest:

     <property android:name="android.adservices.AD_SERVICES_CONFIG"
               android:resource="@xml/ad_services_config" />
   

7. Specifica la risorsa XML dei servizi pubblicitari a cui fai riferimento nel manifest, ad esempiores/xml/ad_services_config.xml. Scopri di più sulle autorizzazioni dei servizi pubblicitari e sul controllo dell'accesso degli SDK.

     <ad-services-config>
       <custom-audiences allowAllToAccess="true" />
     </ad-services-config>
   

8. Per impostazione predefinita, l'API di selezione degli annunci applica limiti alla quantità massima di memoria che uno script di generazione di report sulle aste o sulle impressioni può allocare. La funzionalità di limitazione della memoria richiede WebView versione 105.0.5195.58 o successive. La piattaforma applica un controllo della versione e le chiamate alle API selectAds e reportImpression non vanno a buon fine se questo requisito non è soddisfatto. Esistono due opzioni per configurare questa opzione:

   • Opzione 1: esegui il seguente comando adb per disattivare questo controllo:

     adb device_config put fledge_js_isolate_enforce_max_heap_size false
     

   • Opzione 2: installa WebView Beta dal Google Play Store. Deve essere uguale o superiore alla versione indicata in precedenza.

Partecipare a un segmento di pubblico personalizzato

Un segmento di pubblico personalizzato rappresenta un gruppo di utenti con intenzioni o interessi comuni, come stabilito da un'app dell'inserzionista. Un'app o un SDK può utilizzare un segmento di pubblico personalizzato per indicare un pubblico specifico, ad esempio un utente che ha lasciato degli articoli nel carrello degli acquisti. Per creare o partecipare a un segmento di pubblico personalizzato in modo asincrono:

1. Inizializza l'oggetto CustomAudienceManager.
2. Crea un oggetto CustomAudience specificando parametri chiave come il pacchetto dell'acquirente e un nome pertinente. Quindi, inizializza l'oggetto JoinCustomAudienceRequest con l'oggetto CustomAudience.
3. Chiama joinCustomAudience() asincrono con l'oggetto JoinCustomAudienceRequest e gli oggetti Executor e OutcomeReceiver pertinenti.

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)

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 ogni oggetto CustomAudience su un dispositivo:

• owner: nome del pacchetto dell'app proprietaria. Viene 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 un identificatore arbitrario per il segmento di pubblico personalizzato.

La chiamata ripetuta di joinCustomAudience() con un'istanza diversa di CustomAudience aggiorna qualsiasi CustomAudience esistente con parametri owner, buyer e name corrispondenti. Per contribuire a preservare la privacy, il risultato dell'API non distingue tra "creazione" e "aggiornamento".

Inoltre, CustomAudience deve essere creato con i seguenti parametri obbligatori:

• URL di aggiornamento giornaliero: un URL HTTPS su cui viene eseguita una query giornaliera in background per aggiornare gli indicatori di offerta per gli utenti e i dati di offerta attendibili di un segmento di pubblico personalizzato, nonché gli URL di rendering e i metadati per gli annunci.
• URL della logica di offerta: un URL HTTPS sottoposto a query durante la selezione degli annunci per recuperare la logica di offerta JavaScript di un acquirente. Consulta le signature delle funzioni richieste in questo codice JavaScript.
• ID di 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:

• Data e ora di attivazione: un segmento di pubblico personalizzato può partecipare alla selezione degli annunci e agli aggiornamenti giornalieri solo dopo la data e l'ora di attivazione. Ad esempio, può essere utile per coinvolgere gli utenti inattivi di un'app.
• Data e ora di scadenza: una data e un'ora future dopo le quali il segmento di pubblico personalizzato viene rimosso dal dispositivo.
• Indicatori per le offerte per gli utenti: una stringa JSON contenente indicatori per gli utenti, come la lingua preferita dell'utente, che viene utilizzata dalla logica di offerta JavaScript di un acquirente per generare offerte durante la procedura di selezione degli annunci. Questo formato consente alle piattaforme di ad tech di riutilizzare il codice su più piattaforme e semplifica il consumo nelle funzioni JavaScript.
• Dati di offerta attendibili: un URL HTTPS e un elenco di stringhe utilizzate durante la procedura di selezione degli annunci che recuperano gli indicatori di offerta da un servizio Key/Value attendibile.
• Annunci: un elenco di oggetti AdData corrispondenti agli annunci che partecipano alla selezione degli annunci. Ogni oggetto AdData è 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 da utilizzare dalla logica di offerta dell'acquirente durante la procedura di selezione degli annunci.
  • Filtri annunci: una classe che contiene tutte le informazioni necessarie per il filtro degli annunci di installazione di app e la limitazione della frequenza durante la selezione degli annunci.

Ecco un esempio di istanza di oggetto CustomAudience:

// 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()

// Minimal initialization of a CustomAudience object
CustomAudience customAudience = CustomAudience.Builder()
    .setBuyer(AdTechIdentifier.fromString("my.buyer.domain.name"))
    .setName("example-custom-audience-name")
    .setDailyUpdateUrl(Uri.parse("https://DAILY_UPDATE_URL"))
    .setBiddingLogicUrl(Uri.parse("https://BIDDING_LOGIC_URL"))
    .build();

Gestire i risultati di joinCustomAudience()

Il metodo joinCustomAudience() asincrono utilizza l'oggetto OutcomeReceiver per segnalare il risultato della chiamata all'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 un IllegalArgumentException come causa.
  • Tutti gli altri errori ricevono un AdServicesException con IllegalStateException come causa.

Ecco un esempio di gestione dell'esito di joinCustomAudience():

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)
    }
};

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);
    }
};

Lasciare 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 un CustomAudience in base ai suoi parametri unici:

1. Inizializza l'oggetto CustomAudienceManager.
2. Inizializza LeaveCustomAudienceRequest con buyer e name del segmento di pubblico personalizzato. Per scoprire di più su questi campi di immissione, consulta "Unisci un segmento di pubblico personalizzato".
3. Chiama il metodo leaveCustomAudience() asincrono con l'oggetto LeaveCustomAudienceRequest e gli oggetti Executor e OutcomeReceiver pertinenti.

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)

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 di joinCustomAudience(), OutcomeReceiver indica la fine di una chiamata API. Per contribuire a proteggere la privacy, un esito di errore non distingue tra errori interni e argomenti non validi. Il callback onResult() viene chiamato al termine della chiamata all'API, indipendentemente dal fatto che un segmento di pubblico personalizzato corrispondente sia stato rimosso correttamente o meno.

Esegui selezione degli annunci

Per utilizzare l'API Protected Audience per selezionare gli annunci, chiama il metodo selectAds():

1. Inizializza un oggetto AdSelectionManager.
2. Crea un oggetto AdSelectionConfig.
3. Chiama il metodo selectAds() asincrono con l'oggetto AdSelectionConfig e gli oggetti Executor e OutcomeReceiver pertinenti.

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
)

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 della logica decisionale: un URL HTTPS su cui è stata eseguita una query per ottenere la logica JavaScript della rete pubblicitaria del venditore.
  • URL HTTPS: viene eseguito un query per ottenere la logica JavaScript della Rete pubblicitaria del venditore. Consulta le signature delle funzioni richieste.
  • URI predefinito: segue il formato di selezione degli annunci di FLEDGE. Viene generato un errore IllegalArgumentException se viene passato un URI precompilato non supportato o con formato errato.
• Acquirenti di segmenti di pubblico personalizzati: un elenco completo di identificatori per le reti pubblicitarie dell'acquirente autorizzate dal venditore a partecipare alla procedura di selezione degli annunci. Questi identificatori dell'acquirente corrispondono al CustomAudience.getBuyer() dei segmenti di pubblico personalizzati partecipanti.

Facoltativamente, è possibile specificare i seguenti parametri per una selezione degli annunci più personalizzata:

• Indicatori di selezione degli annunci: un oggetto JSON, serializzato come stringa, contenente indicatori da utilizzare dalla logica di offerta dell'acquirente JavaScript recuperata da CustomAudience.getBiddingLogicUrl().
• Indicatori del venditore: un oggetto JSON, serializzato come stringa, contenente gli indicatori utilizzati dalla logica decisionale JavaScript recuperata dal venditore da AdSelectionConfig.getDecisionLogicUrl().
• Indicatori per acquirente: una mappa di oggetti JSON, serializzati come stringhe, contenenti indicatori da utilizzare nella logica di offerta JavaScript di acquirenti specifici recuperati da CustomAudience.getBiddingLogicUrl(), identificati dai campi acquirente dei segmenti di pubblico personalizzati partecipanti.
• Annunci contestuali: una raccolta di annunci candidati raccolti direttamente dagli acquirenti durante un'asta al di fuori di un'asta Protected Audience.

Una volta selezionato un annuncio, i risultati, le offerte e gli indicatori vengono mantenuti internamente per i report. Il callback OutcomeReceiver.onResult() restituisce un AdSelectionOutcome contenente:

• Un URL di rendering dell'annuncio vincente, ottenuto da AdData.getRenderUrl().
• Un ID selezione annunci univoco per l'utente del dispositivo. Questo ID viene utilizzato per registrare l'impressione dell'annuncio.

Se la selezione degli annunci non può essere completata correttamente per motivi quali argomenti non validi, timeout o 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 indica IllegalArgumentException come causa.
• Tutti gli altri errori ricevono un AdServicesException con IllegalStateException come causa.

Annunci contestuali

Protected Audience può incorporare annunci contestuali in un'asta protetta. Gli annunci contestuali devono essere selezionati sul server di tecnologia pubblicitaria e restituiti al dispositivo al di fuori delle API Protected Audience. Gli annunci contestuali possono quindi essere inclusi nella gara utilizzando AdSelectionConfig, a quel punto funzionano come gli annunci sul dispositivo, inclusa l'idoneità al filtro degli annunci negativi. Una volta completata l'asta Protected Audience, devi invocare reportImpression(). Viene chiamato reportWin() nell'annuncio contestuale vincente, nello stesso schema dei report sulle impressioni, per ricevere l'annuncio vincente su un dispositivo. Ogni annuncio contestuale richiede un acquirente, un'offerta, un link alla logica di generazione di report, un URL di rendering e i metadati dell'annuncio.

Per eseguire il deployment degli annunci contestuali in-app, l'app di destinazione deve creare un oggetto ContextualAds:

val contextualAds: ContextualAds =
  Builder().setBuyer(AdTechIdentifier.fromString(mBiddingLogicUri.getHost()))
    //Pass in your valid app install ads
    .setDecisionLogicUri(mContextualLogicUri)
    .setAdsWithBid(appInstallAd)
    .build()

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 passato durante la creazione di AdSelectionConfig:

// 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)

// 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 che sono già installate su un dispositivo.

Il primo passaggio di questa procedura consiste nel definire quali inserzionisti hanno la possibilità di filtrare in base al pacchetto installato. Questo deve avvenire nell'app che vuoi scegliere come target per un annuncio.

//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)
    }
  })

//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 passati possono eliminare le app installate che specifichi 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 dell'inserzionista.

Il passaggio successivo consiste nel configurare il filtro degli annunci all'interno dell'app del publisher. La parte che pubblica l'annuncio all'interno dell'app del publisher (molto probabilmente un SDK lato offerta) deve inizializzare l'oggetto AdFilters con le informazioni sugli annunci correlati alle app che vuole escludere:

// Instantiate AdFilters object with package names.
val filters: AdFilters = Builder().setAppInstallFilters(
    Builder().setPackageNames(setOf("example.target.app")).build()
  ).build()

// 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 della domanda possono anche impostare un AdFilter per gli annunci presenti all'interno dei loro segmenti di pubblico personalizzati.

AdFilters può essere passato anche al momento dell'inizializzazione di un nuovo oggetto AdData:

// 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()

// 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 delle quote limite

Il filtro della quota limite consente agli esperti di tecnologia pubblicitaria di limitare il numero di volte in cui viene mostrato un annuncio. Il filtro della quota limite riduce la sovraesposizione degli annunci e ottimizza la selezione degli annunci alternativi per una determinata campagna pubblicitaria.

Un filtro di limite di frequenza è costituito da due componenti principali: il tipo di evento correlato all'annuncio e la chiave del contatore degli annunci. I tipi di eventi correlati agli annunci disponibili sono:

• Win: un evento win indica che l'annuncio ha vinto un'asta. Gli eventi Win vengono aggiornati automaticamente dall'API Protected Audience e non possono essere chiamati direttamente dallo sviluppatore. I dati sulle conversioni sono visibili solo per gli annunci all'interno di un determinato segmento di pubblico personalizzato.
• Impressione: separato da reportImpression, un chiamante on-device (SSP o MMP) utilizza updateAdCounterHistogram() per richiamare gli eventi di impressione nel punto del codice che preferisce. Gli eventi impressioni sono visibili a tutti gli annunci appartenenti a una determinata DSP e non sono limitati agli annunci nello stesso segmento di pubblico personalizzato.
• Visualizza: l'evento viene invocato dall'utente chiamante sul dispositivo (SSP o MMP) in un punto del codice scelto utilizzando una chiamata a updateAdCounterHistogram(). Gli eventi di visualizzazione sono visibili a tutti gli annunci appartenenti a una determinata piattaforma di scambio pubblicitario e non sono limitati agli annunci nello stesso segmento di pubblico personalizzato.
• Clic: l'evento viene invocato dall'utente chiamante on-device (SSP o MMP) in un punto del codice scelto utilizzando una chiamata a updateAdCounterHistogram(). Gli eventi di clic sono visibili a tutti gli annunci appartenenti a una determinata DSP e non sono limitati agli annunci nello stesso segmento di pubblico personalizzato.

Nell'app del publisher, una SSP o una MMP presente sul dispositivo richiama gli eventi correlati agli annunci. Quando viene chiamato updateAdCounterHistogram(), il contatore di un filtro della quota limite viene incrementato in modo che le aste future dispongano di informazioni aggiornate sull'esposizione di un utente a un determinato annuncio. I tipi di eventi correlati agli annunci non sono obbligatoriamente legati all'azione utente corrispondente e sono linee guida fornite per aiutare gli utenti chiamanti a strutturare il proprio sistema di eventi. Per incrementare i contatori degli annunci al momento di un evento, l'attore on-device fornisce l'ID selezione dell'annuncio dell'asta vincente.

Le chiavi del contatore degli annunci sono numeri interi con segno di 32 bit arbitrari assegnati da una tecnologia pubblicitaria dell'acquirente e corrispondono a un determinato insieme di annunci come definito dalla DSP. Poiché le chiavi del contatore degli annunci sono limitate solo agli annunci che appartengono a un determinato DSP, possono essere selezionate senza sovrapposizioni con le tabelle di distribuzione di un'altra tecnologia pubblicitaria. Le chiavi del contatore degli annunci vengono utilizzate per incrementare gli identificatori specifici del DSP negli annunci di un DSP o all'interno di un determinato segmento di pubblico personalizzato per filtrare gli annunci dalle aste future.

Le chiavi contatore possono essere utilizzate per dare la 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 da aste, visualizzazioni e clic sugli annunci vincenti rappresenta un punto dati dedotto. Per chiarire ulteriormente questo punto: un annuncio di mazze da golf per mancini potrebbe indicare che l'utente non è interessato a quelle per destri. Un filtro per la quota limite impostato per una chiave contatore assegnato agli annunci per mancini potrebbe filtrare quelli per i club destrimani.

Per utilizzare la quota limite nell'asta, devi prima creare oggetti KeyedFrequencyCap:

// 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()

// Value used when incrementing frequency counter
int adCounterKey = 123;

// Frequency cap exceeded after 2 counts
KeyedFrequencyCap keyedFrequencyCapForImpression =
  new KeyedFrequencyCap.Builder(
    adCounterKey, 2, Duration.ofSeconds(10)
  ).build();

// Frequency Cap exceeded after 1 counts
KeyedFrequencyCap keyedFrequencyCapForClick =
  new KeyedFrequencyCap.Builder(
    adCounterKey, 1, Duration.ofSeconds(10)
  ).build();

Una volta creati gli oggetti KeyedFrequencyCap, puoi passarli a un oggetto AdFilters.

val filters: AdFilters = Builder()
  .setFrequencyCapFilters(
    Builder()
      .setKeyedFrequencyCapsForImpressionEvents(
        ImmutableObject.of(keyedFrequencyCapForImpression)
      )
      .setKeyedFrequencyCapsForClickEvents(
        ImmutableObject.of(keyedFrequencyCapForClick)
      )
  ).build()

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 di quota limite, può essere trasmesso al momento della creazione del segmento di pubblico personalizzato:

// 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()

// 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 di limite di frequenza vengono implementati in un segmento di pubblico personalizzato, la SSP può invocare gli eventi di clic, visualizzazione o impressione necessari.

val callerAdTech: AdTechIdentifier = mAdSelectionConfig.getSeller()

val request: UpdateAdCounterHistogramRequest = Builder(
  adSelectionId,
  FrequencyCapFilters.AD_EVENT_TYPE_CLICK,  //CLICK, VIEW, or IMPRESSION
  callerAdTech
).build()

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 del filtro della quota limite preimpostata vengono esclusi dall'asta. Il filtro viene applicato prima dell'esecuzione della logica di offerta per le aste on-device e durante la generazione del payload per le aste di Bidding & Auction Services.Questo toolkit offre agli esperti di tecnologia pubblicitaria la flessibilità di utilizzare le interazioni tra gli utenti e gli annunci all'interno dei loro segmenti di pubblico personalizzati per focalizzare il targeting degli annunci riducendo al minimo la sovraesposizione degli annunci.

Filtro degli annunci contestuali senza chiamate di rete

Se non esiste una domanda di remarketing sul dispositivo, puoi eseguire la selezione degli annunci per gli annunci contestuali senza chiamate di rete. Con gli URI predefiniti e un elenco di annunci contestuali con offerte, la piattaforma può saltare il recupero della logica di offerta, degli indicatori delle offerte 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, le tecnologie pubblicitarie possono eseguire un flusso di selezione degli annunci che include solo annunci contestuali con funzionalità di filtro degli annunci senza chiamate di rete. Questo viene ottenuto utilizzando URI predefiniti per il calcolo del punteggio degli indicatori. Per un elenco delle implementazioni scoreAds, consulta la sezione Nomi e casi d'uso degli URI predefiniti supportati.

Per eseguire la selezione degli annunci senza chiamate alla rete:

1. Configurare il filtro degli annunci
2. Creare annunci contestuali

3. Crea un oggetto AdSelectionConfig con quanto segue:

   1. Un elenco vuoto di acquirenti
   2. Un URI predefinito per selezionare l'offerta più alta
   3. Annunci contestuali
   4. Un URI vuoto per gli indicatori di punteggio. L'URI vuoto è consentito per indicare che non vuoi utilizzare il recupero di indicatori attendibili per il calcolo del 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();
   

4. Esegui la selezione degli annunci:

   adSelectionManager.selectAds(
       adSelectionConfig,
       executor,
       outcomeReceiver);
   

Esegui il tuo codice JavaScript per i report utilizzando URI predefiniti

Al momento, la piattaforma Privacy Sandbox dispone solo di un'implementazione di JavaScript di base per i report per gli URI predefiniti. Se vuoi eseguire il tuo codice JavaScript per i report continuando a utilizzare gli URI predefiniti per una selezione degli annunci con bassa latenza, puoi sostituire il valore DecisionLogicUri tra la selezione degli annunci e le esecuzioni dei report.

1. Esegui i passaggi per eseguire la selezione degli annunci per gli annunci contestuali utilizzando gli URI predefiniti

2. Crea una copia di AdSelectionConfig prima di generare i report

   adSelectionConfigWithYourReportingJS = adSelectionConfig.cloneToBuilder()
     // Replace <urlToFetchYourReportingJS> with your own URL:
     .setDecisionLogicUri(Uri.parse(<urlToFetchYourReportingJS>))
     .build();
   

3. Generare report sulle impressioni

   // adSelectionId is from the result of the previous selectAds run
   ReportImpressionRequest request = new ReportImpressionRequest(
     adSelectionId,
     adSelectionConfigWithYourReportingJS);
   adSelectionManager.reportImpression(
     request,
     executor,
     outcomeReceiver);
   

Eseguire la mediazione a cascata

La mediazione a cascata richiede l'orchestrazione di più SDK di terze parti (reti di terze parti) da parte di una rete di mediazione SDK proprietaria. La mediazione a cascata viene eseguita allo stesso modo indipendentemente dal fatto che l'asta sia avvenuta sul dispositivo o sia stata eseguita su Bidding & Auction Services (B&A).

Reti di terze parti

Le reti di terze parti devono fornire un'interfaccia che consenta alla rete di mediazione di invocare i metodi necessari per l'esecuzione di un'asta:

• Esegui selezione degli annunci
• Impressioni report

Ecco un esempio di adattatore di rete di mediazione:

class NetworkAdaptor {
    private val adSelectionManager : AdSelectionManager

    init {
        adSelectionManager = context.getSystemService(AdSelectionManager::class.java)
    }

    fun selectAds() {...}

    fun reportImpressions() {...}
}

class NetworkAdaptor {
    AdSelectionManager adSelectionManager;

    public NetworkAdaptor() {
        AdSelectionManager adSelectionManager =
            context.getSystemService(AdSelectionManager.class);
    }

    public void selectAds() {...}

    public void reportImpressions() {...}
}

Ogni SDK ha i propri gestori e clienti del servizio di selezione degli annunci, nonché la propria implementazione di selectAds e reportImpressions. I fornitori di SDK possono consultare le sezioni su come eseguire la selezione degli annunci per le aste on-device o la spiegazione di B&A per le aste B&A. Scopri come registrare le impressioni (consulta la sezione relativa alla registrazione delle impressioni delle SSP singole per i report.

Rete di mediazione

Come le reti di terze parti, le reti di mediazione richiedono implementazioni di selectAds e reportImpression. Per ulteriori informazioni, consulta le sezioni su come eseguire la selezione degli annunci e su come registrare le impressioni degli annunci.

Le reti di mediazione sono responsabili dell'esecuzione della catena di mediazione e del loro posizionamento al suo interno. La sezione successiva spiega come configurare ed eseguire questa procedura.

Recuperare la catena di mediazione e le offerte minime

La rete di mediazione è responsabile del recupero degli annunci contestuali proprietari (1P), della catena di mediazione e delle offerte minime delle reti di terze parti (3P). Questo può accadere in una richiesta di recupero di annunci contestuali eseguita dalla rete di mediazione. La catena di mediazione determina come eseguire l'iterazione delle reti di terze parti e le offerte minime possono essere passate al processo di asta come adSelectionSignals.

Posizionamento della rete nella catena di mediazione

Un SDK di mediazione può posizionarsi nella catena di mediazione in base all'eCPM in tempo reale delle offerte per gli 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 la soglia minima della rete di terze parti successiva nella catena. Se l'offerta proprietaria è superiore al prezzo minimo, significa che l'SDK di mediazione è posizionato prima della rete di terze parti.

Esegui selezione degli annunci

Per recuperare un annuncio candidato proprietario, la rete di mediazione può eseguire un'asta on-device seguendo i passaggi descritti nella sezione Eseguire la selezione degli annunci. In questo modo viene generato un annuncio candidato proprietario, un'offerta e un AdSelectionId che vengono utilizzati nel processo di mediazione.

Crea un AdSelectionFromOutcomesConfig

Un AdSelectionFromOutcomesConfig consente alla rete di mediazione di trasmettere un elenco di AdSelectionIds (risultati di aste precedenti), indicatori di selezione degli annunci e un URI per recuperare il codice JavaScript che seleziona un annuncio tra più candidati. L'elenco di AdSelectionId, insieme alle relative offerte e agli indicatori, viene passato al codice JavaScript, che può restituire uno dei valori AdSelectionIds se supera la base di offerta o nessuno se la catena di mediazione deve continuare.

Le reti di mediazione creano un AdSelectionFromOutcomesConfig utilizzando il AdSelectionId di proprietà della rete pubblicitaria proprietaria della sezione precedente e la soglia di offerta per la rete pubblicitaria di terze parti in considerazione. Deve essere creato un nuovo AdSelectionFromOutcomesConfig per ogni passaggio della catena di mediazione.

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)
}

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 la soglia minima dell'offerta recuperata per la rete di terze parti specificata.
• URI della logica di selezione: un URL HTTPS sottoposto a query durante la selezione dell'annuncio per recuperare il codice JavaScript della rete di mediazione per la selezione di un annuncio vincente. Consulta le signature delle funzioni richieste in questo codice JavaScript. Il codice JavaScript deve restituire l'annuncio di terze parti se l'offerta è superiore all'offerta minima oppure restituire null. In questo modo, l'SDK di mediazione può troncare la catena di mediazione quando viene trovato un vincitore.

Con AdSelectionOutcomesConfig creato, chiama il metodo selectAds() della rete di terze parti che è la prima della catena.

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)

AdSelectionManager adSelectionManager =
    context.getSystemService(AdSelectionManager.class);

// Initialize AdSelectionFromOutcomesConfig
AdSelectionFromOutcomesConfig adSelectionFromOutcomesConfig =
        new AdSelectionFromOutcomesConfig.Builder()
            .setSeller(seller)
            .setAdSelectionIds(Collection.singletonList(outcome1p))
            .setSelectionSignals({"bid_floor": bid_floor})
            .setSelectionLogicUri(selectionLogicUri)
            .setAdSelectionIds(outcomeIds)
            .build();

// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(
    adSelectionFromOutcomesConfig,
    executor,
    outcomeReceiver);

Orchestrare la mediazione a cascata

Di seguito è riportato l'ordine delle operazioni per eseguire la procedura di mediazione.

1. Esegui la selezione degli annunci proprietari.
2. Esegui l'iterazione della catena di mediazione. Per ogni emittente di terze parti:
   1. Crea AdSelectionFromOutcomeConfig, inclusi outcomeId proprietari e il prezzo minimo dell'SDK di terze parti.
   2. Chiama selectAds() con la configurazione del passaggio precedente.
   3. Se il risultato non è vuoto, restituisce l'annuncio.
   4. Chiama il metodo selectAds() dell'adattatore di rete dell'SDK corrente. Se il risultato non è vuoto, restituisce l'annuncio.
3. Se non viene trovato alcun annuncio vincitore nella catena, restituisci l'annuncio proprietario.

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)
}

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) { ... }
}

Segnalare impressioni degli annunci

Esistono due flussi per registrare un'impressione dell'annuncio, a seconda di come viene eseguita l'asta. Se sei una singola SSP che gestisce un'asta, segui questa sezione. Se hai intenzione di implementare la mediazione a cascata, segui i passaggi descritti nella sezione relativa ai report sulle impressioni della mediazione a cascata.

Report sulle impressioni di una singola SSP

Dopo aver scelto un annuncio vincente dal flusso di lavoro di selezione degli annunci, puoi registrare nuovamente l'impressione alle piattaforme sell-side e buy-side partecipanti con il metodo AdSelectionManager.reportImpression(). Per segnalare un'impressione dell'annuncio:

1. Inizializza un oggetto AdSelectionManager.
2. Crea un oggetto ReportImpressionRequest con l'ID selezione annunci.
3. Chiama il metodo reportImpression() asincrono con l'oggetto ReportImpressionRequest e gli oggetti Executor e OutcomeReceiver pertinenti.

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);

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 solo per un utente del dispositivo che identifica una selezione di annunci riuscita.
• Configurazione selezione annunci: la stessa configurazione utilizzata nella chiamata selectAds() identificata dall'ID selezione annunci fornito.

Il metodo reportImpression() asincrono utilizza l'oggetto OutcomeReceiver per segnalare il risultato della chiamata all'API.

• Il callback onResult() indica se sono stati creati gli URL dei report sulle impressioni e se la richiesta è stata pianificata.
• Il callback onError() indica le seguenti possibili condizioni:
  • Se la chiamata viene inizializzata con un argomento di input non valido, il valore AdServicesException indica IllegalArgumentException come causa.
  • Tutti gli altri errori ricevono un AdServicesException con IllegalStateException come causa.

Report sulle impressioni della mediazione a cascata

Un SDK di mediazione deve tenere traccia dell'SDK vincente per attivare i flussi di generazione di report. Gli SDK che partecipano a una catena di mediazione devono fornire un metodo che il mediatore può chiamare per attivare il proprio flusso di generazione di report. Un SDK che partecipa a un'asta mediata può seguire i passaggi precedenti per implementare i propri report.

Le SSP possono utilizzare 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 per i report sulle impressioni

L'API Impressioni report invia richieste GET HTTPS agli endpoint forniti dalla piattaforma lato vendite e dalla piattaforma lato acquirente vincente:

Endpoint della piattaforma lato acquisti:

• L'API utilizza l'URL della logica di offerta specificato nel segmento di pubblico personalizzato per recuperare il codice JavaScript fornito dall'acquirente che include la logica per restituire un URL per i report sulle impressioni.
• Richiama la funzione JavaScript reportWin(), che dovrebbe restituire l'URL dei report sulle impressioni dell'acquirente.

Endpoint della piattaforma di scambio pubblicitario:

• Utilizza l'URL della logica decisionale specificato nell'oggetto AdSelectionConfig per recuperare il codice JavaScript della logica decisionale del venditore.
• Richiama la funzione JavaScript reportResult(), che dovrebbe restituire l'URL dei report sulle impressioni del venditore.

Report sui servizi di offerte e aste

Un'asta eseguita sui servizi di aste e offerte conterrà tutte le informazioni necessarie per i report, inclusi gli URL generati per i report sulle interazioni con gli annunci, inclusi nella risposta criptata dell'asta lato server. Quando la risposta viene decriptata, gli URL appropriati vengono registrati sulla piattaforma, pertanto la generazione di report su annunci e impressioni segue gli stessi passaggi.

Report sulle impressioni con il criterio del "best effort"

Il metodo reportImpression() è progettato per offrire un completamento del reporting al meglio delle possibilità.

Segnalare le interazioni con gli annunci

Protected Audience fornisce assistenza per generare report su interazioni più granulari per un annuncio visualizzato. Ciò può includere interazioni come tempo di visualizzazione, clic, passaggi del mouse o qualsiasi altra metrica utile che può essere raccolta. La procedura per ricevere questi report richiede due passaggi. Innanzitutto, acquirenti e venditori devono registrarsi per ricevere questi report nel codice JavaScript dei report. Il cliente dovrà poi registrare questi eventi.

Registrazione per la ricezione di eventi di interazione

La registrazione per gli eventi di interazione avviene nelle funzioni JavaScript reportWin() dell'acquirente e reportResult() del venditore utilizzando una funzione JavaScript fornita dalla piattaforma: registerAdBeacon. Per registrarti per ricevere un report sugli eventi, chiama la funzione JavaScript della piattaforma dal codice JavaScript per i report. Lo snippet seguente 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, "view": viewUri, "hover": hoverUri});

    return reportingUri;
}

Generare report sugli eventi di interazione

Dopo aver registrato un'impressione, i clienti possono segnalare le interazioni alle piattaforme di scambio pubblicitario di acquirenti e venditori vincenti registrate in precedenza con il metodo AdSelectionManager.reportInteraction(). Per segnalare un evento correlato agli annunci:

1. Inizializza un oggetto AdSelectionManager.
2. Crea un oggetto ReportInteractionRequest con l'ID selezione annunci, la chiave di interazione, i dati di interazione e la destinazione dei report.
3. Chiama il metodo reportInteraction() asincrono con l'oggetto request e gli oggetti Executor e OutcomeReceiver 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 annunci recuperato da un AdSelectionOutcome restituito in precedenza.
• Chiave di interazione: una chiave di stringa definita dal client che descrive l'azione indicata nel report. Deve corrispondere alla chiave registrata dal venditore o dall'acquirente nelle funzioni JavaScript dei report.
• Dati di interazione: una stringa contenente i dati da includere nel report sugli eventi da inviare tramite POST ai server di generazione di report.
• 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 bitwise. Per generare un report in una destinazione, puoi utilizzare direttamente il flag fornito dalla piattaforma. Per generare report in più destinazioni, puoi utilizzare l'operatore OR (|) a livello di bit per combinare i valori dei flag.

Il metodo reportInteraction() asincrono utilizza l'oggetto OutcomeReceiver per segnalare il risultato della chiamata all'API.

• Il callout onResult() indica che la chiamata di interazione con il report è valida.
• Il callback onError() indica le seguenti possibili condizioni:
  • 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 dalla chiamata a reportInteraction(), viene restituito un valore LimitExceededException.
  • Se il pacchetto non è registrato per chiamare le API incentrate sulla tutela della privacy, viene restituito un valore SecurityException().
  • Se l'app che registra le interazioni è diversa dall'app che ha chiamato selectAds(), viene restituito un IllegalStateException.
• Se l'utente non ha dato il consenso per abilitare le API Privacy Sandbox, la chiamata non andrà a buon fine in modo silenzioso.

Endpoint dei report sulle interazioni

L'API di interazione con i report invia richieste POST HTTPS agli endpoint forniti dalla piattaforma sell-side e dalla piattaforma buy-side vincente. Protected Audience associa le chiavi di interazione agli URI dichiarati in JavaScript per i report e invia una richiesta POST a ogni endpoint per ogni interazione registrata. Il Content-Type della richiesta è in testo normale e il corpo è costituito dai Dati sulle interazioni.

Report sulle interazioni secondo il criterio del massimo impegno

reportInteraction() è progettato per offrire un completamento secondo il criterio del massimo impegno dei report tramite POST HTTP.

Aggiornamento giornaliero in background

Quando crei un segmento di pubblico personalizzato, la tua app o il tuo SDK può inizializzare i metadati del segmento di pubblico personalizzato. Inoltre, la piattaforma può aggiornare i seguenti elementi dei metadati dei segmenti di pubblico personalizzati con un processo di aggiornamento giornaliero in background.

• Indicatori di offerta per gli utenti
• Dati di 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 dei metadati supportati che devono essere aggiornati.
• Ogni campo JSON viene convalidato in modo indipendente. Il client ignora eventuali campi con formato non corretto, il che comporta l'assenza di aggiornamenti a quel determinato campo nella risposta.
• Una risposta HTTP vuota o un oggetto JSON vuoto "{}" non comporta aggiornamenti dei metadati.
• Le dimensioni del messaggio di risposta devono essere limitate a 10 KB.
• Tutti gli URI devono utilizzare HTTPS.
• trusted_bidding_uri deve condividere lo stesso ETLD+1 dell'acquirente.

Esempio: risposta JSON per l'aggiornamento giornaliero in background

{
    "user_bidding_signals" : { ... },  // Valid JSON object
    "trusted_bidding_data" : {
        "trusted_bidding_uri" : 'example-dsp1-key-value-service.com',
        "trusted_bidding_keys" : [ 'campaign123', 'campaign456', ... ]
    },
    'ads' : [
        {
            "render_uri" : 'www.example-dsp1.com/.../campaign123.html',
            'metadata' : { ... }  // Valid JSON object
        },
        {
            "render_uri" : 'www.example-dsp1.com/.../campaign456.html',
            'metadata' : { ... }  // Valid JSON object
        },
        ...
    ]
}

JavaScript per la selezione degli annunci

Il flusso di lavoro di selezione degli annunci orchestra l'esecuzione del codice JavaScript fornito dall'acquirente e dal venditore.

Il codice JavaScript fornito dall'acquirente viene recuperato dall'URL della logica di offerta specificato nel segmento di pubblico personalizzato. Il codice JavaScript restituito deve includere le seguenti funzioni:

• generateBid()
• reportWin()

Il codice JavaScript fornito dal venditore viene recuperato dall'URL della logica decisionale specificato nel parametro AdSelectionConfig per l'API di selezione degli annunci. Il codice JavaScript restituito deve includere le seguenti funzioni:

• scoreAd()
• reportResult()

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 formato var ad = { 'render_url': url, 'metadata': json_metadata };
• auction_signals, per_buyer_signals: oggetti JSON specificati nell'oggetto di configurazione dell'asta

• custom_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 e name sono stringhe prese dalle proprietà con lo stesso nome del segmento di pubblico personalizzato che partecipa alla selezione degli annunci
  • activation_time e expiration_time sono le date di attivazione e scadenza del segmento di pubblico personalizzato, espresse in secondi dall'epoca Unix
  • ca_user_bidding_signals è una stringa JSON specificata nel campo userBiddingSignals di CustomAudience al momento della creazione
  • trusted_bidding_signals, contextual_signals e user_signals sono oggetti JSON. Vengono passati come oggetti vuoti e verranno completati nelle release future. Il loro formato non viene applicato dalla piattaforma ed è gestito dalla tecnologia pubblicitaria.

Risultato:

• ad: è l'annuncio a cui si riferisce l'offerta. Lo script è autorizzato a restituire una copia dell'annuncio ricevuto con metadati diversi. La proprietà render_url dell'annuncio dovrebbe essere invariata.
• bid: un valore float che rappresenta il valore dell'offerta per questo annuncio
• status: un valore intero che può essere:
  • 0: per un'esecuzione riuscita
  • 1: (o qualsiasi valore diverso da zero) nel caso in cui uno degli indicatori di input non sia valido. Se generate-bid restituisce un valore diverso da zero, la procedura di offerta viene invalidata per tutti gli annunci CA

scoreAd()

function scoreAd(
  ad,
  bid,
  ad_selection_config,
  seller_signals,
  trusted_scoring_signals,
  contextual_signal,
  user_signal,
  custom_audience_signal) {
    return {'status': 0, 'score': score };
}

Parametri di input:

• ad: consulta la documentazione di generateBid
• bid: il valore dell'offerta per l'annuncio

• ad_selection_config: un oggetto JSON che rappresenta il parametro AdSelectionConfig dell'API selectAds. 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 dell'API sellerSignals AdSelectionConfig

• trusted_scoring_signal: letto dal campo adSelectionSignals nel parametro dell'API AdSelectionConfig

• contextual_signals, user_signals: oggetti JSON. Vengono passati come oggetti vuoti e verranno completati nelle release future. Il loro formato non viene applicato dalla piattaforma ed è gestito dalla tecnologia pubblicitaria.

• per_buyer_signals: oggetto JSON letto dalla mappa perBuyerSignal nel parametro dell'API AdSelectionConfig utilizzando come chiave l'attuale acquirente di segmenti di pubblico personalizzato. Vuoto se la mappa non contiene voci per l'acquirente specificato.

Output:

• score: un valore float che rappresenta il valore del punteggio per questo annuncio
• status: un valore intero che può essere:
  • 0: per un'esecuzione riuscita
  • 1: nel caso in cui i valori 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 lanciata

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 esito positivo, diverso da zero per esito negativo
• result: uno dei risultati passati o nullo

reportResult()

function reportResult(ad_selection_config, render_url, bid, contextual_signals) {
   return {
      'status': status,
      'results': {'signals_for_buyer': signals_for_buyer, 'reporting_url': reporting_url }
   };
}

Parametri di input:

• ad_selection_config: consulta la documentazione di scoreAds
• render_url: l'URL di rendering dell'annuncio vincente
• bid: l'offerta offerta per l'annuncio vincente
• contextual_signals: consulta la documentazione di generateBid

Output:

• status: 0 per esito positivo e diverso da zero per esito negativo
• results: un oggetto JSON contenente:
  • signals_for_buyer: un oggetto JSON passato alla funzione reportWin.
  • 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 relativa a scoreAd
• signals_for_buyer: un oggetto JSON restituito da reportResult
• contextual_signals, custom_audience_signals: consulta la documentazione per generateBid

Output:

• status: 0 per esito positivo e diverso da zero per esito negativo
• results: un oggetto JSON contenente:
  • reporting_url: un URL utilizzato dalla piattaforma per notificare l'impressione al venditore

registerAdBeacon()

function registerAdBeacon(
  beacons
)

Parametri di input:

• beacons: un oggetto contenente coppie chiave-valore di chiavi di interazione e URI report. Il formato è:

  let beacons = {
    'interaction_key': 'reporting_uri',
    'interaction_key': 'reporting_uri',
    ...
  }
  

  • interaction_key: una stringa che rappresenta l'evento. Questo valore viene utilizzato dalla piattaforma in un secondo momento per segnalare le interazioni con gli eventi e cercare il reporting_uri a cui deve essere inviata la notifica. Questa chiave deve corrispondere a quanto registrato dall'acquirente o dal venditore e a quanto registrato dal venditore.
  • reporting_uri: un URI per ricevere i report sugli eventi. Deve essere specifico per il tipo di evento registrato. Deve accettare una richiesta POST per gestire tutti i dati registrati insieme all'evento.

  Ad esempio:

    let beacons = {
      'click': 'https://reporting.example.com/click_event',
      'view': 'https://reporting.example.com/view_event'
    }
  

URI predefiniti per la selezione degli annunci

Gli URI predefiniti offrono alle tecnologie pubblicitarie la possibilità di assegnare funzioni JavaScript per la logica di decisione di selezione degli annunci nelle classi AdSelectionConfig e AdSelectionFromOutcomesConfig. Gli URI predefiniti non richiedono chiamate di rete per scaricare il codice JavaScript corrispondente. Gli esperti di tecnologia pubblicitaria possono utilizzare URI predefiniti senza dover configurare un dominio registrato per ospitare il codice JavaScript.

Un URI predefinito viene creato utilizzando il seguente formato:

ad-selection-prebuilt:<use-case>/<name>?<required-script-generation-parameters>

La piattaforma Privacy Sandbox fornisce JavaScript utilizzando le informazioni di questo URI in fase di runtime.

Viene generato un IllegalArgumentException se:

• uno dei parametri obbligatori non è presente nell'URI
• sono presenti parametri non riconosciuti nell'URI

Nomi e casi d'uso degli URI predefiniti supportati

Caso d'uso 1: selezione degli annunci

Gli URI predefiniti nel caso d'uso ad-selection sono supportati nel flusso selectAds(AdSelectionConfig).

Nome dell'URI predefinito: highest-bid-wins

Questo URI predefinito fornisce un codice JavaScript che seleziona l'annuncio con l'offerta più alta dopo l'asta. Fornisce inoltre una funzione di generazione di report di base per segnalare render_uri e bid del vincitore.

Parametri obbligatori

reportingUrl: l'URL report di base parametrizzato con render_uri e bid dell'annuncio vincente:

<reportingUrl>?render_uri=<renderUriOfWinnigAd>&bid=<bidOfWinningAd>

Utilizzo

Se l'URL dei 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: selezione degli annunci in base ai risultati

Gli URI predefiniti nel caso d'uso ad-selection-from-outcomes supportano il flusso di lavoro selectAds(AdSelectionFromOutcomesConfig).

Nome dell'URI predefinito: waterfall-mediation-truncation

L'URI predefinito waterfall-mediation-truncation fornisce JavaScript che implementa la logica di troncamento della mediazione a cascata in cui JavaScript restituisce un annuncio proprietario se bid è maggiore o uguale a bid floor e, in caso contrario, restituisce null.

Parametri obbligatori

bidFloor: la chiave del valore del prezzo minimo dell'offerta trasmessa in 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 precompilato 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 un po' di codice JavaScript durante la selezione degli annunci e la generazione di 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 restituisce il codice JavaScript
• Sostituisci il 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 sette endpoint HTTPS a cui può accedere il dispositivo di test o l'emulatore:

1. Endpoint dell'acquirente che pubblica il codice JavaScript della logica di offerta.
2. Un endpoint che pubblica gli indicatori per le offerte.
3. Endpoint del venditore che serve la logica decisionale JavaScript.
4. Un endpoint che fornisce indicatori di punteggio.
5. Endpoint dei report sulle impressioni dell'acquirente vincitore.
6. Endpoint per i report sulle impressioni del venditore.
7. Un endpoint per pubblicare gli aggiornamenti giornalieri per un segmento di pubblico personalizzato.

Per comodità, il repository GitHub fornisce codice JavaScript di base per scopi di test. Include anche definizioni di servizi OpenAPI che possono essere implementate su una piattaforma di microservizi o simulata supportata. Per maggiori dettagli, consulta il file README del progetto.

Sostituisci il recupero remoto di JavaScript

Questa funzionalità è pensata per essere utilizzata per i 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 l'applicazione, aggiungi la seguente riga all'attributo application in AndroidManifest.xml:

<application
  android:debuggable="true">

Per un esempio di come utilizzare queste sostituzioni, consulta l'app di esempio Protected Audience su GitHub.

Devi aggiungere il tuo codice JavaScript personalizzato per gestire le routine di selezione degli annunci, come le aste, le decisioni di punteggio 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 mostra come leggere il codice da quel file e prepararlo per l'utilizzo come override.

È possibile eseguire l'override del recupero di JavaScript lato sell-side e lato buy-side indipendentemente, anche se è necessario un endpoint HTTPS per pubblicare qualsiasi JavaScript per cui non fornisci sostituzioni. Consulta il file README per informazioni su come configurare un server che gestisca questi casi.

È possibile eseguire l'override del recupero di JavaScript solo per i segmenti di pubblico personalizzati di proprietà del tuo pacchetto.

Sostituire il codice JavaScript lato sell

Per configurare un'override del codice JavaScript lato vendita, procedi come mostrato nel seguente esempio di codice:

1. Inizializza un oggetto AdSelectionManager.
2. Recupera un riferimento a TestAdSelectionManager dall'oggetto AdSelectionManager.
3. Crea un oggetto AdSelectionConfig.
4. Crea un AddAdSelectionOverrideRequest con l'oggetto AdSelectionConfig e un String che rappresenti il codice JavaScript che intendi utilizzare come override.
5. Chiama il metodo overrideAdSelectionConfigRemoteInfo() asincrono con l'oggetto AddAdSelectionOverrideRequest e gli oggetti Executor e OutcomeReceiver pertinenti.

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)

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);

Per ulteriori informazioni su cosa rappresenta ciascuno dei campi in AdSelectionConfig, consulta la sezione Eseguire la selezione degli annunci. 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, il decisionLogicJs deve contenere le signature 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 all'API.

Il callback onResult() indica che l'override è stato applicato correttamente. Le chiamate future a selectAds() utilizzeranno la logica di decisione e generazione di report che hai specificato come sostituzione.

Il callback onError() indica due possibili condizioni:

• Se il tentativo di override viene eseguito con argomenti non validi, il valore AdServiceException indica IllegalArgumentException come causa.
• Se il tentativo di override viene eseguito con un'app non in esecuzione in modalità di debug con le opzioni sviluppatore abilitate, AdServiceException indica IllegalStateException come causa.

Reimpostare le sostituzioni lato vendita

Questa sezione presuppone che tu abbia sostituito il codice JavaScript sell-side e che tu abbia un riferimento a TestAdSelectionManager e AdSelectionConfig utilizzati nella sezione precedente.

Per reimpostare le sostituzioni per tutti i AdSelectionConfigs:

1. Chiama il metodo resetAllAdSelectionConfigRemoteOverrides() asincrono con l'oggetto OutcomeReceiver pertinente.

// Resets overrides for all AdSelectionConfigs
testAadSelectionManager.resetAllAdSelectionConfigRemoteOverrides(
  outComeReceiver)

// Resets overrides for all AdSelectionConfigs
testAdSelectionManager.resetAllAdSelectionConfigRemoteOverrides(
    outComeReceiver);

Dopo aver reimpostato le sostituzioni lato vendita, le chiamate a selectAds() utilizzano qualsiasi decisionLogicUrl memorizzato in AdSelectionConfig per tentare di recuperare il JavaScript richiesto.

Se la chiamata a resetAllAdSelectionConfigRemoteOverrides() non va a buon fine, il callback OutComeReceiver.onError() fornisce un AdServiceException. Se la rimozione delle sostituzioni viene tentata con un'app non in esecuzione in modalità di debug con le opzioni sviluppatore attivate, AdServiceException indica IllegalStateException come causa.

Sostituisci il codice JavaScript lato acquirente

1. Segui i passaggi per unire un segmento di pubblico personalizzato
2. Crea un AddCustomAudienceOverrideRequest con l'attributo buyer e name del segmento di pubblico personalizzato da sostituire, oltre alla logica di offerta e ai dati che vuoi utilizzare come sostituzione.
3. Chiama il metodo overrideCustomAudienceRemoteInfo() asincrono con l'oggetto AddCustomAudienceOverrideRequest e gli oggetti pertinenti Executor e OutcomeReceiver.

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)

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 di buyer e name sono gli stessi utilizzati per creare il segmento di pubblico personalizzato. Scopri di più su questi campi.

Inoltre, puoi specificare altri due parametri:

• biddingLogicJs: codice JavaScript che contiene la logica dell'acquirente utilizzata durante la selezione degli annunci. Consulta le signature delle funzioni richieste in questo codice JavaScript.
• trustedBiddingSignals: indicatori di offerta da utilizzare durante la selezione degli annunci. Per scopi di test, può essere una stringa vuota.

Il metodo overrideCustomAudienceRemoteInfo() asincrono utilizza l'oggetto OutcomeReceiver per segnalare il risultato della chiamata all'API.

Il callback onResult() indica che l'override è stato applicato correttamente. Le chiamate successive a selectAds() utilizzano la logica di offerta e generazione di report che hai specificato come sostituzione.

Il callback onError() indica due possibili condizioni.

• Se il tentativo di override viene eseguito con argomenti non validi, il valore AdServiceException indica IllegalArgumentException come causa.
• Se il tentativo di override viene eseguito con un'app non in esecuzione in modalità di debug con le opzioni sviluppatore abilitate, AdServiceException indica IllegalStateException come causa.

Reimpostare le sostituzioni lato acquirente

Questa sezione presuppone che tu abbia sostituito il 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:

1. Chiama il metodo resetAllCustomAudienceOverrides() asincrono con gli oggetti Executor e OutcomeReceiver pertinenti.

// Resets overrides for all custom audiences
testCustomAudienceManager.resetCustomAudienceRemoteInfoOverride(
    executor,
    outComeReceiver)

// Resets overrides for all custom audiences
testCustomAudienceManager.resetCustomAudienceRemoteInfoOverride(
    executor,
    outComeReceiver)

Dopo aver reimpostato le sostituzioni lato acquirente, le chiamate successive a selectAds() utilizzano qualsiasi biddingLogicUrl e trustedBiddingData memorizzato in CustomAudience per tentare di recuperare il JavaScript richiesto.

Se la chiamata a resetCustomAudienceRemoteInfoOverride() non va a buon fine, il callback OutComeReceiver.onError() fornisce un AdServiceException. Se la rimozione delle sostituzioni viene tentata con un'app non in esecuzione in modalità di debug con le opzioni sviluppatore abilitate, AdServiceException indica IllegalStateException come causa.

Configurare un server dei report

Quando utilizzi le sostituzioni del recupero remoto, devi comunque configurare un server che il tuo dispositivo o emulatore possa raggiungere per rispondere agli eventi di generazione di report. Per i test è sufficiente un endpoint che restituisce 200. Il repository GitHub include definizioni di servizi OpenAPI che possono essere implementate in una piattaforma di microservizi o simulata supportata. Per maggiori dettagli, consulta il file README del progetto.

Quando cerchi le definizioni OpenAPI, cerca reporting-server.json. Questo file contiene un endpoint che restituisce 200, che rappresenta un codice di risposta HTTP. Questo endpoint viene utilizzato durante selectAds() e indica all'API Protected Audience che i report sulle impressioni sono stati completati correttamente.

Funzionalità da testare

• Esegui l'esercizio di aggiunta o rimozione e configura un segmento di pubblico personalizzato in base alle azioni degli utenti precedenti.
• Esegui l'inizializzazione della selezione degli annunci sul dispositivo tramite JavaScript ospitati remotely.
• Scopri in che modo l'associazione di un'app con impostazioni dei segmenti di pubblico personalizzati può influire sui risultati della selezione degli annunci.
• Genera report sulle impressioni degli esercizi dopo la selezione degli annunci.

Limitazioni

La tabella seguente elenca le limitazioni per l'elaborazione dell'API Protected Audience. I limiti presentati potrebbero essere soggetti a modifiche in base al feedback. Per le funzionalità in corso di sviluppo, leggi le note di rilascio.

Segnalare bug e problemi

Il tuo feedback è una parte fondamentale di Privacy Sandbox su Android. Comunicaci eventuali problemi rilevati o idee per migliorare Privacy Sandbox su Android.