Guida per gli sviluppatori dell'API Protected Audience

Anteprima per sviluppatori Beta

Mentre leggi la documentazione di Privacy Sandbox su Android, utilizza il pulsante Anteprima per gli sviluppatori o Beta per selezionare la versione del programma in uso, 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 e gli inserzionisti di ad tech possono utilizzare queste API per pubblicare annunci personalizzati in base al coinvolgimento precedente dell'app che limita la condivisione di identificatori tra app e limita la condivisione con terze parti delle informazioni sull'interazione di un utente con l'app.

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. A questo scopo, il sistema considera gli annunci pertinenti associati al segmento di pubblico personalizzato ed esegue un'elaborazione aggiuntiva sugli annunci che una piattaforma di ad tech restituisce al dispositivo.

Le piattaforme di ad tech possono integrare queste API per implementare il remarketing che tutela la privacy degli utenti. Per le release future sono previsti supporto per 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:

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 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 per 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 la generazione di report di 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 file manifest dell'app:

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

6. Fai riferimento a una configurazione di servizi pubblicitari nell'elemento <application> del 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 viene fatto riferimento nel file manifest, ad esempio res/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.

Entrare a far parte di 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 l'joinCustomAudience() asincrono con l'oggetto JoinCustomAudienceRequest e gli oggetti Executor e OutcomeReceiver pertinenti.

Kotlin

val customAudienceManager: CustomAudienceManager =
    context.getSystemService(CustomAudienceManager::class.java)

// Initialize a custom audience.
val audience = CustomAudience.Builder()
    .setBuyer(buyer)
    .setName(name)
    ...
    .build()

// Initialize a custom audience request.
val joinCustomAudienceRequest: JoinCustomAudienceRequest =
    JoinCustomAudienceRequest.Builder().setCustomAudience(audience).build()

// Request to join a custom audience.
customAudienceManager.joinCustomAudience(joinCustomAudienceRequest,
    executor,
    outcomeReceiver)

Java

CustomAudienceManager customAudienceManager =
    context.getSystemService(CustomAudienceManager.class);

// Initialize a custom audience.
CustomAudience audience = new CustomAudience.Builder()
    .setBuyer(buyer)
    .setName(name)
    ...
    .build();

// Initialize a custom audience request.
JoinCustomAudienceRequest joinCustomAudienceRequest =
    new JoinCustomAudienceRequest.Builder().setCustomAudience(audience).build();

// Request to join a custom audience.
customAudienceManager.joinCustomAudience(joinCustomAudienceRequest,
    executor,
    outcomeReceiver);

La combinazione dei seguenti parametri identifica in modo univoco ogni oggetto CustomAudience su un dispositivo:

• owner: nome del pacchetto dell'app del proprietario. È impostato implicitamente sul nome del pacchetto dell'app chiamante.
• buyer: identificatore della rete pubblicitaria dell'acquirente che gestisce gli annunci per questo segmento di pubblico personalizzato.
• name: un nome o un identificatore arbitrario per il segmento di pubblico personalizzato.

Chiamare ripetutamente joinCustomAudience() con un'istanza diversa di CustomAudience aggiorna tutti gli elementi CustomAudience esistenti con i 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. Ciò può essere utile, ad esempio, per coinvolgere gli utenti non più attivi 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 sulle offerte attendibili: un URL HTTPS e un elenco di stringhe utilizzate durante il processo di selezione degli annunci per recuperare gli indicatori di offerta da un servizio chiave/valore attendibile.
• Annunci: un elenco di oggetti AdData corrispondenti agli annunci che partecipano alla selezione degli annunci. Ogni 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 che possono essere utilizzate dalla logica di offerta dell'acquirente durante il processo di selezione degli annunci.
  • Filtri annunci: una classe che contiene tutte le informazioni necessarie per il filtro degli annunci per l'installazione di app e la quota limite durante la selezione degli annunci.

Nota: i valori degli attributi "Indicatori per le offerte basate sugli utenti", "Dati delle offerte attendibili" e "Annunci" non devono superare i 10 KB in totale. Questi tre campi devono essere compilati per consentire a un segmento di pubblico personalizzato di partecipare alla selezione degli annunci.

Ecco un esempio di istanza di oggetto CustomAudience:

Kotlin

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

Java

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

Gestire i risultati 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 come gestire il risultato di joinCustomAudience():

Kotlin

var callback: OutcomeReceiver<Void, AdServicesException> =
    object : OutcomeReceiver<Void, AdServicesException> {
    override fun onResult(result: Void) {
        Log.i("CustomAudience", "Completed joinCustomAudience")
    }

    override fun onError(error: AdServicesException) {
        // Handle error
        Log.e("CustomAudience", "Error executing joinCustomAudience", error)
    }
};

Java

OutcomeReceiver callback = new OutcomeReceiver<Void, AdServicesException>() {
    @Override
    public void onResult(@NonNull Void result) {
        Log.i("CustomAudience", "Completed joinCustomAudience");
    }

    @Override
    public void onError(@NonNull AdServicesException error) {
        // Handle error
        Log.e("CustomAudience", "Error executing joinCustomAudience", error);
    }
};

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, leggi "Unisciti a un segmento di pubblico personalizzato".
3. Chiama il metodo leaveCustomAudience() asincrono con l'oggetto LeaveCustomAudienceRequest e gli oggetti Executor e OutcomeReceiver pertinenti.

Kotlin

val customAudienceManager: CustomAudienceManager =
    context.getSystemService(CustomAudienceManager::class.java)

// Initialize a LeaveCustomAudienceRequest
val leaveCustomAudienceRequest: LeaveCustomAudienceRequest =
    LeaveCustomAudienceRequest.Builder()
        .setBuyer(buyer)
        .setName(name)
        .build()

// Request to leave a custom audience
customAudienceManager.leaveCustomAudience(
    leaveCustomAudienceRequest,
    executor,
    outcomeReceiver)

Java

CustomAudienceManager customAudienceManager =
    context.getSystemService(CustomAudienceManager.class);

// Initialize a LeaveCustomAudienceRequest
LeaveCustomAudienceRequest leaveCustomAudienceRequest =
    new LeaveCustomAudienceRequest.Builder()
        .setBuyer(buyer)
        .setName(name)
        .build();

// Request to leave a custom audience
customAudienceManager.leaveCustomAudience(
    leaveCustomAudienceRequest,
    executor,
    outcomeReceiver);

Analogamente alla chiamata di joinCustomAudience(), OutcomeReceiver indica la fine di una chiamata API. Per proteggere la privacy, il risultato di un 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.

Pubblica selezione 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.

Kotlin

val adSelectionManager: AdSelectionManager =
  context.getSystemService(AdSelectionManager::class.java)

// Initialize AdSelectionConfig
val adSelectionConfig: AdSelectionConfig =
  AdSelectionConfig.Builder().setSeller(seller)
    .setDecisionLogicUrl(decisionLogicUrl)
    .setCustomAudienceBuyers(customAudienceBuyers)
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .setBuyerContextualAds(
      Collections.singletonMap(
        contextualAds.getBuyer(), contextualAds
      )
    ).build()

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

Java

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

// Initialize AdSelectionConfig
AdSelectionConfig adSelectionConfig =
  new AdSelectionConfig.Builder()
    .setSeller(seller)
    .setDecisionLogicUrl(decisionLogicUrl)
    .setCustomAudienceBuyers(customAudienceBuyers)
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .setBuyerContextualAds(
      Collections.singletonMap(contextualAds.getBuyer(), contextualAds)
    )
    .build();

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

Il metodo selectAds() richiede un input AdSelectionConfig, in cui devi specificare i seguenti parametri obbligatori:

• Venditore: l'identificatore della rete pubblicitaria del venditore che avvia la selezione degli annunci.
• URL della logica decisionale: un URL HTTPS sottoposto a query per ottenere la logica JavaScript della rete pubblicitaria del venditore.
  • URL HTTPS: viene eseguito una 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 che sono consentiti dal venditore a partecipare alla procedura di selezione degli annunci. Questi identificatori dell'acquirente corrispondono al CustomAudience.getBuyer() dei segmenti di pubblico personalizzati partecipanti.

I seguenti parametri possono essere facoltativamente specificati 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 candidati per gli annunci raccolti direttamente dagli acquirenti durante un'asta che si svolge al di fuori di un'asta Protected Audience.

Dopo aver 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 generare report sull'impressione dell'annuncio.

Se la selezione degli annunci non può essere completata per motivi quali argomenti non validi, timeout o un consumo eccessivo di risorse, il callback OutcomeReceiver.onError() fornisce un valore 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 ad tech 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 report, un URL di rendering e metadati degli annunci.

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

Kotlin

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

Java

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

L'oggetto ContextualAds risultante può quindi essere passato durante la creazione di AdSelectionConfig:

Kotlin

// Create a new ad
val noFilterAd: AdData = Builder()
  .setMetadata(JSONObject().toString())
  .setRenderUri(Uri.parse(baseUri + NO_FILTER_RENDER_SUFFIX))
  .build()
val noFilterAdWithBid = AdWithBid(noFilterAd, NO_FILTER_BID)
contextualAds.getAdsWithBid().add(noFilterAdWithBid)

Java

// Create a new ad
AdData noFilterAd = new AdData.Builder()
  .setMetadata(new JSONObject().toString())
  .setRenderUri(Uri.parse(baseUri + NO_FILTER_RENDER_SUFFIX))
  .build();
AdWithBid noFilterAdWithBid = new AdWithBid(noFilterAd, NO_FILTER_BID);
contextualAds.getAdsWithBid().add(noFilterAdWithBid);

Filtro degli annunci per l'installazione di app

Il filtro degli annunci per l'installazione di app ti consente di filtrare gli annunci di installazione per le app già installate su un dispositivo.

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

Kotlin

//Create a request for setting the app install advertisers
val adtech = AdTechIdentifier.fromString("your.enrolled.uri")
val adtechSet = setOf(adtech)
val request = SetAppInstallAdvertisersRequest(adtechSet)

//Set the app install advertisers in the ad selection manager
mAdSelectionManager.setAppInstallAdvertisers(
  request,
  mExecutor,
  object : OutcomeReceiver<Any?, Exception?>() {
    fun onResult(@NonNull ignoredResult: Any?) {
      Log.v("[your tag]", "Updated app install advertisers")
    }

    fun onError(@NonNull error: Exception?) {
      Log.e("[your tag]", "Failed to update app install advertisers", error)
    }
  })

Java

//Create a request for setting the app install advertisers
AdTechIdentifier adtech = AdTechIdentifier.fromString("your.enrolled.uri");
Set<AdTechIdentifier> adtechSet = Collections.singleton(adtech);
SetAppInstallAdvertisersRequest request = new SetAppInstallAdvertisersRequest(adtechSet);

//Set the app install advertisers in the ad selection manager
mAdSelectionManager.setAppInstallAdvertisers(
  request,
  mExecutor,
  new OutcomeReceiver<Object, Exception>() {
    @Override
    public void onResult(@NonNull Object ignoredResult) {
      Log.v("[your tag]", "Updated app install advertisers");
    }

    @Override
    public void onError(@NonNull Exception error) {
      Log.e("[your tag]", "Failed to update app install advertisers", error);
    }
  });

Quando viene eseguito il codice precedente, gli inserzionisti trasmessi sono quindi in grado di filtrare le app installate specificate durante la loro generazione dell'offerta. 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:

Kotlin

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

Java

// Instantiate AdFilters object with package names.
AdFilters filters = new AdFilters.Builder()
.setAppInstallFilters(
  new AppInstallFilters.Builder()
  .setPackageNames(Collections.singleton("example.target.app"))
  .build())
.build();

I publisher della domanda possono anche impostare un AdFilter per gli annunci presenti all'interno dei loro segmenti di pubblico personalizzati.

AdFilters può anche essere passato nel momento di creare un'istanza per un nuovo oggetto AdData:

Kotlin

// Instantiate an AdData object with the AdFilters created in the
// previous example.
val appInstallAd: AdData =
  Builder().setMetadata("{ ... }") // Valid JSON string
    .setRenderUri(Uri.parse("www.example-dsp1.com/.../campaign123.html"))
    .setAdFilters(filters).build()

Java

// Instantiate an AdData object with the AdFilters created in the
// previous example.
AdData appInstallAd = new AdData.Builder()
.setMetadata("{ ... }") // Valid JSON string
.setRenderUri(Uri.parse("www.example-dsp1.com/.../campaign123.html"))
    .setAdFilters(filters)
    .build();

Filtro delle quote limite

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

Un filtro di quota limite presenta due componenti principali: il tipo di evento dell'annuncio e la chiave del contatore annunci. I tipi di eventi correlati agli annunci disponibili sono:

• Vittoria: un evento con vittoria indica che l'annuncio ha vinto un'asta. Gli eventi di acquisizione vengono aggiornati automaticamente dall'API Protected Audience e non possono essere chiamati direttamente dallo sviluppatore. I dati relativi alle vittorie sono visibili solo agli annunci all'interno di un determinato segmento di pubblico personalizzato.
• Impressione: a prescindere da reportImpression, un chiamante sul dispositivo (SSP o MMP) utilizza updateAdCounterHistogram() per richiamare gli eventi di impressione nel punto del codice scelto. Gli eventi impressioni 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.
• Visualizzazione: l'evento viene richiamato dal chiamante sul dispositivo (SSP o MMP) in un punto del codice scelto utilizzando una chiamata al numero 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 richiamato dal chiamante sul dispositivo (SSP o MMP) in un punto del codice scelto utilizzando una chiamata al numero updateAdCounterHistogram(). Gli eventi di clic sono visibili a tutti gli annunci appartenenti a un determinato DSP e non solo 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 abbiano informazioni aggiornate sull'esposizione di un utente a un determinato annuncio. I tipi di eventi dell'annuncio non sono vincolati di forza all'azione dell'utente corrispondente e sono linee guida fornite per aiutare i chiamanti a strutturare il sistema di eventi. Per aumentare i contatori degli annunci in corrispondenza di un evento, l'attore on-device fornisce l'ID selezione annunci dell'asta dell'annuncio vincente.

Le chiavi del contatore degli annunci sono numeri interi con segno di 32 bit arbitrari assegnati da un team di tecnologia pubblicitaria dell'acquirente e corrispondono a un determinato insieme di annunci come definito dalla DSP. Poiché le chiavi del contatore 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 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 alto livello di coinvolgimento a seguito della vittoria di aste, visualizzazioni e clic sull'annuncio 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 ad annunci per mancini potrebbe filtrare quelli per mazze destrimane.

Per utilizzare la limitazione della frequenza nell'asta, devi prima creare oggetti KeyedFrequencyCap come mostrato di seguito:

Kotlin

// Value used when incrementing frequency counter
val adCounterKey = 123

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

// Frequency cap exceeded after 1 counts
val keyedFrequencyCapForImpression: KeyedFrequencyCap = Builder(
  adCounterKey, 1, Duration.ofSeconds(10)
).build()

Java

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

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

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

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

Kotlin

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

Java

AdFilters filters = new AdFilters.Builder()
    .setFrequencyCapFilters(new FrequencyCapFilters.Builder()
        .setKeyedFrequencyCapsForImpressionEvents(
            ImmutableObject.of(keyedFrequencyCapForImpression)
        )
        .setKeyedFrequencyCapsForClickEvents(
            ImmutableObject.of(keyedFrequencyCapForClick)
        )
    ).build();

Quando l'oggetto AdFilters viene compilato con i filtri di quota limite, può essere trasmesso al momento della creazione del segmento di pubblico personalizzato:

Kotlin

// Initialize a custom audience.
val audience: CustomAudience = Builder()
  .setBuyer(buyer)
  .setName(name)
  .setAds(
    listOf(
      Builder()
        .setRenderUri(renderUri)
        .setMetadata(JSONObject().toString())
        .setAdFilters(filters)
        .setAdCounterKeys(adCounterKeys)
        .build()
    )
  ).build()

Java

// Initialize a custom audience.
CustomAudience audience = new CustomAudience.Builder()
    .setBuyer(buyer)
    .setName(name)
    .setAds(Collections.singletonList(new AdData.Builder()
        .setRenderUri(renderUri)
        .setMetadata(new JSONObject().toString())
        .setAdFilters(filters)
        .setAdCounterKeys(adCounterKeys)
        .build()))
    .build();

Quando i filtri della quota limite vengono implementati in un segmento di pubblico personalizzato, la piattaforma SSP può richiamare gli eventi necessari di clic, visualizzazione o impressione.

Kotlin

val callerAdTech: AdTechIdentifier = mAdSelectionConfig.getSeller()

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

Java

AdTechIdentifier callerAdTech = mAdSelectionConfig.getSeller();

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

Gli annunci che hanno raggiunto i limiti del filtro della quota limite preimpostati 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 agli annunci.

Filtro degli annunci contestuali senza chiamate di rete

Se il dispositivo non prevede una richiesta di remarketing, puoi pubblicare la selezione degli annunci per gli annunci contestuali senza chiamate di rete. Grazie agli URI predefiniti e a un elenco di annunci contestuali con offerte, la piattaforma può saltare il recupero della logica di offerta, degli indicatori di offerta e degli indicatori di punteggio. La piattaforma utilizza un URI predefinito per selezionare l'annuncio contestuale con l'offerta più alta.

Per migliorare la latenza, i tecnici pubblicitari possono eseguire un flusso di selezione degli annunci che include solo annunci contestuali con funzionalità di filtro degli annunci senza chiamate di rete. Ciò si ottiene utilizzando URI predefiniti per l'assegnazione di punteggi. Fai riferimento alla sezione Nomi e casi d'uso degli URI predefiniti supportati per un elenco delle implementazioni di scoreAds.

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. Pubblica selezione annunci:

   adSelectionManager.selectAds(
       adSelectionConfig,
       executor,
       outcomeReceiver);
   

Esegui il tuo codice JavaScript di reporting mentre utilizzi URI predefiniti

Oggi, la piattaforma Privacy Sandbox dispone solo di un'implementazione di JavaScript di base per i report disponibile per gli URI predefiniti. Se vuoi eseguire il tuo codice JavaScript di reporting personale mentre continui a utilizzare URI predefiniti per la selezione di annunci a bassa latenza, puoi eseguire l'override di DecisionLogicUri tra la selezione degli annunci e l'esecuzione dei report.

1. Esegui i passaggi per eseguire la selezione degli annunci per gli annunci contestuali utilizzando 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 proprietari. La mediazione a cascata viene eseguita allo stesso modo indipendentemente dal fatto che l'asta sia avvenuta sul dispositivo o sia stata eseguita sui servizi di aste e offerte.

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:

Kotlin

class NetworkAdaptor {
    private val adSelectionManager : AdSelectionManager

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

    fun selectAds() {...}

    fun reportImpressions() {...}
}

Java

class NetworkAdaptor {
    AdSelectionManager adSelectionManager;

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

    public void selectAds() {...}

    public void reportImpressions() {...}
}

Ogni SDK ha i propri clienti e gestori del servizio di selezione degli annunci e una propria implementazione 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

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

Le reti di mediazione sono responsabili dell'esecuzione della catena di mediazione e del loro posizionamento al suo interno. La sezione successiva illustra 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 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 nelle reti di terze parti e i prezzi minimi delle offerte possono essere trasmessi al processo dell'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 l'offerta minima della rete di terze parti successiva nella catena. Se l'offerta proprietaria è superiore all'offerta minima, significa che l'SDK di mediazione viene posizionato davanti alla rete di terze parti.

Pubblica selezione annunci

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

Crea un AdSelectionFromRisultatosConfig

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.

Kotlin

fun  runSelectOutcome(
    adSelectionClient : AdSelectionClient,
    outcome1p : AdSelectionOutcome,
    network3p : NetworkAdapter) : ListenableFuture<AdSelectionOutcome?> {
    val config = AdSelectionFromOutcomesConfig.Builder()
        .setSeller(seller)
        .setAdSelectionIds(listOf(outcome1p))
        .setSelectionSignals({"bid_floor": bid_floor})
        .setSelectionLogicUri(selectionLogicUri)
        .build()
    return adSelectionClient.selectAds(config)
}

Java

public ListenableFuture<AdSelectionOutcome> runSelectOutcome(AdSelectionOutcome outcome1p,
                                              NetworkAdapter network3p) {
    AdSelectionFromOutcomesConfig config = new AdSelectionFromOutcomesConfig.Builder()
            .setSeller(seller)
            .setAdSelectionIds(Collection.singletonList(outcome1p))
            .setSelectionSignals({"bid_floor": bid_floor})
            .setSelectionLogicUri(selectionLogicUri)
            .build();

    return adSelectionClient.selectAds(config){}
}

L'override del metodo selectAds() per la mediazione a cascata richiede un input AdSelectionFromOutcomesConfig, in cui devi specificare i seguenti parametri obbligatori:

• Venditore: identificatore della rete pubblicitaria del venditore che avvia la selezione degli annunci.
• AdSelectionIds: un elenco singolo di un'esecuzione precedente di selectAds() per un annuncio proprietario.
• Indicatori di selezione degli annunci: un oggetto JSON, serializzato come stringa, contenente indicatori da utilizzare dalla logica di offerta dell'acquirente. In questo caso, includi 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. Vedi le firme delle funzioni obbligatorie 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.

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

Kotlin

val adSelectionManager = context.getSystemService(AdSelectionManager::class.java)

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

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

Java

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

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

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

Orchestrare la mediazione a cascata

Di seguito è riportato l'ordine delle operazioni per l'esecuzione del processo di mediazione.

1. Esegui la selezione degli annunci proprietari.
2. Esegui l'iterazione della catena di mediazione. Per ogni rete di terze parti:
   1. Crea AdSelectionFromOutcomeConfig che includa la outcomeId proprietaria e l'offerta minima 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 dell'SDK corrente. Se il risultato non è vuoto, restituisci l'annuncio.
3. Se nella catena non viene trovato alcun vincitore, restituisci l'annuncio proprietario.

Kotlin

fun runWaterfallMediation(mediationChain : List<NetworkAdapter>)
  : Pair<AdSelectionOutcome, NetworkAdapter> {
    val outcome1p = runAdSelection()

    var outcome : AdSelectionOutcome
    for(network3p in mediationChain) {
      outcome = runSelectOutcome(outcome1p, network3p)
      if (outcome1p.hasOutcome() && outcome.hasOutcome()) {
          return Pair(outcome, this)
      }

      outcome = network3p.runAdSelection()
      if(outcome.hasOutcome()) {
          return Pair(outcome, network3p)
      }
    }
  return Pair(outcome1p, this)
}

Java

class MediationNetwork {
    AdSelectionManager adSelectionManager;

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

    public void runAdSelection() {...}

    public void reportImpressions() {...}

    public Pair<AdSelectionOutcome, NetworkAdapter> runWaterfallMediation(
            List<NetworkAdapter> mediationChain) {
        AdSelectionOutcome outcome1p = runAdSelection();

        AdSelectionOutcome outcome;
        for(NetworkAdapter network3p: mediationChain) {
            if (outcome1p.hasOutcome() &&
              (outcome = runSelectOutcome(outcome1p, network3p)).hasOutcome()) {
                return new Pair<>(outcome, this);
            }

            if((outcome = network3p.runAdSelection()).hasOutcome()) {
                return new Pair<>(outcome, network3p);
            }
        }
        return new Pair<>(outcome1p, this);
    }

    /* Runs comparison by creating an AdSelectionFromOutcomesConfig */
    public AdSelectionOutcome runSelectOutcome(AdSelectionOutcome outcome1p,
                                              NetworkAdapter network3p) { ... }
}

Registra impressioni degli annunci

A seconda di come si svolge l'asta, esistono due flussi per la segnalazione di un'impressione dell'annuncio. Se sei una singola SSP che gestisce un'asta, segui questa sezione. Se vuoi implementare la mediazione a cascata, segui i passaggi indicati nella sezione dei report sulle impressioni della mediazione a cascata.

Report sulle impressioni singole 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. Inizializzare 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.

Java

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

// Initialize a ReportImpressionRequest
ReportImpressionRequest reportImpressionRequest =
        new ReportImpressionRequest.Builder()
                .setAdSelectionId(adSelectionId)
                .setAdSelectionConfig(adSelectionConfig)
                .build();

// Request to report the impression with the ReportImpressionRequest
adSelectionManager.reportImpression(
    reportImpressionRequest,
    executor,
    outcomeReceiver);

Kotlin

val adSelectionManager = context.getSystemService(AdSelectionManager::class.java)

// Initialize a ReportImpressionRequest
val adSelectionConfig: ReportImpressionRequest =
    ReportImpressionRequest.Builder()
        .setAdSelectionId(adSelectionId)
        .setAdSelectionConfig(adSelectionConfig)
        .build()

// Request to report the impression with the ReportImpressionRequest
adSelectionManager.reportImpression(
    reportImpressionRequest,
    executor,
    outcomeReceiver)

Inizializza ReportImpressionRequest con i seguenti parametri obbligatori:

• ID selezione annunci: un ID univoco 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, AdServicesException indica IllegalArgumentException come causa.
  • Tutti gli altri errori ricevono un'etichetta 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 report. Gli SDK che partecipano a una catena di mediazione devono fornire un metodo che il mediatore può richiamare per attivare il proprio flusso 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 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 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 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 piattaforma lato vendite:

• 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 del 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 elencati sopra.

Report sulle impressioni con il criterio del "best effort"

Il metodo reportImpression() è progettato per completare la generazione di report con il criterio del "best effort".

Nota:

• Se l'API non è in grado di determinare gli URL dei report sulle impressioni dalle funzioni JavaScript, verrà restituito un errore.
• Se la chiamata agli URL non riesce, l'attuale release di Anteprima per gli sviluppatori non produce errori. La logica di ripetizione per gli errori temporanei è prevista per le release future.
• Più chiamate a reportImpression() con gli stessi parametri possono comportare la registrazione più volte dei risultati della selezione degli annunci.

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 ricevere 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 semplicemente la funzione JavaScript della piattaforma dal codice JavaScript di reporting. 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;
}

Nota: per ricevere i report, le stringhe delle chiavi di interazione devono corrispondere ai dati segnalati dal venditore.

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 degli annunci, la chiave di interazione, i dati dell'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 stringa definita dal client che descrive l'azione segnalata. Deve corrispondere alla chiave registrata dal venditore o dall'acquirente nelle funzioni JavaScript dei report.
• Dati sull'interazione: una stringa contenente dati da includere nel report sugli eventi, da pubblicare di nuovo sui server di reporting.
• Destinazioni report: una maschera di bit che specifica se gli eventi devono essere segnalati all'acquirente, al venditore o a entrambi. Questi flag sono forniti dalla piattaforma e la maschera di destinazione finale può essere creata utilizzando operazioni bitwise. Per generare report per una destinazione, puoi utilizzare il flag fornito direttamente dalla piattaforma. Per generare report per più destinazioni, puoi utilizzare l'OR a livello di bit (|) per combinare i valori del flag.

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

• Il callback onResult() indica che la chiamata dell'interazione con il report è valida.
• Il callback onError() indica le seguenti condizioni possibili:
  • Se la chiamata viene effettuata quando l'app è in esecuzione in background, viene restituito un IllegalStateException con una descrizione dell'errore.
  • Se il client è limitato per le chiamate a reportInteraction(), viene restituito un LimitExceededException.
  • Se il pacchetto non è registrato per chiamare le API incentrate sulla tutela della privacy, viene restituito un valore SecurityException().
  • Se le interazioni dei report sull'app sono diverse dall'app chiamata 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.

Nota: l'assenza di errori non significa che i report siano stati generati. Piuttosto, è una garanzia che Protected Audience tenterà di registrare le interazioni a un certo punto.

Endpoint di reporting delle interazioni

L'API di interazione con i report invia richieste POST HTTPS agli endpoint forniti dalla Sell-Side Platform e dalla Piattaforma lato acquirente vincente. Protected Audience abbinerà le chiavi di interazione con gli URI dichiarati nel codice JavaScript di reporting ed emetterà una richiesta POST a ciascun endpoint per ogni interazione segnalata. Il tipo di contenuti della richiesta è testo normale con il corpo costituito dai dati di interazione.

Report sulle interazioni con il miglior sforzo

reportInteraction() è progettato per offrire la creazione di report tramite HTTP POST secondo il criterio del "best effort".

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 metadati dei segmenti di pubblico personalizzati con una procedura di aggiornamento in background giornaliera.

• Indicatori di offerta per gli utenti
• Dati di Trusted Bidding
• AdData elenco

Questa procedura esegue una query sull'URL di aggiornamento giornaliero definito nel segmento di pubblico personalizzato e l'URL potrebbe restituire una risposta in formato JSON.

• La risposta JSON può contenere uno qualsiasi dei campi di metadati supportati che devono essere aggiornati.
• Ogni campo JSON viene convalidato in modo indipendente. Il client ignora eventuali campi con formato non corretto, il che comporta l'assenza di aggiornamenti per quel determinato campo nella risposta.
• Una risposta HTTP vuota o un oggetto JSON vuoto "{}" non genera 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 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 dovrebbe 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 recuperate dalle proprietà con lo stesso nome del segmento di pubblico personalizzato che partecipa alla selezione degli annunci
  • activation_time e expiration_time sono il momento di attivazione e scadenza del segmento di pubblico personalizzato, espressi 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 fa riferimento l'offerta. Lo script può restituire una copia dell'annuncio ricevuto con metadati diversi. La proprietà render_url dell'annuncio dovrebbe essere invariata.
• bid: un valore in virgola mobile 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: lettura dal campo adSelectionSignals nel parametro API AdSelectionConfig

• contextual_signals, user_signals: oggetti JSON. Al momento vengono passati come oggetti vuoti e verranno completati nelle release future. Il loro formato non è 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 del segmento 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 l'esito positivo, diverso da zero per l'errore
• 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: visualizza la documentazione di scoreAd
• signals_for_buyer: un oggetto JSON restituito da reportResult
• contextual_signals, custom_audience_signals: visualizza la documentazione di 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()

Nota: questa funzione è fornita dalla piattaforma Android e non deve essere implementata dall'ad tech.

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 ciò che l'acquirente o il venditore sta registrando.
  • reporting_uri: un URI per ricevere i report sugli eventi. Dovrebbe essere specifico per il tipo di evento segnalato. Deve accettare una richiesta POST per gestire i dati riportati 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 runtime.

Viene lanciato un valore IllegalArgumentException se:

• nessuno dei parametri richiesti è presente nell'URI
• Nell'URI sono presenti parametri non riconosciuti

Casi d'uso e nomi di 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 anche una funzione di reporting di base per generare report su 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 dai 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 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 alcuni JavaScript durante la selezione degli annunci e i report sulle impressioni. Esistono due metodi per fornire questo codice JavaScript in un ambiente di test:

• Esegui un server con gli endpoint HTTPS richiesti che 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 pubblica la logica decisionale in JavaScript.
4. Un endpoint che fornisce indicatori di punteggio.
5. Endpoint del report sulle impressioni dell'acquirente vincente.
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 progetto README.

Esegui l'override del recupero remoto di JavaScript

Questa funzionalità è stata pensata per essere utilizzata per test end-to-end. Per eseguire l'override del recupero da 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">

Nota: assicurati di rimuovere "android:debuggable="true" prima di inviare la tua applicazione.

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 dimostra come leggere il codice del 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 pacchetto.

Eseguire l'override del codice JavaScript lato vendite

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

1. Inizializzare un oggetto AdSelectionManager.
2. Recupera un riferimento a TestAdSelectionManager dall'oggetto AdSelectionManager.
3. Crea un oggetto AdSelectionConfig.
4. Crea un elemento AddAdSelectionOverrideRequest con l'oggetto AdSelectionConfig e un String che rappresenta 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.

Kotlin

val testAdSelectionManager: TestAdSelectionManager =
  context.getSystemService(AdSelectionManager::class.java).getTestAdSelectionManager()

// Initialize AdSelectionConfig =
val adSelectionConfig = new AdSelectionConfig.Builder()
    .setSeller(seller)
    .setDecisionLogicUrl(decisionLogicUrl)
    .setCustomAudienceBuyers(customAudienceBuyers)
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .build()

// Initialize AddAddSelectionOverrideRequest
val request = AddAdSelectionOverrideRequest.Builder()
    .setAdSelectionConfig(adSelectionConfig)
    .setDecisionLogicJs(decisionLogicJS)
    .build()

// Run the call to override the JavaScript for the given AdSelectionConfig
// Note that this only takes effect in apps marked as debuggable
testAdSelectionManager.overrideAdSelectionConfigRemoteInfo(
    request,
    executor,
    outComeReceiver)

Java

TestAdSelectionManager testAdSelectionManager =
  context.getSystemService(AdSelectionManager.class).getTestAdSelectionManager();

// Initialize AdSelectionConfig =
AdSelectionConfig adSelectionConfig = new AdSelectionConfig.Builder()
    .setSeller(seller)
    .setDecisionLogicUrl(decisionLogicUrl)
    .setCustomAudienceBuyers(customAudienceBuyers)
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .build();

// Initialize AddAddSelectionOverrideRequest
AddAdSelectionOverrideRequest request = AddAdSelectionOverrideRequest.Builder()
    .setAdSelectionConfig(adSelectionConfig)
    .setDecisionLogicJs(decisionLogicJS)
    .build();

// Run the call to override the JavaScript for the given AdSelectionConfig
// Note that this only takes effect in apps marked as debuggable
testAdSelectionManager.overrideAdSelectionConfigRemoteInfo(
    request,
    executor,
    outComeReceiver);

Consulta la sezione Esegui selezione di annunci per ulteriori informazioni su ciò che rappresentano i singoli campi in AdSelectionConfig. 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 la pagina di esempio dell'app 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 le decisioni e la logica di reporting trasmessi come override.

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 si tenta di eseguire l'override 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 lato vendita e che tu abbia un riferimento a TestAdSelectionManager e AdSelectionConfig utilizzati nella sezione precedente.

Per reimpostare gli override per tutte le AdSelectionConfigs:

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

Kotlin

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

Java

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

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

Se la chiamata a resetAllAdSelectionConfigRemoteOverrides() non va a buon fine, il callback OutComeReceiver.onError() restituisce un valore AdServiceException. Se viene tentato di rimuovere gli override 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 il buyer e il nome del segmento di pubblico personalizzato che vuoi sostituire, oltre alla logica di offerta e ai dati che vuoi utilizzare come override
3. Chiama il metodo overrideCustomAudienceRemoteInfo() asincrono con l'oggetto AddCustomAudienceOverrideRequest e gli oggetti Executor e OutcomeReceiver pertinenti

Kotlin

val testCustomAudienceManager: TestCustomAudienceManager =
  context.getSystemService(CustomAudienceManager::class.java).getTestCustomAudienceManager()

// Join custom audience

// Build the AddCustomAudienceOverrideRequest
val request = AddCustomAudienceOverrideRequest.Builder()
    .setBuyer(buyer)
    .setName(name)
    .setBiddingLogicJs(biddingLogicJS)
    .setTrustedBiddingSignals(trustedBiddingSignals)
    .build()

// Run the call to override JavaScript for the given custom audience
testCustomAudienceManager.overrideCustomAudienceRemoteInfo(
    request,
    executor,
    outComeReceiver)

Java

TestCustomAudienceManager testCustomAudienceManager =
  context.getSystemService(CustomAudienceManager.class).getTestCustomAudienceManager();

// Join custom audience

// Build the AddCustomAudienceOverrideRequest
AddCustomAudienceOverrideRequest request =
    AddCustomAudienceOverrideRequest.Builder()
        .setBuyer(buyer)
        .setName(name)
        .setBiddingLogicJs(biddingLogicJS)
        .setTrustedBiddingSignals(trustedBiddingSignals)
        .build();

// Run the call to override JavaScript for the given custom audience
testCustomAudienceManager.overrideCustomAudienceRemoteInfo(
    request,
    executor,
    outComeReceiver);

I valori per acquirente e nome sono gli stessi utilizzati per creare il segmento di pubblico personalizzato. Scopri di più su questi campi.

Inoltre, puoi specificare altri due parametri:

• biddingLogicJs: codice JavaScript contenente la logica dell'acquirente utilizzato durante la selezione degli annunci. Vedi le firme delle funzioni richieste in questo codice JavaScript.
• trustedBiddingSignals: indicatori di offerta da utilizzare durante la selezione degli annunci. A scopo 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 di reporting che hai trasmesso come override.

Il callback onError() rappresenta due condizioni possibili.

• Se si tenta di eseguire l'override con argomenti non validi, AdServiceException indica IllegalArgumentException come causa.
• Se si tenta di eseguire l'override con un'app non in esecuzione in modalità di debug con le opzioni sviluppatore abilitate, AdServiceException indica IllegalStateException come causa.

Ripristinare le sostituzioni lato acquirente

Questa sezione presuppone che tu abbia sostituito il codice JavaScript lato acquisti e che tu abbia un riferimento al token TestCustomAudienceManager utilizzato nella sezione precedente.

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

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

Kotlin

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

Java

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

Dopo aver reimpostato gli override del lato acquisti, le chiamate successive a selectAds() utilizzano qualsiasi elemento biddingLogicUrl e trustedBiddingData memorizzato in CustomAudience per tentare di recuperare il codice 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.

Configura un server di reporting

Quando utilizzi gli override del recupero remoto, devi comunque configurare un server che il dispositivo o l'emulatore può raggiungere per rispondere agli eventi del report. Per i test è sufficiente un endpoint semplice che restituisce 200. Il repository GitHub include definizioni di servizi OpenAPI che possono essere implementate in una piattaforma di microservizi o simulata supportata. Per ulteriori dettagli, consulta il file README del progetto.

Quando cerchi le definizioni OpenAPI, cerca reporting-server.json. Questo file contiene un endpoint semplice che restituisce 200, che rappresenta un codice di risposta HTTP. Questo endpoint viene utilizzato durante la fase selectAds() e segnala all'API Protected Audience che la generazione di report sulle impressioni è stata completata 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.
• Esercita l'avvio della selezione degli annunci sul dispositivo tramite JavaScript ospitati in remoto.
• Osserva 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.

Componente	Descrizione limite	Valore limite
Segmento di pubblico personalizzato (CA)	Numero massimo di annunci per CA	100
	Numero massimo di CA per applicazione	1000
	Numero massimo di app che possono creare una CA	1000
	Ritardo massimo nel tempo di attivazione di una CA dalla relativa ora di creazione	60 giorni
	Tempo massimo per la scadenza di una CA dall'ora di attivazione	60 giorni
	Numero massimo di CA sul dispositivo	4000
	Dimensione massima del nome CA	200 byte
	Dimensione massima dell'URI di recupero giornaliero	400 byte
	Dimensione massima URI della logica di offerta	400 byte
	Dimensione massima dei dati di offerte attendibili	10 KB
	Dimensione massima degli indicatori di offerta per l'utente	10 kB
	Tariffa massima di chiamata a leaveCustomAudience per acquirente	1 al secondo
	Tariffa massima di chiamata a joinCustomAudience per acquirente	1 al secondo
Recupero in background CA	Timeout connessione	5 secondi
	Timeout lettura HTTP	30 secondi
	Dimensioni totali di download massime	10 KB
	Durata massima di un'iterazione di recupero	5 minuti
	Numero massimo di CA aggiornate per job	1000
Selezione degli annunci	Numero massimo di acquirenti	Da definire
	Numero massimo di CA per acquirente	Da definire
	Numero massimo di annunci in un'asta	Da definire
	Timeout iniziale della connessione	5 secondi
	Timeout di lettura della connessione	5 secondi
	Tempo di esecuzione massimo per AdSelection nel complesso	10 secondi
	Tempo di esecuzione massimo delle offerte per CA in AdSelection	5 secondi
	Tempo massimo di esecuzione per il punteggio in AdSelection	5 secondi
	Tempo di esecuzione massimo per acquirente in AdSelection	Da definire
	Dimensioni massime degli indicatori di selezione degli annunci/del venditore/per acquirente	Da definire
	Dimensione massima degli script venditore/acquirente	Da definire
	Tariffa massima chiamate per selectAds	1 QPS
Report sulle impressioni	Tempo minimo prima di rimuovere la selezione di annunci dalla persistenza	24 ore
	Numero massimo di selezioni di annunci per lo spazio di archiviazione	Da definire
	Dimensione massima dell'URL di output del report	Da definire
	Tempo massimo per i report sulle impressioni	Da definire
	Numero massimo di nuovi tentativi per le chiamate di notifica	Da definire
	Connessione in timeout	5 secondi
	Tempo di esecuzione complessivo massimo per reportImpression	2 secondi
	Frequenza di chiamata massima per reportImpressions	1 QPS
Report sugli eventi	Numero massimo di beacon per acquirente per asta	10
	Numero massimo di beacon per venditore per asta	10
	Dimensione massima della chiave evento	40 byte
	Dimensione massima dei dati sugli eventi	64 kB
Annunci	Dimensione massima dell'elenco di annunci	10 KB condivisi da tutti AdData in un'unica CA per i dati contestuali
URL	Lunghezza massima di qualsiasi stringa URL inserita come input	Da definire
Javascript	Tempo massimo di esecuzione	1 secondo per le offerte e il calcolo del punteggio per i report sulle impressioni
	Memoria massima utilizzata	10 MB

Segnalare bug e problemi

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