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 sviluppatori o Beta per selezionare la versione del programma che stai utilizzando, poiché le istruzioni possono variare.

---

Inviare feedback

L'API Protected Audience su Android (precedentemente nota come FLEDGE) include l'API Custom Audience e l'API Ad Selection. Gli inserzionisti e le piattaforme di ad tech possono utilizzare queste API per pubblicare annunci personalizzati in base al coinvolgimento in app precedente, il che limita la condivisione degli identificatori tra le app e limita la condivisione delle informazioni sull'interazione con le app di un utente con terze parti.

L'API Custom Audience è incentrata sull'astrazione "segmento di pubblico personalizzato", che rappresenta un gruppo di utenti con intenzioni comuni. Un inserzionista può registrare un utente con un segmento di pubblico personalizzato e associare annunci pertinenti a questo segmento. Queste informazioni vengono memorizzate in locale e possono essere utilizzate per definire le offerte degli inserzionisti, i filtri degli annunci e il rendering degli annunci.

L'API Ad Selection fornisce un framework che consente a più sviluppatori di eseguire un'asta a livello locale per un segmento di pubblico personalizzato. Per ottenere questo risultato, il sistema prende in considerazione gli annunci pertinenti associati al segmento di pubblico personalizzato ed esegue un'ulteriore elaborazione sugli annunci che una piattaforma di tecnologia pubblicitaria restituisce al dispositivo.

Le piattaforme ad tech possono integrare queste API per implementare il remarketing che tutela la privacy dell'utente. Per le versioni future è previsto il supporto per casi d'uso aggiuntivi, 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 e pubblicare 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 il tuo 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. Includi un'autorizzazione ACCESS_ADSERVICES_CUSTOM_AUDIENCE nel file manifest dell'app:

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

5. Fai riferimento a una configurazione di servizi pubblicitari nell'elemento <application> del manifest:

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

6. 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 per i servizi pubblicitari e sul controllo dell'accesso agli SDK.

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

7. Per impostazione predefinita, l'API Ad Selection applica dei limiti alla quantità massima di memoria che può allocare uno script di report sull'asta o sulle impressioni. La funzionalità di limitazione della memoria richiede WebView versione 105.0.5195.58 o successiva. La piattaforma applica un controllo della versione e le chiamate alle API selectAds e reportImpression non vanno a buon fine se questo non è soddisfatto. Sono disponibili due opzioni per l'impostazione:

   • Opzione 1: esegui il comando adb riportato di seguito per disattivare questa verifica:

     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.

Entra in un segmento di pubblico personalizzato

Un segmento di pubblico personalizzato rappresenta un gruppo di utenti con intenzioni o interessi comuni, come deciso dall'app di un inserzionista. Un'app o un SDK può utilizzare un segmento di pubblico personalizzato per indicare un determinato segmento di pubblico, ad esempio un utente che ha lasciato degli articoli in un carrello degli acquisti. Per creare o unirti 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. Richiama l'elemento 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 ciascun oggetto CustomAudience su un dispositivo:

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

Chiamare joinCustomAudience() ripetutamente con un'istanza diversa di CustomAudience aggiorna qualsiasi CustomAudience esistente con i parametri owner, buyer e name corrispondenti. Per contribuire a tutelare la privacy, il risultato dell'API non fa distinzione tra "creazione" e "aggiornamento".

Inoltre, CustomAudience deve essere creato con questi parametri obbligatori:

• URL di aggiornamento giornaliero: un URL HTTPS eseguito ogni giorno una query in background per aggiornare gli indicatori di offerte per gli utenti di un segmento di pubblico personalizzato, i dati sulle offerte attendibili e visualizzare gli URL e i metadati per gli annunci.
• URL logica di offerta: un URL HTTPS su cui è stata eseguita una query durante la selezione degli annunci per recuperare la logica di offerta JavaScript di un acquirente. Vedi le firme delle funzioni richieste in questo codice JavaScript.
• ID 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:

• Ora di attivazione: un segmento di pubblico personalizzato può partecipare alla selezione degli annunci e agli aggiornamenti giornalieri solo dopo il relativo tempo di attivazione. Questo può essere utile, ad esempio, per coinvolgere gli utenti non più attivi di un'app.
• Data di scadenza: un'ora futura dopo la quale il segmento di pubblico personalizzato viene rimosso dal dispositivo.
• Indicatori delle offerte dell'utente: una stringa JSON contenente indicatori sugli utenti, come le impostazioni internazionali preferite dell'utente, che vengono utilizzati da JavaScript per la logica di offerta di un acquirente per generare offerte durante il processo di selezione degli annunci. Questo formato consente alle piattaforme di ad tech di riutilizzare il codice su più piattaforme e di semplificarne l'utilizzo nelle funzioni JavaScript.
• Dati di offerta attendibili: un URL HTTPS e un elenco di stringhe utilizzate durante il processo di selezione degli annunci che recuperano 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 devono essere utilizzate dalla logica di offerta dell'acquirente durante il processo di selezione degli annunci.
  • Filtri degli annunci: una classe contenente 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 per gli attributi "Indicatori delle offerte dell'utente", "Dati di offerta attendibili " e"Annunci" non devono superare i 10 kB in totale. Questi tre campi devono essere compilati affinché un segmento di pubblico personalizzato possa partecipare alla selezione degli annunci.

Ecco un esempio di creazione di un'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 joinCustomAudience()

Il metodo joinCustomAudience() asincrono 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 correttamente.
• Il callback onError() indica due possibili condizioni.
  • Se JoinCustomAudienceRequest viene inizializzato con argomenti non validi, AdServicesException indica una IllegalArgumentException come causa.
  • Tutti gli altri errori ricevono un elemento AdServicesException con IllegalStateException come causa.

Ecco un esempio di gestione del 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);
    }
};

Esci da 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 una CustomAudience in base ai suoi parametri univoci:

1. Inizializza l'oggetto CustomAudienceManager.
2. Inizializza LeaveCustomAudienceRequest con i valori buyer e name del segmento di pubblico personalizzato. Per saperne di più su questi campi di immissione, consulta "Utilizzare un segmento di pubblico personalizzato".
3. Richiama 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 a joinCustomAudience(), OutcomeReceiver segnala 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 sia stato rimosso o meno.

Pubblica 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. Richiama 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: identificatore della rete pubblicitaria del venditore che avvia la selezione degli annunci.
• URL logica di decisione: un URL HTTPS a cui è stata eseguita una query per ottenere la logica JavaScript della rete pubblicitaria del venditore.
  • URL HTTPS: è stata eseguita una query per ottenere la logica JavaScript della rete pubblicitaria del venditore. Scopri le firme delle funzioni richieste.
  • URI predefinito: che segue il formato di selezione degli annunci di FLEDGE. Viene generato IllegalArgumentException se viene passato un URI predefinito non supportato o in un formato non corretto.
• Acquirenti di segmenti di pubblico personalizzati: un elenco completo di identificatori per le reti pubblicitarie degli acquirenti a cui il venditore ha consentito di partecipare al processo di selezione degli annunci. Questi identificatori acquirente corrispondono a CustomAudience.getBuyer() dei segmenti di pubblico personalizzati partecipanti.

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

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

Una volta selezionato un annuncio, i risultati, le offerte e gli indicatori vengono conservati 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 di annunci univoco dell'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 un consumo eccessivo di risorse, il callback OutcomeReceiver.onError() fornisce un AdServicesException con i seguenti comportamenti:

• Se la selezione degli annunci viene avviata con argomenti non validi, AdServicesException indica IllegalArgumentException come causa.
• Tutti gli altri errori ricevono un elemento 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 essere inclusi nell'asta utilizzando il AdSelectionConfig; a quel punto funzionano come gli annunci sui dispositivi, inclusa l'idoneità al filtro degli annunci per esclusione. Una volta completata l'asta di Protected Audience, devi richiamare reportImpression(). In questo modo viene richiamato reportWin() nell'annuncio contestuale vincente, nello stesso pattern dei 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 di reporting, un URL di rendering e i metadati dell'annuncio.

Per implementare annunci contestuali nell'app, l'app di destinazione deve creare un oggetto ContextualAds:

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ò essere trasmesso 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 possono filtrare in base al pacchetto installato. Questo deve avvenire nell'app che vuoi scegliere come target con 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 possono quindi escludere le app installate specificate durante la generazione delle offerte. Se devi impedire a un inserzionista di accedere allo stato di installazione di questa app, esegui di nuovo questo codice rimuovendo le informazioni sull'inserzionista.

Il passaggio successivo consiste nell'impostare il filtro degli annunci all'interno dell'app del publisher. La parte che pubblica l'annuncio nell'app del publisher (che molto probabilmente è un SDK Supply-Side) deve inizializzare l'oggetto AdFilters con le informazioni relative agli annunci relativi alle app da 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 lato domanda possono anche impostare un AdFilter per gli annunci che esistono all'interno dei loro segmenti di pubblico personalizzati.

AdFilters può essere trasmesso anche al momento di creare un'istanza di 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 per la quota limite

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

Esistono due componenti principali di un filtro quota limite: il tipo di evento annuncio e la chiave del contatore annunci. I tipi di eventi dell'annuncio disponibili che possono essere utilizzati sono:

• Vincere (disponibile a breve): un evento vincente 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. Questi dati sono visibili solo agli annunci all'interno di un determinato segmento di pubblico personalizzato.
• Impressione: separatamente da reportImpression, un chiamante on-device (SSP o MMP) utilizza updateAdCounterHistogram() per richiamare gli eventi di impressioni nel punto del codice scelto. Gli eventi di impressione sono visibili a tutti gli annunci appartenenti a una determinata DSP e non si limitano agli annunci dello stesso segmento di pubblico personalizzato.
• Visualizza: l'evento viene richiamato dal chiamante sul dispositivo (SSP o MMP) in un punto del codice scelto tramite una chiamata al numero updateAdCounterHistogram(). Gli eventi di visualizzazione sono visibili a tutti gli annunci appartenenti a una determinata DSP e non solo agli annunci nello stesso pubblico personalizzato.
• Clic: l'evento viene richiamato dal chiamante sul dispositivo (SSP o MMP) in un momento nel codice scelto tramite una chiamata al numero updateAdCounterHistogram(). Gli eventi di clic sono visibili a tutti gli annunci appartenenti a una determinata DSP e non solo agli annunci dello stesso segmento di pubblico personalizzato.

Nell'app del publisher, una SSP o una MMP con una presenza sul dispositivo richiama gli eventi relativi 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 forzati associati all'azione dell'utente corrispondente e sono linee guida fornite per aiutare i chiamanti a strutturare il proprio sistema di eventi. Per aumentare i contatori degli annunci al momento di un evento, l'attore on-device fornisce l'ID selezione degli annunci dell'asta dell'annuncio vincente.

Le chiavi del contatore degli annunci sono numeri interi arbitrari con firma a 32 bit assegnati dalla tecnologia pubblicitaria di un acquirente e corrispondono a un determinato insieme di annunci come definito dalla DSP. Poiché le chiavi del contatore annunci sono limitate solo agli annunci appartenenti a una determinata DSP, queste possono essere selezionate senza sovrapporsi agli istogrammi di un'altra tecnologia pubblicitaria. Le chiavi dei contatori degli annunci vengono utilizzate per incrementare gli identificatori specifici di DSP negli annunci di una DSP o all'interno di un determinato segmento di pubblico personalizzato, in modo da escludere gli annunci di aste future.

Le chiavi dei contatori possono essere utilizzate per dare priorità agli annunci che hanno maggiori probabilità di essere interessanti per un determinato utente in base alle sue interazioni con altri annunci di una determinata tecnologia pubblicitaria dell'acquirente. Ad esempio, un annuncio che ha ricevuto un elevato livello di coinvolgimento grazie alla vincita di aste dell'annuncio, visualizzazioni e clic rappresenta un punto dati dedotto. Per chiarire meglio questo punto, un annuncio relativo a mazze da golf mancini potrebbe indicare che l'utente non sarebbe interessato a quelli per destri. Un filtro per la quota limite impostato per un tasto del contatore assegnato agli annunci della mano sinistra potrebbe filtrare gli annunci per i club della mano destra.

Per utilizzare la quota limite nella tua asta, devi prima creare KeyedFrequencyCap oggetti 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 trasferirli in 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 per la quota limite, puoi trasmetterlo 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 per la quota limite vengono implementati in un segmento di pubblico personalizzato, la SSP può richiamare gli eventi di clic, visualizzazione o impressione necessari.

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 preimpostati del filtro per la quota limite vengono esclusi dall'asta. I filtri vengono applicati prima dell'esecuzione della logica di offerta per le aste on-device e durante la generazione del payload per le aste dei servizi di offerte e aste.Questo toolkit offre ai tecnici pubblicitari la flessibilità di utilizzare le interazioni tra gli utenti e gli annunci all'interno dei loro segmenti di pubblico personalizzati per concentrare il targeting degli annunci, riducendo al minimo la sovraesposizione degli annunci.

Filtro contestuale degli annunci senza chiamate di rete

Se sul dispositivo non è presente alcuna domanda 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, gli ad tech 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 gli URI predefiniti per gli indicatori di punteggio. Consulta la sezione relativa ai nomi e ai casi d'uso degli URI predefiniti supportati per un elenco di implementazioni 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 il seguente codice:

   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 può indicare che non vuoi utilizzare il recupero di indicatori attendibili per il 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 degli annunci:

   adSelectionManager.selectAds(
       adSelectionConfig,
       executor,
       outcomeReceiver);
   

Esegui il tuo codice JavaScript per i report utilizzando gli URI predefiniti

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

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

2. Crea una copia del tuo AdSelectionConfig prima di eseguire il reporting

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

3. Eseguire il 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 mediazione a cascata

La mediazione con struttura a cascata richiede che più SDK di terze parti (reti di terze parti) siano orchestrati da una rete di mediazione SDK proprietaria. La mediazione con struttura a cascata viene eseguita allo stesso modo indipendentemente dal fatto che l'asta si sia svolta sul dispositivo o nei 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 l'esecuzione di un'asta:

• Pubblica selezione degli annunci
• Impressioni del 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 dei servizi di selezione degli annunci e le proprie implementazioni di selectAds e reportImpressions. I provider di SDK possono consultare le sezioni su come eseguire la selezione degli annunci per le aste on-device o il documento esplicativo B&A per le aste B&A. Segui come segnalare le impressioni degli annunci (seguendo i singoli report sulle impressioni della 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 generare report sulle impressioni degli annunci.

Le reti di mediazione sono responsabili dell'esecuzione della catena di mediazione e del loro posizionamento nella catena di mediazione. La prossima sezione spiega come impostare ed eseguire questo processo.

Recuperare la catena di mediazione e i prezzi minimi delle offerte

La rete di mediazione è responsabile del recupero degli annunci contestuali proprietari, della catena di mediazione e degli annunci minimi delle reti di terze parti. Ciò può accadere in una richiesta di recupero degli annunci contestuali eseguiti dalla rete di mediazione. La catena di mediazione determina come eseguire l'iterazione attraverso le reti di terze parti e i prezzi minimi delle offerte possono essere trasmessi al processo di asta come adSelectionSignals.

Posizionamento nella rete nella catena di mediazione

Un SDK di mediazione può inserirsi nella catena di mediazione in base all'eCPM effettivo delle offerte per 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 degli annunci

Per recuperare un annuncio proprietario, la rete di mediazione può eseguire un'asta on-device seguendo i passaggi nella sezione Esegui selezione degli annunci. Ciò genera un annuncio proprietario, un'offerta e un AdSelectionId che vengono utilizzati nella procedura di mediazione.

Crea un AdSelectionFromResultsConfig

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 il codice JavaScript che seleziona un annuncio tra più candidati. L'elenco di AdSelectionIds insieme alle relative offerte e agli indicatori viene passato al JavaScript, che può restituire uno degli AdSelectionIds se supera il prezzo minimo dell'offerta o nessuno se la catena di mediazione deve continuare.

Le reti di mediazione creano un AdSelectionFromOutcomesConfig utilizzando il AdSelectionId proprietario della sezione precedente e il prezzo minimo per la rete di terze parti che viene presa in considerazione. È necessario creare 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 l'offerta minima recuperata per la rete di terze parti specificata.
• URI della logica di selezione: un URL HTTPS su cui è stata eseguita una query durante la selezione degli annunci per recuperare il codice JavaScript della rete di mediazione per la selezione di un annuncio vincente. Vedi le firme delle funzioni richieste in questo codice JavaScript. JavaScript dovrebbe restituire l'annuncio di terze parti se l'offerta è superiore all'offerta minima, altrimenti 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 si trova per 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. Eseguire l'iterazione sulla catena di mediazione. Per ogni rete di terze parti:
   1. Crea una AdSelectionFromOutcomeConfig che includa il outcomeId proprietario 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 SDK corrente. Se il risultato non è vuoto, restituisci l'annuncio.
3. Se la catena non trova un 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

Esistono due flussi per segnalare un'impressione dell'annuncio a seconda di come viene eseguita l'asta. Se hai una sola SSP che esegue un'asta, segui questa sezione. Se vuoi implementare la mediazione con struttura a cascata, segui la procedura descritta nella sezione dei report sulle impressioni della mediazione con struttura a cascata.

Report sulle singole impressioni della SSP

Dopo aver scelto l'annuncio vincente dal flusso di lavoro di selezione degli annunci, puoi segnalare l'impressione alle piattaforme lato acquisti e Sell-Side Platform 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 degli annunci.
3. Richiama 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 di un utente del dispositivo che identifica una selezione di annunci riuscita.
• Configurazione della selezione degli annunci: la stessa configurazione utilizzata nella chiamata selectAds() identificata dall'ID selezione degli annunci fornito.

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

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

Report sulle impressioni della mediazione con struttura 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 al mediatore un metodo da richiamare per attivare il proprio flusso di report. Gli SDK che partecipano a un'asta con mediazione possono seguire i passaggi riportati sopra per implementare i propri report.

Le SSP possono usare questo esempio di codice dell'SDK di terze parti come prototipo per partecipare ai flussi di mediazione:

Pair<AdSelectionOutcome, NetworkAdapter> winnerOutcomeAndNetwork =
         mediationSdk.orchestrateMediation(mediationChain);

if (winner.first.hasOutcome()) {
      winner.second.reportImpressions(winner.first.getAdSelectionId());

Endpoint dei report sulle impressioni

L'API Report delle impressioni invia richieste HTTPS GET agli endpoint forniti dalla Sell-Side Platform e dalla Buy-Side Platform vincente:

Endpoint della piattaforma lato acquisti:

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

Endpoint della piattaforma lato vendita:

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

Report sui servizi di asta e offerta

Un'asta eseguita nei servizi di offerte e aste avrà tutte le informazioni dei report necessarie, 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 nella piattaforma e, di conseguenza, i report sulle impressioni e sugli annunci seguono gli stessi passaggi elencati sopra.

Report sulle impressioni con il massimo sforzo

Il metodo reportImpression() è progettato per consentire il completamento della generazione di report secondo il criterio del "best effort".

Nota:

• Se l'API non è in grado di determinare gli URL dei report sulle impressioni dalle funzioni JavaScript, restituirà un errore.
• Se la chiamata agli URL non va a buon fine, la release di Anteprima per gli sviluppatori corrente non produce errori. La logica di nuovo tentativo per gli errori temporanei è pianificata per le release future.
• Più chiamate a reportImpression() con gli stessi parametri possono comportare la segnalazione più volte dei risultati della selezione degli annunci.

Segnala interazioni con gli annunci

Protected Audience supporta la generazione di report sulle interazioni più granulari di un annuncio visualizzato. Ciò può includere interazioni come tempo di visualizzazione, clic, passaggi del mouse o qualsiasi altra metrica utile che è possibile raccogliere. La procedura per ricevere questi report prevede due passaggi. In primo luogo, acquirenti e venditori devono registrarsi per ricevere questi report nel codice JavaScript dei report. Successivamente, il cliente dovrà segnalare questi eventi.

Registrazione per ricevere eventi di interazione

La registrazione degli eventi di interazione viene eseguita nelle funzioni JavaScript reportResult() dell'acquirente e del venditore reportWin() utilizzando una funzione JavaScript fornita dalla piattaforma registerAdBeacon. Per ricevere un report su un evento, basta chiamare la funzione JavaScript della piattaforma dal codice JavaScript dei 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)
    registerAdBeacon("view", viewUri)
    registerAdBeacon("hover", hoverUri)

    return reportingUrl;
}

Nota: le stringhe della chiave di interazione devono corrispondere a quanto riportato dal venditore per ricevere i report.

Segnalare gli eventi di interazione

Dopo aver segnalato un'impressione, i clienti possono segnalare le interazioni alle piattaforme lato acquisti e Sell-Side Platform registrate in precedenza con il metodo AdSelectionManager.reportInteraction(). Per segnalare un evento relativo all'annuncio:

1. Inizializza un oggetto AdSelectionManager.
2. Crea un oggetto ReportInteractionRequest con l'ID selezione degli annunci, la chiave di interazione, i dati sull'interazione e la destinazione del report.
3. Richiama 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 annuncio recuperato da un elemento 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 di interazione: una stringa contenente dati da includere nel report sugli eventi da POSTARE ai 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 a bit. Per generare report su una destinazione, puoi utilizzare il flag fornito direttamente dalla piattaforma. Per generare report per più destinazioni, puoi utilizzare l'operatore bit a bit (|) per combinare i valori dei flag.

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

• Il callback onResult() indica che la chiamata di 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 viene limitato per chiamare reportInteraction(), viene restituito un LimitExceededException.
  • Se il pacchetto non è registrato per chiamare le API Privacy Preserve, viene restituito un SecurityException().
  • Se le interazioni con i report dell'app sono diverse dall'app che ha chiamato selectAds(), viene restituito un IllegalStateException.
• Se l'utente non ha acconsentito ad abilitare le API Privacy Sandbox, la chiamata non andrà a buon fine e non verrà eseguita.

Nota: l'assenza di errori non significa che la segnalazione è stata effettuata. Garantisce, invece, che Protected Audience tenterà di segnalare le interazioni a un certo punto.

Endpoint dei report sull'interazione

L'API Report Interop invia richieste HTTPS POST agli endpoint forniti dalla Sell-Side Platform e dalla Buy-Side Platform vincente. Protected Audience corrisponderà le chiavi di interazione agli URI dichiarati nel codice JavaScript dei report e invierà una richiesta POST a ciascun endpoint per ogni interazione segnalata. Il tipo di contenuto della richiesta è in testo normale, mentre il corpo corrisponde ai dati sull'interazione.

Report sulle interazioni con il massimo sforzo

reportInteraction() è progettato per consentire il completamento con il massimo sforzo della generazione di report tramite HTTP POST.

Aggiornamento giornaliero in background

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

• Indicatori di offerta utente
• Dati sulle 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 di metadati supportati che devono essere aggiornati.
• Ogni campo JSON viene convalidato in modo indipendente. Il client ignora tutti i campi non corretti, il che non comporta aggiornamenti a quel particolare campo nella risposta.
• Una risposta HTTP vuota o un oggetto JSON vuoto "{}" non comportano l'aggiornamento dei metadati.
• Le dimensioni del messaggio di risposta devono essere limitate a 10 kB.
• Tutti gli URI sono obbligatori per l'utilizzo del protocollo 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 per la 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 delle offerte 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 di decisione specificato nel parametro AdSelectionConfig per l'API di selezione degli annunci. Il codice JavaScript restituito deve includere le seguenti funzioni:

• scoreAd()
• reportResult()

generateBid()

function generateBid(
  ad,
  auction_signals,
  per_buyer_signals,
  trusted_bidding_signals,
  contextual_signals,
  user_signals,
  custom_audience_bidding_signals) {
  return {'status': 0, 'ad': ad, 'bid': ad.metadata.result };
}

Parametri di input:

• ad: un oggetto JSON con il formato var ad = { 'render_url': url, 'metadata': json_metadata };
• auction_signals, per_buyer_signals: oggetti JSON specificati nell'oggetto di configurazione dell'asta

• custom_audience_bidding_signals: oggetto JSON generato dalla piattaforma. Il formato di questo oggetto JSON è:

  var custom_audience_signals = {
    "owner":"ca_owner",
    "buyer":"ca_buyer",
    "name":"ca_name",
    "activation_time":"ca_activation_time_epoch_ms",
    "expiration_time":"ca_expiration_time_epoch_ms",
    "user_bidding_signals":"ca_user_bidding_signals"
  }
  

  dove:

  • owner, buyer e name sono stringhe tratte dalle proprietà con lo stesso nome del segmento di pubblico personalizzato che partecipa alla selezione degli annunci
  • activation_time e expiration_time indicano il tempo di attivazione e scadenza del segmento di pubblico personalizzato, espresso in secondi dall'epoca di Unix.
  • ca_user_bidding_signals è una stringa JSON specificata nel campo userBiddingSignals dell'elemento 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 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 rimanere inalterata.
• 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 corretta
  • 1: (o qualsiasi valore diverso da zero) nel caso in cui uno degli indicatori di input non sia valido. Nel caso in cui l'offerta generate-bid restituisca un valore diverso da zero, il processo di offerta viene invalidato per tutti gli annunci dell'autorità di certificazione

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. Attualmente, vengono passati come oggetti vuoti e verranno riempiti nelle versioni future. Il loro 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'attuale acquirente del segmento di pubblico personalizzato. Vuota se la mappa non contiene voci per l'acquirente specificato.

Output:

• score: un valore in virgola mobile che rappresenta il valore del punteggio per questo annuncio
• status: un valore intero che può essere:
  • 0: per un'esecuzione corretta
  • 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 del processo, 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 gli errori
• result: uno dei risultati trasmessi o nulli

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 l'esito positivo e un valore diverso da zero per gli errori
• results: un oggetto JSON contenente:
  • signals_for_buyer: un oggetto JSON che viene 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'esito positivo e un valore diverso da zero per gli errori
• results: un oggetto JSON contenente:
  • reporting_url: un URL utilizzato dalla piattaforma per notificare l'impressione al venditore

registerAdBeacon()

Nota: questa funzionalità è fornita dalla piattaforma Android e non deve essere implementata dalla tecnologia pubblicitaria.

function registerAdBeacon(
  interaction_key,
  reporting_uri
)

Parametri di input:

• interaction_key: una stringa che rappresenta l'evento. Questo viene utilizzato dalla piattaforma in un secondo momento quando vengono segnalate le interazioni degli eventi per cercare il reporting_uri che deve essere notificato. Questa chiave deve corrispondere a ciò che l'acquirente o il venditore sta registrando e ciò che il venditore sta segnalando.
• reporting_uri: un URI per ricevere i report sugli eventi. Deve essere specifico per il tipo di evento segnalato. Deve accettare una richiesta POST per gestire tutti i dati segnalati insieme all'evento.

URI predefiniti per la selezione degli annunci

Gli URI predefiniti offrono agli ad tech la possibilità di designare le funzioni JavaScript per la logica decisionale per la selezione degli annunci nelle classi AdSelectionConfig e AdSelectionFromOutcomesConfig. Gli URI predefiniti non richiedono chiamate di rete per scaricare il codice JavaScript corrispondente. Gli ad tech possono usare 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 valore IllegalArgumentException se:

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

Casi d'uso e nomi degli URI predefiniti supportati

Caso d'uso 1: selezione di annunci

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

Nome URI predefinito: highest-bid-wins

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

Parametri obbligatori

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

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

Utilizzo

Se l'URL del 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: 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 codice 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 minimo dell'offerta trasmesso nel 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 codice 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 restituisca il codice 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 7 endpoint HTTPS a cui può accedere il tuo emulatore o il tuo dispositivo di test:

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 pubblica il codice JavaScript della logica decisionale.
4. Un endpoint che gestisce gli indicatori di punteggio.
5. Endpoint del report sulle impressioni dell'acquirente vincente.
6. Endpoint dei report sulle impressioni del venditore.
7. Un endpoint per pubblicare gli aggiornamenti giornalieri per un segmento di pubblico personalizzato.

Per praticità, il repository GitHub fornisce codice JavaScript di base per lo scopo del test. Include inoltre le definizioni del servizio OpenAPI, di cui è possibile eseguire il deployment in una simulazione supportata o su una piattaforma di microservizi. Per maggiori dettagli, consulta il progetto README.

Esegui l'override del recupero remoto di JavaScript

Questa funzionalità è pensata per essere utilizzata per test end-to-end. Per eseguire l'override del recupero remoto, l'app deve essere eseguita in modalità di debug con le opzioni sviluppatore attivate.

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

<application
  android:debuggable="true">

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

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 offerte, le decisioni sui 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 dimostra come leggere il codice dal file e prepararlo per l'utilizzo come override.

È possibile eseguire l'override di JavaScript lato vendite e lato acquirente in modo indipendente, anche se è necessario un endpoint HTTPS per pubblicare qualsiasi codice JavaScript per cui non fornisci override. Leggi il file README per informazioni su come configurare un server per gestire questi casi.

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

Esegui override di JavaScript lato vendite

Per configurare un override di JavaScript lato vendita, segui questi passaggi come mostrato nell'esempio di codice riportato di seguito:

1. Inizializza 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. Richiama 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 la selezione degli annunci per ulteriori informazioni su ciò che ciascun campo della AdSelectionConfig rappresenta. 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, decisionLogicJs deve contenere le firme delle funzioni lato venditore appropriate. Per un esempio di come leggere un file JavaScript come stringa, consulta l'app di esempio dell'API Protected Audience su GitHub.

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

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

Il callback onError() indica due possibili condizioni:

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

Reimpostare override lato vendite

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

Per reimpostare le sostituzioni 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 lato vendite, le chiamate a selectAds() utilizzano qualsiasi decisionLogicUrl archiviato in AdSelectionConfig per tentare di recuperare il codice JavaScript richiesto.

Se la chiamata al numero resetAllAdSelectionConfigRemoteOverrides() non va a buon fine, il callback OutComeReceiver.onError() fornisce un'AdServiceException. Se il tentativo di rimozione degli override viene eseguito con un'app non in esecuzione in modalità di debug e con le opzioni sviluppatore abilitate, AdServiceException indica IllegalStateException come causa.

Esegui override di JavaScript lato acquirente

1. Segui la procedura per unirti a un segmento di pubblico personalizzato
2. Crea una AddCustomAudienceOverrideRequest con l'acquirente e il nome del segmento di pubblico personalizzato da sostituire, oltre alla logica di offerta e ai dati che vuoi utilizzare come sostituzione.
3. Richiama 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 due parametri aggiuntivi:

• biddingLogicJs: JavaScript contenente la logica dell'acquirente che viene utilizzato durante la selezione degli annunci. Vedi le firme delle funzioni obbligatorie in questo codice JavaScript.
• trustedBiddingSignals: indicatori di offerta da utilizzare durante la selezione degli annunci. A scopo di test, questa può essere una stringa vuota.

Il metodo overrideCustomAudienceRemoteInfo() asincrono 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 di generazione dei report che hai trasmesso come override.

Il callback onError() indica due possibili condizioni.

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

Reimposta override lato acquirente

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

Per reimpostare le sostituzioni per tutti i segmenti di pubblico personalizzati:

1. Richiama 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 lato acquirente, le chiamate successive a selectAds() utilizzano qualsiasi elemento biddingLogicUrl e trustedBiddingData vengono memorizzati nel campo CustomAudience per tentare di recuperare il codice JavaScript richiesto.

Se la chiamata al numero resetCustomAudienceRemoteInfoOverride() non va a buon fine, il callback OutComeReceiver.onError() fornisce un'AdServiceException. Se il tentativo di rimozione degli override viene eseguito con un'app non in esecuzione in modalità di debug e con le opzioni sviluppatore abilitate, la causa AdServiceException indica IllegalStateException come causa.

Imposta un server di reporting

Quando utilizzi gli override del recupero remoto, devi comunque configurare un server che il tuo dispositivo o l'emulatore possa raggiungere per rispondere agli eventi di reporting. Per il test è sufficiente un semplice endpoint che restituisca 200. Il repository GitHub include le definizioni del servizio OpenAPI di cui è possibile eseguire il deployment in una piattaforma di simulazione o microservizi supportata. Per maggiori dettagli, consulta il progetto README.

Quando cerchi le definizioni di OpenAPI, cerca il file reporting-server.json. Questo file contiene un endpoint semplice che restituisce 200, che rappresenta un codice di risposta HTTP. Questo endpoint viene utilizzato durante il periodo selectAds() e segnala all'API Protected Audience che la generazione di report sulle impressioni è stata completata correttamente.

Funzionalità da testare

• Esercitati ad accedere, ad abbandonare e a configurare un segmento di pubblico personalizzato in base alle azioni precedenti dell'utente.
• Esercitati nell'avvio della selezione di annunci sul dispositivo tramite JavaScript ospitati da remoto.
• Osserva come l'associazione di un'app con impostazioni dei segmenti di pubblico personalizzati può influire sui risultati della selezione degli annunci.
• Report sulle impressioni dell'esercizio dopo la selezione degli annunci.

Limitazioni

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

Componente	Descrizione limite	Valore limite
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 dall'ora di creazione	60 giorni
	Scadenza massima di una CA dal suo tempo di attivazione	60 giorni
	Numero massimo di CA sul dispositivo	4000
	Dimensione massima del nome della CA	200 byte
	Dimensione massima dell'URI di recupero giornaliero	400 byte
	Dimensione massima dell'URI della logica di offerta	400 byte
	Dimensione massima dei dati sulle offerte attendibili	10 kB
	Dimensione massima degli indicatori di offerta utente	10 kB
	Tariffa massima di chiamate per leaveCustomAudience per acquirente	1 al secondo
	Tariffa massima di chiamate per joinCustomAudience per acquirente	1 al secondo
Recupero in background CA	Timeout connessione	5 secondi
	Timeout lettura HTTP	30 secondi
	Dimensioni totali massime di download	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 lettura connessione	5 secondi
	Tempo massimo di esecuzione di AdSelection	10 secondi
	Tempo massimo di esecuzione delle offerte per CA in AdSelection	5 secondi
	Tempo massimo di esecuzione del punteggio in AdSelection	5 secondi
	Tempo massimo di esecuzione per acquirente in AdSelection	Da definire
	Dimensione massima degli indicatori di selezione degli annunci/del venditore/per acquirente	Da definire
	Dimensioni massime degli script venditore/acquirente	Da definire
	Percentuale massima di chiamate per selectAds	1 QPS
Report sulle impressioni	Tempo minimo prima di rimuovere la selezione degli annunci dalla persistenza	24 ore
	Numero massimo di selezioni di annunci per lo spazio di archiviazione	Da definire
	Dimensione massima dell'URL di output dei 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
	Percentuale massima di chiamate 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 gli AdData in un'unica CA per scopi contestuali
URL	Lunghezza massima di qualsiasi stringa URL presa come input	Da definire
JavaScript	Tempo massimo di esecuzione	1 secondo per offerte e punteggi per i report sulle impressioni
	Memoria massima utilizzata	10 MB

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