Guida per gli sviluppatori dell'API Protected Audience

Mentre leggi la documentazione di Privacy Sandbox su Android, utilizza il pulsante Developer Preview o Beta per selezionare la versione del programma che stai utilizzando, poiché le istruzioni possono variare.

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

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 tutela la privacy degli utenti. Per le release future è previsto il supporto di altri casi d'uso, inclusi gli annunci per l'installazione di app. Scopri di più sull'API Protected Audience su Android nella proposta di progettazione.

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

1. Gestire i segmenti di pubblico personalizzati
2. Configurare ed eseguire la selezione degli annunci su un dispositivo
3. Report impressioni dell'annuncio

Prima di iniziare

Prima di iniziare, completa i seguenti passaggi:

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 (disabilitata per impostazione predefinita) con il seguente comando adb.

     adb shell device_config put adservices ppapi_app_allow_list \"*\"
   

4. In un terminale, attiva la segnalazione dei 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 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 viene fatto riferimento nel manifest, ad esempio res/xml/ad_services_config.xml. Scopri di più sulle autorizzazioni dei servizi pubblicitari e sul controllo dell'accesso agli SDK.

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

8. Per impostazione predefinita, l'API Ad Selection applica limiti alla quantità massima di memoria che può essere allocata da uno script di reporting di aste o impressioni. 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 questa condizione non è soddisfatta. Esistono due opzioni per configurare questa impostazione:

   • 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.

Unirsi a un segmento di pubblico personalizzato

Un segmento di pubblico personalizzato rappresenta un gruppo di utenti con intenzioni o interessi comuni, come deciso da un'app inserzionista. Un'app o un SDK può utilizzare un segmento di pubblico personalizzato per indicare un segmento di pubblico specifico, ad esempio un utente che ha lasciato articoli in un 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. Poi, 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. Questo valore viene impostato implicitamente sul nome del pacchetto dell'app chiamante.
• buyer: identificatore della rete pubblicitaria dell'acquirente che gestisce gli annunci per questo 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 questi parametri obbligatori:

• URL di aggiornamento giornaliero: un URL HTTPS interrogato quotidianamente in background per aggiornare gli indicatori di offerta degli utenti, i dati di offerta attendibili e i metadati e gli URL di rendering per gli annunci di un segmento di pubblico personalizzato.
• URL della logica di offerta: un URL HTTPS interrogato durante la selezione dell'annuncio per recuperare la logica di offerta JavaScript di un acquirente. Consulta le firme delle funzioni richieste in questo JavaScript.
• ID rendering annuncio: un ID arbitrario impostato dalla tecnologia pubblicitaria dell'acquirente. Si tratta di un'ottimizzazione per la generazione del payload per B&A.

I parametri facoltativi per un oggetto CustomAudience possono includere:

• Ora di attivazione: un segmento di pubblico personalizzato può partecipare alla selezione degli annunci e agli aggiornamenti giornalieri solo dopo l'ora di attivazione. Questo può essere utile per coinvolgere gli utenti inattivi di un'app, ad esempio.
• Ora di scadenza: un'ora futura dopo la quale il segmento di pubblico personalizzato viene rimosso dal dispositivo.
• Indicatori di offerta dell'utente: una stringa JSON contenente indicatori dell'utente, ad esempio le impostazioni internazionali preferite dell'utente, che il codice JavaScript della logica di offerta di un acquirente utilizza per generare offerte durante la procedura di selezione degli annunci. Questo formato aiuta le piattaforme di tecnologia pubblicitaria a 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 utilizzati 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 su cui viene eseguita una query per eseguire il rendering dell'annuncio finale.
  • Metadati: un oggetto JSON serializzato come stringa contenente informazioni da utilizzare nella logica di offerta dell'acquirente durante la procedura di selezione degli annunci.
  • Filtri annuncio: una classe che contiene tutte le informazioni necessarie per il filtro degli annunci per l'installazione di app e per la quota limite durante la selezione degli annunci.

Ecco un esempio di creazione di un 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 asincrono joinCustomAudience() utilizza l'oggetto OutcomeReceiver per segnalare il risultato della chiamata API.

• Il callback onResult() indica che il segmento di pubblico personalizzato è stato creato o aggiornato.
• 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 del risultato 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);
    }
};

Uscire da un segmento di pubblico personalizzato

Se l'utente non soddisfa più i criteri aziendali per un determinato pubblico personalizzato, un'app o un SDK può chiamare leaveCustomAudience() per rimuovere il 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 saperne di più su questi campi di immissione, leggi "Unirsi a un segmento di pubblico personalizzato".
3. Chiama il metodo asincrono leaveCustomAudience() 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(), i segnali OutcomeReceiver indicano la fine di una chiamata API. Per proteggere la privacy, un risultato di errore non distingue tra errori interni e argomenti non validi. Il callback onResult() viene chiamato al termine della chiamata API, indipendentemente dal fatto che un segmento di pubblico personalizzato corrispondente venga 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 asincrono selectAds() 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 dell'annuncio.
• URL della logica decisionale: un URL HTTPS interrogato per ottenere la logica JavaScript della rete pubblicitaria del venditore.
  • URL HTTPS: viene eseguita una query per ottenere la logica JavaScript del network pubblicitario del venditore. Consulta le firme delle funzioni richieste.
  • URI predefinito: che segue il formato di selezione degli annunci di FLEDGE. IllegalArgumentException viene generato se viene passato un URI predefinito non supportato o con formato errato.
• Acquirenti di segmenti di pubblico personalizzati: un elenco completo di identificatori per le reti pubblicitarie degli acquirenti che sono autorizzate dal venditore a partecipare alla procedura di selezione degli annunci. Questi identificatori dell'acquirente corrispondono a CustomAudience.getBuyer() dei segmenti di pubblico personalizzati partecipanti.

I seguenti parametri possono essere specificati facoltativamente per una selezione degli annunci più personalizzata:

• Indicatori di selezione degli annunci: un oggetto JSON, serializzato come stringa, contenente indicatori da utilizzare nella logica di offerta JavaScript dell'acquirente recuperata da CustomAudience.getBiddingLogicUrl().
• Indicatori del venditore: un oggetto JSON, serializzato come stringa, contenente indicatori utilizzati dalla logica decisionale JavaScript recuperata del 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 candidati all'annuncio raccolti direttamente dagli acquirenti durante un'asta che si svolge al di fuori di un'asta Protected Audience.

Una volta selezionato un annuncio, i risultati, le offerte e gli indicatori vengono salvati internamente per la generazione di report. Il callback OutcomeReceiver.onResult() restituisce un AdSelectionOutcome che contiene:

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

Se la selezione degli annunci non può essere completata correttamente per motivi quali argomenti non validi, timeout o consumo eccessivo di risorse, il callback OutcomeReceiver.onError() fornisce un AdServicesException con i seguenti comportamenti:

• Se la selezione dell'annuncio viene avviata con argomenti non validi, AdServicesException indica un 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 nell'asta 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 richiamare reportImpression(). Questo chiama reportWin() nell'annuncio contestuale vincente, nello stesso pattern della generazione di report sulle impressioni, per ricevere l'annuncio vincente su un dispositivo. Ogni annuncio contestuale ha bisogno di un acquirente, un'offerta, un link alla logica dei report, un URL di rendering e metadati dell'annuncio.

Per eseguire il deployment di annunci contestuali nell'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ò quindi 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 per l'installazione di app 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. Questa operazione deve essere eseguita 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 filtrare le app installate che specifichi durante la generazione delle offerte. Se devi rimuovere l'accesso di un inserzionista allo stato di installazione di questa app, esegui di nuovo questo codice dopo aver rimosso le informazioni dell'inserzionista.

Il passaggio successivo consiste nell'impostare 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 informazioni sugli annunci correlati alle app che vuole filtrare:

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

AdFilters può essere passato anche al momento dell'istanza 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 della quota limite

Il filtro della quota limite consente alle tecnologie pubblicitarie 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 di annunci alternativi per una determinata campagna pubblicitaria.

Un filtro del limite di frequenza è composto da due componenti principali: il tipo di evento annuncio e la chiave del contatore degli annunci. I tipi di eventi dell'annuncio disponibili che possono essere utilizzati sono:

• Vittoria: un evento di vittoria indica che l'annuncio ha vinto un'asta. Gli eventi vincenti vengono aggiornati automaticamente dall'API Protected Audience e non possono essere chiamati direttamente dallo sviluppatore. I dati sulle vittorie sono visibili solo agli annunci all'interno di un determinato segmento di pubblico personalizzato.
• Impressione: separato da reportImpression, un chiamante sul dispositivo (SSP o MMP) utilizza updateAdCounterHistogram() per richiamare gli eventi impressione nel punto del codice che sceglie. Gli eventi relativi alle impressioni sono visibili a tutti gli annunci appartenenti a un determinato DSP e non sono limitati agli annunci dello stesso segmento di pubblico personalizzato.
• Visualizzazione: l'evento viene richiamato dal chiamante sul dispositivo (SSP o MMP) in un punto del codice scelto utilizzando una chiamata a updateAdCounterHistogram(). Le visualizzazioni di eventi sono visibili a tutti gli annunci appartenenti a un determinato DSP e non sono limitate agli annunci dello stesso pubblico personalizzato.
• Clic: l'evento viene richiamato dal chiamante sul dispositivo (SSP o MMP) in un punto del codice scelto utilizzando una chiamata a updateAdCounterHistogram(). Gli eventi relativi ai clic sono visibili a tutti gli annunci appartenenti a un determinato DSP e non sono limitati agli annunci nello stesso segmento di pubblico personalizzato.

Nell'app editore, una SSP o un MMP presente sul dispositivo richiama gli eventi pubblicitari. Quando viene chiamato updateAdCounterHistogram(), il contatore di un filtro di 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 pubblicitari non sono legati forzatamente all'azione dell'utente corrispondente e sono linee guida fornite per aiutare i chiamanti a strutturare il proprio sistema di eventi. Per incrementare i contatori degli annunci al momento di un evento, l'attore sul dispositivo fornisce l'ID di selezione dell'annuncio dell'asta vincente.

Le chiavi del contatore di annunci sono numeri interi con segno a 32 bit arbitrari assegnati da una tecnologia pubblicitaria dell'acquirente e corrispondono a un determinato insieme di annunci definiti dalla DSP. Poiché le chiavi del contatore di annunci sono limitate solo agli annunci che appartengono a un determinato DSP, queste chiavi possono essere selezionate senza sovrapporsi agli istogrammi di un'altra tecnologia pubblicitaria. Le chiavi del contatore di 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 del contatore possono essere utilizzate per dare la priorità agli annunci che hanno maggiori probabilità di interessare 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 di annunci vincenti, visualizzazioni e clic rappresenta un punto dati inferito. Per illustrare ulteriormente questo punto: un annuncio di mazze da golf per mancini potrebbe indicare che l'utente non è interessato a quelle per destri. Un filtro della quota limite impostato per una chiave del contatore assegnata agli annunci per mancini potrebbe escludere gli annunci per mazze da golf per 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 della quota limite di frequenza, può essere trasmesso durante la 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 del limite di frequenza vengono implementati in un segmento di pubblico personalizzato, la SSP può richiamare 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 di filtro della quota limite preimpostata vengono esclusi dall'asta. Il filtraggio avviene prima dell'esecuzione della logica di offerta per le aste sul dispositivo e durante la generazione del payload per le aste dei servizi di offerta e asta.Questo toolkit offre alle tecnologie pubblicitarie la flessibilità di utilizzare le interazioni tra gli utenti e gli annunci all'interno dei segmenti di pubblico personalizzati per concentrarsi sul targeting degli annunci riducendo al minimo la sovraesposizione degli annunci.

Filtro degli annunci contestuali senza chiamate di rete

Se non è presente 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 includa solo annunci contestuali con funzionalità di filtro degli annunci senza chiamate di rete. Ciò si ottiene utilizzando URI predefiniti per gli indicatori di punteggio. Consulta la sezione Casi d'uso e nomi degli URI predefiniti supportati per un elenco delle implementazioni di scoreAds.

Per eseguire la selezione degli annunci senza chiamate di 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 degli indicatori attendibili per l'assegnazione 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 JavaScript per i report mentre utilizzi gli URI predefiniti

Oggi, la piattaforma Privacy Sandbox dispone solo di un'implementazione JavaScript di base per la generazione di report disponibile per gli URI predefiniti. Se vuoi eseguire il tuo JavaScript di generazione dei report e utilizzare comunque gli URI predefiniti per una selezione degli annunci a bassa latenza, puoi ignorare DecisionLogicUri tra la selezione degli annunci e l'esecuzione dei report.

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

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

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

3. Eseguire i report sulle impressioni

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

Esegui la mediazione a cascata

La mediazione a cascata richiede 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 si sia svolta sul dispositivo o sia stata eseguita sui servizi di offerte e aste (B&A).

Reti di terze parti

Le reti di terze parti devono fornire un adattatore che consenta alla rete di mediazione di richiamare i metodi necessari per eseguire un'asta:

• Esegui selezione degli annunci
• Impressioni del 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 client del servizio di selezione degli annunci e le proprie implementazioni di selectAds e reportImpressions. I fornitori di SDK possono fare riferimento alle sezioni su come eseguire la selezione degli annunci per le aste on-device o alla spiegazione di B&A per le aste B&A. Segui la procedura per generare report sulle impressioni degli annunci (seguendo la generazione di report sulle impressioni di una singola SSP per la generazione di report).

Rete di mediazione

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

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

Recuperare la catena di mediazione e i prezzi minimi di offerta

La rete di mediazione è responsabile del recupero degli annunci contestuali proprietari (1P), della catena di mediazione e dei prezzi minimi di offerta delle reti di terze parti (3P). Ciò può verificarsi in una richiesta di recupero di annunci contestuali eseguita dalla rete di mediazione. La catena di mediazione determina come scorrere le reti pubblicitarie di terze parti e i prezzi minimi di offerta possono essere passati 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 al suo eCPM live delle offerte per gli annunci proprietari. Nell'API Protected Audience, le offerte degli annunci sono opache. Un SDK di mediazione deve utilizzare AdSelectionFromOutcomesConfig per poter confrontare l'offerta di un annuncio proprietario con il prezzo minimo dell'offerta della successiva rete di terze parti nella catena. Se l'offerta proprietaria è superiore al prezzo minimo dell'offerta, significa che l'SDK di mediazione viene posizionato davanti alla rete di terze parti.

Esegui selezione degli annunci

Per recuperare un candidato annuncio proprietario, la rete di mediazione può eseguire un'asta sul dispositivo seguendo i passaggi descritti nella sezione Esegui la selezione degli annunci. In questo modo vengono generati un candidato annuncio proprietario, un'offerta e un AdSelectionId che viene utilizzato nel processo di mediazione.

Crea un oggetto AdSelectionFromOutcomesConfig

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

Le reti di mediazione creano un AdSelectionFromOutcomesConfig utilizzando l'AdSelectionId di prima parte della sezione precedente e il prezzo minimo di offerta per la rete di terze parti in esame. Per ogni passaggio della catena di mediazione deve essere creato un nuovo AdSelectionFromOutcomesConfig.

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 dell'annuncio.
• AdSelectionIds: un elenco singleton 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 nella logica di offerta dell'acquirente. In questo caso, includi il prezzo minimo recuperato per la rete di terze parti specificata.
• URI della logica di selezione: un URL HTTPS interrogato durante la selezione dell'annuncio per recuperare il codice JavaScript della rete di mediazione per selezionare un annuncio vincente. Consulta le firme delle funzioni richieste in questo JavaScript. Il codice JavaScript deve restituire l'annuncio di terze parti se l'offerta è superiore al prezzo minimo dell'offerta, altrimenti deve restituire null. Ciò consente all'SDK di mediazione di troncare la catena di mediazione quando viene trovato un vincitore.

Con AdSelectionOutcomesConfig creato, chiama il metodo selectAds() della rete di terze parti che si trova al primo posto nella 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 l'esecuzione della procedura di mediazione.

1. Esegui la selezione degli annunci proprietari.
2. Itera la catena di mediazione. Per ogni rete 3P, procedi nel seguente modo:
   1. Crea AdSelectionFromOutcomeConfig includendo outcomeId di prima parte e il prezzo minimo di offerta dell'SDK di terze parti.
   2. Chiama selectAds() con la configurazione del passaggio precedente.
   3. Se il risultato non è vuoto, restituisci l'annuncio.
   4. Chiama il metodo selectAds() dell'adattatore di rete SDK corrente. Se il risultato non è vuoto, restituisci l'annuncio.
3. Se non viene trovato alcun 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) { ... }
}

Report sulle impressioni annuncio

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

Report sulle impressioni di una singola SSP

Dopo che è stato scelto un annuncio vincente dal flusso di lavoro di selezione degli annunci, puoi segnalare l'impressione alle piattaforme lato acquisti e lato vendite 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 annuncio.
3. Chiama il metodo asincrono reportImpression() 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 annuncio: un ID univoco solo per un utente del dispositivo che identifica una selezione annuncio riuscita.
• Configurazione della selezione degli annunci: la stessa configurazione utilizzata nella chiamata selectAds() identificata dall'ID selezione degli annunci fornito.

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

• Il callback onResult() indica se sono stati creati gli URL di monitoraggio delle 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, AdServicesException indica un 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 relativi flussi di reporting. Gli SDK che partecipano a una catena di mediazione devono fornire un metodo che il mediatore possa richiamare per attivare il proprio flusso di generazione di report. Un SDK che partecipa a un'asta con mediazione può seguire i passaggi precedenti per implementare i propri report.

Le SSP possono utilizzare questo codice di esempio 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 di reporting delle impressioni

L'API Report Impression invia richieste GET HTTPS agli endpoint forniti dalla piattaforma lato vendite e dalla piattaforma lato acquisti 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 di reporting delle impressioni.
• Richiama la funzione JavaScript reportWin(), che dovrebbe restituire l'URL di reporting delle impressioni dell'acquirente.

Endpoint Sell-Side Platform:

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

Report sui servizi di offerte e aste

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

Report sulle impressioni basato sul criterio del "best effort"

Il metodo reportImpression() è progettato per offrire il completamento al meglio delle possibilità della generazione di report.

Report Interazioni con gli annunci

Protected Audience fornisce supporto per generare report su interazioni più granulari per un annuncio visualizzato. Ciò può includere interazioni come il tempo di visualizzazione, i clic, i 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 proprio JavaScript per i report. Dopodiché, il cliente dovrà segnalare questi eventi.

Registrazione per ricevere eventi di interazione

La registrazione degli 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 tuo codice JavaScript per i report. Il seguente snippet utilizza reportWin() di un acquirente, ma lo stesso approccio si applica a reportResult().

reportWin(
  adSelectionSignals,
  perBuyerSignals,
  signalsForBuyer,
  contextualSignals,
  customAudienceSignals) {
    ...
    // Calculate reportingUri, clickUri, viewUri, and hoverUri

    registerAdBeacon({"click": clickUri, "view": viewUri, "hover": hoverUri});

    return reportingUri;
}

Report sugli eventi di interazione

Dopo aver segnalato un'impressione, i clienti possono segnalare le interazioni alle piattaforme di acquisto e vendita vincenti registrate in precedenza con il metodo AdSelectionManager.reportInteraction(). Per segnalare un evento annuncio:

1. Inizializza un oggetto AdSelectionManager.
2. Crea un oggetto ReportInteractionRequest con l'ID selezione annuncio, la chiave di interazione, i dati di interazione e la destinazione dei report.
3. Chiama il metodo asincrono reportInteraction() 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 annuncio: un ID selezione annuncio recuperato da un AdSelectionOutcome restituito in precedenza.
• Chiave di interazione: una chiave stringa definita dal client che descrive l'azione di cui viene generato un report. Deve corrispondere alla chiave registrata dal venditore o dall'acquirente nelle funzioni JavaScript di reporting.
• Interaction Data: una stringa contenente i dati da includere nel report sull'evento, da inviare di nuovo ai server di reporting.
• Destinazioni dei report: una maschera di bit che specifica se gli eventi devono essere segnalati all'acquirente, al venditore o a entrambi. Questi flag vengono forniti dalla piattaforma e la maschera di destinazione finale può essere creata utilizzando operazioni bitwise. Per inviare un report a una destinazione, puoi utilizzare direttamente il flag fornito dalla piattaforma. Per generare report per più destinazioni, puoi utilizzare l'operatore OR bit a bit (|) per combinare i valori dei flag.

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

• Il callback onResult() indica che la chiamata di interazione del 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 LimitExceededException.
  • Se il pacchetto non è registrato per chiamare le API Privacy Preserving, viene restituito un SecurityException().
  • Se l'app che segnala le interazioni è diversa da quella che ha chiamato selectAds(), viene restituito un IllegalStateException.
• Se l'utente non ha acconsentito all'attivazione delle API Privacy Sandbox, la chiamata non andrà a buon fine.

Endpoint di generazione dei report sulle interazioni

L'API Report Interaction invia richieste POST HTTPS agli endpoint forniti dalla piattaforma lato venditore e dalla piattaforma lato acquirente vincente. Protected Audience corrisponderà le chiavi di interazione con gli URI dichiarati nel JavaScript di generazione dei report ed emetterà una richiesta POST a ogni endpoint per ogni interazione segnalata. L'Content-Type della richiesta è testo normale e il corpo contiene i dati di interazione.

Report sulle interazioni di tipo "best effort"

reportInteraction() è progettato per offrire il completamento ottimale dei report tramite HTTP POST.

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 del pubblico personalizzato con un processo di aggiornamento in background giornaliero.

• Indicatori di offerta dell'utente
• Dati delle 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 deve essere aggiornato.
• Ogni campo JSON viene convalidato in modo indipendente. Il client ignora i campi con errori di formato, pertanto non vengono apportati aggiornamenti a quel particolare campo nella risposta.
• Una risposta HTTP vuota o un oggetto JSON vuoto "{}" non comporta aggiornamenti dei metadati.
• La dimensione del messaggio di risposta deve essere limitata a 10 KB.
• Tutti gli URI devono utilizzare HTTPS.
• trusted_bidding_uri deve condividere lo stesso ETLD+1 dell'acquirente.

Esempio: risposta JSON per l'aggiornamento giornaliero in background

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

JavaScript per la selezione degli annunci

Il flusso di lavoro di selezione degli annunci orchestra l'esecuzione di JavaScript forniti 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 per la 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 estratte dalle proprietà con lo stesso nome del segmento di pubblico personalizzato che partecipa alla selezione degli annunci
  • activation_time e expiration_time sono l'ora di attivazione e scadenza del segmento di pubblico personalizzato, espressa in secondi a partire 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 riempiti nelle versioni future. Il loro formato non è applicato dalla piattaforma ed è gestito dalla tecnologia pubblicitaria.

Risultato:

• ad: è l'annuncio a cui si riferisce l'offerta. Lo script può restituire una copia dell'annuncio ricevuto con metadati diversi. La proprietà render_url dell'annuncio non deve essere modificata.
• 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. Nel caso in cui generate-bid restituisca 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 API sellerSignals AdSelectionConfig

• trusted_scoring_signal: lettura dal campo adSelectionSignals nel parametro API AdSelectionConfig

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

• per_buyer_signals: oggetto JSON letto dalla mappa perBuyerSignal nel parametro API AdSelectionConfig utilizzando come chiave l'acquirente del segmento di pubblico personalizzato corrente. 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 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 della procedura. Il valore determina il tipo di eccezione generata.

selectOutcome()

function selectOutcome(
  outcomes,
  selection_signals) {
    return {'status': 0, 'result': null};
}

Parametri di input:

• outcomes: un oggetto JSON {"id": id_string, "bid": bid_double}
• selection_signals: oggetti JSON specificati nell'oggetto di configurazione dell'asta

Output:

• status: 0 per l'esito positivo, diverso da zero per l'esito negativo
• result: uno dei risultati passati o null

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 proposta per l'annuncio vincente
• contextual_signals: consulta la documentazione di generateBid

Output:

• status: 0 per l'operazione riuscita e un valore diverso da zero per l'operazione non riuscita
• 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 per scoreAd
• signals_for_buyer: un oggetto JSON restituito da reportResult
• contextual_signals, custom_audience_signals: consulta la documentazione per generateBid

Output:

• status: 0 per l'operazione riuscita e un valore diverso da zero per l'operazione non riuscita
• 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 di reporting. 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, quando vengono segnalate le interazioni con gli eventi, per cercare l'reporting_uri a cui inviare la notifica. Questa chiave deve corrispondere a ciò che l'acquirente o il venditore sta registrando e a ciò che il venditore sta segnalando.
  • reporting_uri: un URI per ricevere i report sugli eventi. Queste informazioni devono essere specifiche per il tipo di evento segnalato. Deve accettare una richiesta POST per gestire i dati segnalati 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 consentono alle tecnologie pubblicitarie 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. Le tecnologie pubblicitarie possono utilizzare URI predefiniti senza dover configurare un dominio registrato per ospitare JavaScript.

Un URI predefinito viene creato utilizzando il seguente formato:

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

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

Viene generato un IllegalArgumentException se:

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

Casi d'uso e nomi degli URI predefiniti supportati

Caso d'uso 1: selezione degli annunci

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

Nome URI predefinito: highest-bid-wins

Questo URI predefinito fornisce un JavaScript che sceglie l'annuncio con l'offerta più alta dopo l'asta. Fornisce anche una funzione di reporting di base per segnalare il render_uri e il bid del vincitore.

Parametri obbligatori

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

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

Utilizzo

Se l'URL di base per i report è https://www.ssp.com/reporting, l'URI predefinito sarà:

`ad-selection-prebuilt://ad-selection/highest-bid-wins/?reportingUrl=https://www.ssp.com/reporting`

Use case 2: ad-selection-from-outcomes

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

Nome URI predefinito: waterfall-mediation-truncation

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

Parametri obbligatori

bidFloor: la chiave del valore del prezzo minimo di offerta trasmesso in getSelectionSignals() che viene confrontato con l'annuncio dell'SDK di mediazione.

Utilizzo

Se gli indicatori di selezione degli annunci hanno il seguente aspetto: {"bid_floor": 10}, l'URI predefinito risultante sarà:

`ad-selection-prebuilt://ad-selection-from-outcomes/waterfall-mediation-truncation/?bidFloor=bid_floor`

Test

Per aiutarti a iniziare a utilizzare l'API Protected Audience, abbiamo creato app di esempio in Kotlin e Java, che puoi trovare su GitHub.

Prerequisiti

L'API Protected Audience richiede JavaScript durante la selezione degli annunci e la generazione di report sulle impressioni. Esistono due metodi per fornire questo JavaScript in un ambiente di test:

• Esegui un server con gli endpoint HTTPS richiesti che restituisce JavaScript
• Esegui l'override del recupero remoto fornendo il codice necessario da un'origine locale

Entrambi gli approcci richiedono la configurazione di un endpoint HTTPS per gestire i report sulle impressioni.

Endpoint HTTPS

Per testare la selezione degli annunci e i report sulle impressioni, devi configurare sette endpoint HTTPS a cui il dispositivo di test o l'emulatore può accedere:

1. Endpoint dell'acquirente che pubblica il codice JavaScript della logica di offerta.
2. Un endpoint che pubblica gli indicatori di offerta.
3. Endpoint del venditore che gestisce il codice JavaScript della logica decisionale.
4. Un endpoint che pubblica indicatori di punteggio.
5. Endpoint per la generazione di report sulle impressioni dell'acquirente vincitore.
6. Endpoint per la generazione di 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 i test. Include anche definizioni di servizi OpenAPI che possono essere implementate in una piattaforma di microservizi o di simulazione supportata. Per maggiori dettagli, consulta il file README del progetto.

Eseguire l'override del recupero remoto di JavaScript

Questa funzionalità è pensata per essere utilizzata per i test end-to-end. Per ignorare il recupero da remoto, l'app deve essere eseguita in modalità di debug con le opzioni sviluppatore attive.

Per attivare la modalità di debug per la tua applicazione, aggiungi la seguente riga all'attributo dell'applicazione nel file AndroidManifest.xml:

<application
  android:debuggable="true">

Per un esempio di come utilizzare questi override, consulta l'app di esempio dell'API Protected Audience su GitHub.

Devi aggiungere il tuo codice JavaScript personalizzato per gestire le routine di selezione degli annunci, ad esempio le decisioni relative a offerte e punteggi e i report. Puoi trovare esempi di codice JavaScript di base che gestiscono tutte le richieste richieste nel repository GitHub. L'applicazione di esempio dell'API Protected Audience mostra come leggere il codice da questo file e prepararlo per l'utilizzo come override.

È possibile eseguire l'override del recupero di JavaScript lato venditore e lato acquirente in modo indipendente, anche se è necessario un endpoint HTTPS per pubblicare qualsiasi JavaScript per cui non fornisci override. Consulta il file README per informazioni su come configurare un server che gestisce questi casi.

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

Eseguire l'override di JavaScript lato venditore

Per configurare l'override di JavaScript lato vendite, procedi come segue, come illustrato nell'esempio di codice riportato di seguito:

1. Inizializza un oggetto AdSelectionManager.
2. Ottieni un riferimento a TestAdSelectionManager dall'oggetto AdSelectionManager.
3. Crea un oggetto AdSelectionConfig.
4. Crea un AddAdSelectionOverrideRequest con l'oggetto AdSelectionConfig e un String che rappresenta il codice JavaScript che intendi utilizzare come override.
5. Chiama il metodo asincrono overrideAdSelectionConfigRemoteInfo() 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 sul significato di ciascun campo in AdSelectionConfig, consulta la sezione Esegui selezione annuncio. 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 firme delle funzioni lato venditore corrette. Per un esempio di come leggere un file JavaScript come stringa, consulta l'app di esempio dell'API Protected Audience su GitHub.

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

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

Il callback onError() indica due possibili condizioni:

• Se il tentativo di override viene eseguito con argomenti non validi, 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 attive, AdServiceException indica IllegalStateException come causa.

Reimposta gli override lato vendite

Questa sezione presuppone che tu abbia eseguito l'override del codice JavaScript lato venditore e che tu abbia un riferimento a TestAdSelectionManager e AdSelectionConfig utilizzati nella sezione precedente.

Per reimpostare gli override per tutti i AdSelectionConfigs:

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

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

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

Dopo aver reimpostato gli override lato vendite, le chiamate a selectAds() utilizzano l'decisionLogicUrl memorizzato in AdSelectionConfig per tentare di recuperare il codice JavaScript richiesto.

Se la chiamata a resetAllAdSelectionConfigRemoteOverrides() non riesce, il callback OutComeReceiver.onError() fornisce un AdServiceException. Se si tenta la rimozione degli override con un'app non in esecuzione in modalità di debug con le opzioni sviluppatore attive, AdServiceException indica IllegalStateException come causa.

Eseguire l'override di JavaScript lato acquirente

1. Segui i passaggi per unirti a un segmento di pubblico personalizzato.
2. Crea un AddCustomAudienceOverrideRequest con l'acquirente e il nome del segmento di pubblico personalizzato che devi sostituire, oltre alla logica di offerta e ai dati che vuoi utilizzare come override.
3. Chiama il metodo asincrono overrideCustomAudienceRemoteInfo() con l'oggetto AddCustomAudienceOverrideRequest e gli oggetti Executor e OutcomeReceiver pertinenti.

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

Inoltre, puoi specificare due parametri aggiuntivi:

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

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

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

Il callback onError() indica due possibili condizioni.

• Se il tentativo di override viene eseguito con argomenti non validi, 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 attive, AdServiceException indica IllegalStateException come causa.

Reimposta gli override lato acquirente

Questa sezione presuppone che tu abbia eseguito l'override di JavaScript lato acquirente e che tu abbia un riferimento a TestCustomAudienceManager utilizzato nella sezione precedente.

Per reimpostare gli override per tutti i segmenti di pubblico personalizzati:

1. Chiama il metodo asincrono resetAllCustomAudienceOverrides() 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 gli override lato acquirente, le chiamate successive a selectAds() utilizzano biddingLogicUrl e trustedBiddingData memorizzati in CustomAudience per tentare di recuperare il codice JavaScript richiesto.

Se la chiamata a resetCustomAudienceRemoteInfoOverride() non riesce, il callback OutComeReceiver.onError() fornisce un AdServiceException. Se si tenta la rimozione degli override con un'app non in esecuzione in modalità di debug con le opzioni sviluppatore abilitate, AdServiceException indica IllegalStateException come causa.

Configurare un server di reporting

Quando utilizzi gli override del recupero remoto, devi comunque configurare un server che il tuo dispositivo o emulatore possa raggiungere per rispondere agli eventi di reporting. Un endpoint che restituisce 200 è sufficiente per i test. Il repository GitHub include definizioni di servizi OpenAPI che possono essere implementate in una piattaforma di microservizi o di simulazione 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 segnala all'API Protected Audience che la generazione di report sulle impressioni è stata completata correttamente.

Funzionalità da testare

• Esercitati a entrare o uscire e a configurare un segmento di pubblico personalizzato in base alle azioni precedenti degli utenti.
• Esercitare l'avvio della selezione degli annunci sul dispositivo tramite JavaScript ospitati in remoto.
• Osserva in che modo l'associazione di un'app alle impostazioni dei segmenti di pubblico personalizzati può influire sui risultati della selezione degli annunci.
• Report sulle impressioni dell'esercizio dopo la selezione dell'annuncio.

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, leggi le note di rilascio.

Segnalare bug e problemi

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