Guida per gli sviluppatori dell'API Protected Audience

Anteprima per gli sviluppatori Beta

Mentre leggi Privacy Sandbox su Android documentazione, utilizza il pulsante Anteprima per sviluppatori o Beta per selezionare la versione del programma in uso, le istruzioni possono variare.

---

Inviare un feedback

L'API Protected Audience su Android (precedentemente nota come FLEDGE) include il parametro l'API Custom Audience e l'API Ad Selection. Piattaforme e inserzionisti di tecnologia pubblicitaria puoi usare queste API per pubblicare annunci personalizzati in base alle precedenti interazioni in-app che limita la condivisione di identificatori tra le app e limita la condivisione dell'app di un utente informazioni sulle interazioni con terze parti.

L'API Custom Audience è incentrata sul "segmento di pubblico personalizzato" , che rappresenta un gruppo di utenti con intenzioni comuni. Un L'inserzionista può registrare un utente con un pubblico personalizzato e associare annunci pertinenti con essa. Queste informazioni vengono memorizzate localmente e possono essere utilizzate per informare l'inserzionista offerte, filtri degli annunci e rendering degli annunci.

L'API Ad Selection fornisce un framework che consente a più sviluppatori di eseguire un'asta localmente per un pubblico personalizzato. A questo scopo, il sistema prende in considerazione gli annunci pertinenti associati al segmento di pubblico personalizzato e ha un buon rendimento un'ulteriore elaborazione sugli annunci che una piattaforma di ad tech restituisce sul dispositivo.

Le piattaforme di ad tech possono integrare queste API per implementare il remarketing che tutela la privacy degli utenti. Supporto per casi d'uso aggiuntivi, inclusa l'installazione di app sono pianificati per le versioni future. Scopri di più su Protected Audience su Android nella proposta di progettazione.

Questa guida descrive come utilizzare l'API Protected Audience su Android per procedi nel seguente modo:

1. Gestire i segmenti di pubblico personalizzati
2. Configurare ed eseguire la selezione degli annunci su un dispositivo
3. Registrare 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 un emulatore che supporta 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. Includi un'autorizzazione ACCESS_ADSERVICES_CUSTOM_AUDIENCE nella tua app manifest:

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

5. Fare riferimento a una configurazione di servizi pubblicitari nell'elemento <application> di il tuo 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 file manifest, ad esempio res/xml/ad_services_config.xml. Scopri di più sulle autorizzazioni per i servizi pubblicitari e SDK Access Control.

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

7. Per impostazione predefinita, l'API Ad Selection applica i limiti sulla quantità massima di memoria utilizzata dai report su aste o impressioni che lo script può allocare. La funzionalità di limitazione della memoria richiede la versione WebView 105.0.5195.58 o successivo. La piattaforma applica un controllo della versione e chiama le API selectAds e reportImpression hanno esito negativo se non è soddisfatto. Esistono due opzioni per l'impostazione:

   • Opzione 1: esegui il comando adb riportato di seguito 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 uguale o superiore alla versione dichiarata in precedenza.

Entrare a far parte di un segmento di pubblico personalizzato

Un segmento di pubblico personalizzato rappresenta un gruppo di utenti con intenzioni comuni o interessi deciso dall'app dell'inserzionista. Un'app o un SDK può utilizzare un'istanza per indicare un determinato segmento di pubblico, ad esempio qualcuno che ha lasciato alcuni elementi. in un carrello degli acquisti. Per creare o unirti a un segmento di pubblico personalizzato in modo asincrono, procedi nel seguente modo: seguenti:

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

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

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

Chiamata ripetuta a joinCustomAudience() con un'istanza diversa di CustomAudience aggiorna tutte le CustomAudience esistenti con corrispondenti ai parametri owner, buyer e name. Per contribuire a preservare la privacy, il risultato dell'API non fa distinzione tra "creazione" e "update".

Inoltre, è necessario creare la CustomAudience con questi obbligatori parametri:

• URL di aggiornamento giornaliero: un URL HTTPS sottoposto a query giornaliere in background su aggiornare gli indicatori di offerta per gli utenti di un segmento di pubblico personalizzato, i dati sulle offerte attendibili e eseguire il rendering di URL e metadati per gli annunci.
• URL logica di offerta: un URL HTTPS a cui è stato chiesto di eseguire una query durante la selezione dell'annuncio per recuperare un dalla logica di offerta JavaScript dell'acquirente. Vedi le firme delle funzioni richieste in questo codice JavaScript.
• ID rendering annuncio: un ID arbitrario impostato dalla tecnologia pubblicitaria dell'acquirente. Si tratta di un ottimizzazione per generare il payload per B&A.

I parametri facoltativi per un oggetto CustomAudience possono includere:

• Ora di attivazione: un segmento di pubblico personalizzato può partecipare solo alla selezione degli annunci. e aggiornamenti giornalieri dopo l'attivazione. Può essere utile per coinvolgere ad esempio gli utenti non più attivi di un'app.
• Data di scadenza: un periodo di tempo futuro trascorso il quale il segmento di pubblico personalizzato è rimosso dal dispositivo.
• Indicatori di offerta per l'utente: una stringa JSON contenente indicatori relativi agli utenti, ad esempio la le impostazioni internazionali preferite dell'utente utilizzate dal codice JavaScript della logica di offerta dell'acquirente. per generare offerte durante il processo di selezione degli annunci. Questo formato consente le piattaforme riutilizzano il codice su più piattaforme e ne facilita l'utilizzo in JavaScript funzioni.
• Dati relativi a Offerte attendibili. Un URL HTTPS e un elenco di stringhe utilizzate durante processo di selezione degli annunci che recupera gli indicatori di offerta da un valore-chiave attendibile completamente gestito di Google Cloud.
• 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 richiesto di visualizzare l'annuncio finale.
  • Metadati: un oggetto JSON serializzato come stringa contenente informazioni per essere consumati dalla logica di offerta dell'acquirente durante il processo di selezione degli annunci.
  • Filtri annunci: un corso che contiene tutte le informazioni necessarie sull'app installare il filtro degli annunci e la quota limite durante la selezione degli annunci.

Nota :i valori di "Indicatori di offerta per utente", "Dati di offerta attendibili" e "Annunci" non devono superare i 10 kB in totale. Questi 3 campi devono essere compilati affinché un segmento di pubblico personalizzato partecipi alla selezione degli annunci.

Di seguito è riportato 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 di joinCustomAudience()

Il metodo joinCustomAudience() asincrono utilizza OutcomeReceiver per segnalare il risultato della chiamata API.

• Il callback onResult() indica che il segmento di pubblico personalizzato è riuscito creato o aggiornato.
• Il callback onError() rappresenta due condizioni possibili.
  • Se JoinCustomAudienceRequest è inizializzato con un valore non valido argomenti, AdServicesException indica un IllegalArgumentException come causa.
  • A tutti gli altri errori viene assegnato un valore AdServicesException con un 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);
    }
};

Uscire da un segmento di pubblico personalizzato

Se l'utente non soddisfa più i criteri aziendali per un determinato personalizzato pubblico, un'app o un SDK può chiamare leaveCustomAudience() per rimuovere l'elemento pubblico dal dispositivo. Per rimuovere una CustomAudience in base alla sua , procedi nel seguente modo:

1. Inizializza l'oggetto CustomAudienceManager.
2. Inizializza la LeaveCustomAudienceRequest con il buyer e name. Per saperne di più su questi campi di immissione, consulta "Unisciti a un segmento di pubblico personalizzato".
3. Chiama il metodo leaveCustomAudience() asincrono con Oggetto LeaveCustomAudienceRequest e Executor e OutcomeReceiver di oggetti.

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

Come per la chiamata di joinCustomAudience(), gli indicatori OutcomeReceiver al termine di una chiamata API. Per proteggere la privacy, il risultato di un errore distinguere tra errori interni e argomenti non validi. onResult() il callback viene chiamato al termine della chiamata API, indipendentemente dal fatto che segmento di pubblico personalizzato rimosso.

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 Oggetto AdSelectionConfig e Executor e OutcomeReceiver di oggetti.

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, dove devi specificare i seguenti parametri obbligatori:

• Venditore: l'identificatore della rete pubblicitaria del venditore che avvia la selezione degli annunci.
• URL logica decisionale: un URL HTTPS che è stato oggetto di una query per ottenere l'URL della rete pubblicitaria del venditore della logica JavaScript.
  • URL HTTPS: viene eseguito una query per ottenere la logica JavaScript della rete pubblicitaria del venditore. Vedi le firme delle funzioni richieste.
  • URI predefinito: segue il formato di selezione degli annunci di FLEDGE. Viene restituito il valore IllegalArgumentException se un formato non è supportato o è in un formato non supportato l'URI predefinito viene passato.
• 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 dell'acquirente corrispondono a CustomAudience.getBuyer() di segmenti di pubblico personalizzati partecipanti.

I seguenti parametri possono essere facoltativamente specificati per annunci più personalizzati selezione:

• Indicatori di selezione degli annunci: un oggetto JSON, serializzato come stringa, contenente indicatori da utilizzare per la logica di offerta dell'acquirente recuperati da JavaScript CustomAudience.getBiddingLogicUrl().
• Indicatori del venditore: un oggetto JSON, serializzato come stringa, contenente indicatori. consumata dalla logica decisionale JavaScript recuperata dal venditore AdSelectionConfig.getDecisionLogicUrl().
• Indicatori per acquirente: una mappa di oggetti JSON, serializzati come stringhe. che contengono indicatori che possono essere consumati da specifici acquirenti JavaScript della logica di offerta recuperate da CustomAudience.getBiddingLogicUrl(), identificate da campi relativi agli acquirenti dei segmenti di pubblico personalizzati partecipanti.
• Annunci contestuali: una raccolta di candidati per gli annunci raccolti direttamente dagli acquirenti durante un'asta che si verifica al di fuori di Protected Audience in un'asta.

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 che contiene:

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

Se la selezione dell'annuncio non può essere completata correttamente per motivi quali argomenti non validi, timeout o un consumo eccessivo di risorse, La richiamata OutcomeReceiver.onError() produce un AdServicesException con i seguenti comportamenti:

• Se la selezione dell'annuncio viene avviata con argomenti non validi, AdServicesException indica IllegalArgumentException come causa.
• A tutti gli altri errori viene assegnato un valore AdServicesException con un 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 nell'asta utilizzando AdSelectionConfig; a questo punto utilizzano Uguale agli annunci sui dispositivi, inclusa l'idoneità al filtro degli annunci per esclusione. Una volta L'asta Protected Audience è stata completata, devi richiamare reportImpression(). In questo modo viene chiamato reportWin() nell'annuncio contestuale vincente, in lo stesso pattern dei report sulle impressioni, per ricevere l'annuncio vincente su dispositivo. Ciascun annuncio contestuale richiede un acquirente, un'offerta, un link alla logica di report, l'URL di rendering e i metadati degli annunci.

Per implementare gli annunci contestuali nell'app, l'app target deve creare una 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ò quindi essere passato durante la creazione 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 permette di filtrare gli annunci di installazione per le app. già installati su un dispositivo.

Il primo passaggio di questo processo consiste nel definire quali inserzionisti possono per filtrare i dati in base al pacchetto installato. Questa operazione deve essere eseguita 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 in grado di ed escludere le app installate da te specificate durante la generazione delle offerte. Se devi rimuovere un inserzionista dall'accesso all'installazione di questa app , esegui nuovamente questo codice dopo aver rimosso le informazioni sull'inserzionista.

Il passaggio successivo consiste nel configurare il filtro degli annunci all'interno dell'app del publisher. La festa pubblica l'annuncio all'interno dell'app del publisher (molto probabilmente si tratta di un SDK Supply-Side) deve inizializzare l'oggetto AdFilters con informazioni su quali annunci relative 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 presenti all'interno di segmenti di pubblico personalizzati.

AdFilters può anche essere trasmesso nel momento di creare un'istanza di un nuovo 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 sulla quota limite

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

Un filtro per la quota limite ha due componenti principali: il tipo di evento dell'annuncio e la chiave del contatore annunci. I tipi di eventi dell'annuncio che possono essere utilizzati sono i seguenti:

• Vittoria (disponibile a breve): un evento con vincita indica che l'annuncio ha vinto un'asta. Gli eventi vittoria vengono aggiornati automaticamente dall'API Protected Audience e non possono essere chiamato direttamente dallo sviluppatore. I dati relativi alle vincite sono visibili solo agli annunci all'interno di un un determinato segmento di pubblico personalizzato.
• Impressione: separata da reportImpression, un chiamante sul dispositivo (SSP o MMP) utilizza updateAdCounterHistogram() per richiamare gli eventi di impressione a livello di punto nel codice che scelgono. Gli eventi di impressione sono visibili a tutti gli annunci appartenenti a un determinato DSP e non solo agli annunci nello stesso segmento di pubblico personalizzato.
• Visualizzazione: l'evento viene richiamato dal chiamante sul dispositivo (SSP o MMP) in un punto in il codice scelto tramite una chiamata al numero updateAdCounterHistogram(). Gli eventi di visualizzazione sono visibile a tutti gli annunci appartenenti a un determinato DSP e non solo agli annunci nella stessa Segmento di pubblico personalizzato.
• Clic: l'evento viene richiamato dal chiamante sul dispositivo (SSP o MMP) in un momento il codice scelto tramite una chiamata al numero updateAdCounterHistogram(). Eventi di clic sono visibili a tutti gli annunci appartenenti a un determinato DSP e non solo agli annunci nella stesso segmento di pubblico personalizzato.

Nell'app del publisher, una piattaforma SSP o MMP che ha una presenza sul dispositivo richiama l'annuncio eventi. Quando viene chiamato updateAdCounterHistogram(), il contatore di una frequenza il filtro del limite viene incrementato in modo che le aste future siano sempre aggiornate. informazioni sull'esposizione di un utente a un determinato annuncio. I tipi di eventi dell'annuncio non sono forzatamente vincolati all'azione corrispondente dell'utente e sono linee guida fornite per aiutare per strutturare il proprio sistema di eventi. Per incrementare i contatori di annunci nel momento in cui un evento, l'attore sul dispositivo fornisce l'ID selezione annunci dell'asta dell'annuncio vincente.

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

Le chiavi contatore possono essere sfruttate per dare priorità agli annunci che hanno maggiori probabilità interessante per un determinato utente sulla base delle sue interazioni con altri annunci da un una determinata tecnologia pubblicitaria dell'acquirente. Ad esempio, un annuncio che ha ricevuto un alto livello il coinvolgimento derivante da aste di annunci vincenti, visualizzazioni e clic, rappresenta una punto dati. Per illustrare ulteriormente questo punto: un annuncio per mazze da golf mancini potrebbe indicare che all'utente non sarebbero interessati quelli per destrimani. R il filtro della quota limite impostato per una chiave contatore assegnato agli annunci sinistri può filtrare gli annunci per mazze per destrimani.

Per utilizzare la quota limite nell'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 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 per la quota limite, è possibile 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 per la 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 di filtro della quota limite preimpostati vengono esclusi dell'asta. L'applicazione dei filtri avviene prima dell'esecuzione della logica di offerta on-device e man mano che il payload viene generato per Offerte e Asta di Google Cloud.Questo toolkit offre ai tecnici pubblicitari la flessibilità di utilizzare interazioni tra gli utenti e gli annunci all'interno dei loro segmenti di pubblico personalizzati per e al minimo la sovraesposizione degli annunci.

Filtro degli annunci contestuali senza chiamate di rete

Se non c'è alcuna richiesta di remarketing sul dispositivo, puoi eseguire la selezione degli annunci per annunci contestuali senza chiamate di rete. Con URI predefiniti e un elenco di gli annunci contestuali con offerte, la piattaforma può saltare il recupero della logica di offerta indicatori di offerta e di punteggio. La piattaforma utilizza un URI predefinito per selezionare l'annuncio contestuale che presenta l'offerta più alta.

Per migliorare la latenza, i tecnici pubblicitari possono eseguire un flusso di selezione degli annunci che includa solo annunci contestuali con funzionalità di filtro degli annunci senza chiamate di rete. Questo è si ottengono utilizzando URI predefiniti per l'assegnazione di indicatori. Fai riferimento alla sezione sezione dei nomi e dei casi d'uso degli URI predefiniti per un elenco di scoreAds implementazioni.

Per eseguire la selezione degli annunci senza chiamate di rete:

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

3. Crea un oggetto AdSelectionConfig con quanto segue:

   1. Un elenco di acquirenti vuoto
   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 Non vuoi utilizzare il recupero degli indicatori attendibili per assegnare un 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 ha solo un codice JavaScript di base per i report per gli URI predefiniti. Se vuoi eseguire il tuo deployment generare report su JavaScript pur continuando a usare URI predefiniti per un annuncio a bassa latenza puoi sostituire il valore DecisionLogicUri tra la selezione degli annunci e il reporting è in esecuzione.

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

2. Crea una copia del tuo AdSelectionConfig prima di eseguire il 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);
   

Esegui la mediazione a cascata

La mediazione a cascata richiede più SDK di terze parti (reti di terze parti) orchestrate da una rete di mediazione SDK proprietaria. La mediazione a cascata è allo stesso modo, a prescindere dal fatto che l'asta si sia svolta sul dispositivo o il Offerte e Servizi di aste (B&A).

Reti di terze parti

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

• Pubblica selezione annunci
• Registra le impressioni

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

Ciascun SDK dispone dei propri clienti e gestori del servizio di selezione degli annunci e di Implementazione di selectAds e reportImpressions. I provider di SDK possono fare riferimento le sezioni su come eseguire la selezione degli annunci per le aste on-device o il B&A esplicativo per le aste B&A. Segui come segnalare l'annuncio impressioni (in base ai report sulle singole impressioni SSP per i report.

Rete di mediazione

Analogamente alle reti di terze parti, le reti di mediazione richiedono selectAds e reportImpression implementazioni. Consulta le sezioni su come pubblicare un annuncio selezione e su come generare report sulle impressioni degli annunci per saperne di più.

Le reti di mediazione sono responsabili della gestione della catena di mediazione e del posizionamento nella catena di mediazione. La prossima sezione illustra come impostare e questo processo.

Recuperare la catena di mediazione e i prezzi minimi di offerta

La rete di mediazione è responsabile del recupero della parte proprietaria gli annunci contestuali, la catena di mediazione e le reti di terze parti, prezzi minimi (terze parti). Questo può verificarsi in una richiesta di recupero di annunci contestuali eseguiti dalla mediazione in ogni rete. 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 dell'asta come adSelectionSignals.

Posizionamento sulla rete nella catena di mediazione

Un SDK di mediazione può posizionarsi nella catena di mediazione in base al proprio eCPM in tempo reale delle offerte per annunci proprietari. Nell'API Protected Audience, le offerte per gli annunci sono opache. Una mediazione L'SDK deve usare AdSelectionFromOutcomesConfig per poter confrontare una determinata proprietà proprietaria l'offerta dell'annuncio all'offerta minima della successiva rete di terze parti nella catena. Se l'offerta proprietaria è superiore all'offerta minima, significa che l'SDK di mediazione è posizionato in primo piano della rete di terze parti.

Pubblica selezione annunci

Per recuperare un candidato per un annuncio proprietario, la rete di mediazione può eseguire una seguendo i passaggi nella sezione Esegui selezione degli annunci. Questo genera un candidato annuncio proprietario, un'offerta e un AdSelectionId che viene utilizzato nella mediazione e il processo di sviluppo.

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. Elenco di AdSelectionId insieme alle relative offerte e gli indicatori vengono trasmessi JavaScript che può restituire uno degli AdSelectionIds se supera l'offerta minimo o nessuno se la catena di mediazione deve continuare.

Le reti di mediazione creano un AdSelectionFromOutcomesConfig utilizzando i dati proprietari AdSelectionId della sezione precedente e l'offerta minima per la rete di terze parti essere presi 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 quanto segue parametri obbligatori:

• Venditore: l'identificatore della rete pubblicitaria del venditore che avvia la selezione degli annunci.
• AdSelectionIds: un elenco singleton di una precedente esecuzione di selectAds() per una proprietà annuncio.
• 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 recuperate per la rete di terze parti specificata.
• URI Selection Logic: un URL HTTPS che è stato oggetto di una query durante la selezione dell'annuncio per recuperare il valore codice JavaScript della rete di mediazione per selezionare un annuncio vincente. Consulta i campi obbligatori firme di funzione in questo codice JavaScript. Il codice JavaScript dovrebbe restituire l'oggetto annuncio di terze parti se l'offerta è superiore all'offerta minima, altrimenti restituisce null. In questo modo l'SDK di mediazione può troncare la catena di mediazione quando un vincitore è un vincitore. trovato.

Dopo aver creato AdSelectionOutcomesConfig, chiama il metodo selectAds() di la rete di terze parti che è la prima della 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 eseguire la mediazione e il processo di sviluppo.

1. Esegui la selezione di annunci proprietari.
2. Ripeti la procedura sulla catena di mediazione. Per ogni rete di terze parti:
   1. Build AdSelectionFromOutcomeConfig che include outcomeId proprietari e 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, restituisce 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

Esistono due flussi per segnalare un'impressione dell'annuncio a seconda di come si svolge l'asta viene eseguito. Se rappresenti una singola SSP che esegue un'asta, segui questa sezione. Se vuoi implementare la mediazione a cascata, segui i passaggi indicati 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, è possibile Segnalare l'impressione alle piattaforme lato acquisti e lato vendite partecipanti con il metodo AdSelectionManager.reportImpression(). Per segnalare un annuncio impressione:

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

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 quanto segue: parametri:

• ID selezione annunci: un ID univoco solo per un utente del dispositivo che identifica un una selezione efficace degli annunci.
• Configurazione della selezione degli annunci: la stessa configurazione utilizzata in selectAds(). chiamata identificata dall'ID selezione annunci fornito.

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

• Il callback onResult() indica se gli URL dei report sulle impressioni sono stati 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, il valore AdServicesException indica IllegalArgumentException come la causa.
  • A tutti gli altri errori viene assegnato un valore AdServicesException con un IllegalStateException come causa.

Report sulle impressioni della mediazione a cascata

Un SDK di mediazione deve tenere traccia dell'SDK vincente per attivare la sua di generazione dei report. Gli SDK che partecipano a una catena di mediazione devono fornire una che il mediatore deve richiamare per attivare il proprio flusso di reporting. Un SDK la partecipazione a un'asta con mediazione può seguire la procedura descritta sopra per implementare i propri report.

Le SSP possono utilizzare questo esempio di codice SDK di terze parti come prototipo per le modalità di partecipazione flussi di mediazione:

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

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

Endpoint per il reporting delle impressioni

L'API Report Impression emette richieste GET HTTPS agli endpoint forniti Sell-Side Platform e la piattaforma lato acquisti 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 nell'URL dei report sulle impressioni.
• Richiama la funzione JavaScript reportWin(), che dovrebbe restituire l'URL del report sulle impressioni dell'acquirente.

Endpoint piattaforma lato vendite:

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

Offerte e Report sui servizi di aste

Un'asta eseguita su Offerte e I servizi di aste disporranno di tutte le informazioni dei report, inclusi gli URL generati per i report sull'interazione con gli annunci; incluse nella risposta criptata dall'asta lato server. Quando la risposta viene decriptata, gli URL appropriati vengono registrati sulla piattaforma, i report sulle impressioni e sugli annunci seguono gli stessi passaggi elencati sopra.

Report sulle impressioni con il migliore sforzo

Il metodo reportImpression() è progettato per garantire il completamento di i report.

Nota:

• Se l'API non è in grado di determinare gli URL dei report sulle impressioni dal JavaScript, verrà restituito un errore.
• Se la chiamata agli URL non riesce, l'attuale release di Anteprima per gli sviluppatori non produca errori. La logica dei nuovi tentativi per gli errori temporanei è previste per le versioni future.
• Più chiamate a reportImpression() con lo stesso può comportare la segnalazione di più risultati di selezione degli annunci volte.

Segnala interazioni con gli annunci

Protected Audience consente di generare report su interazioni più granulari per di un annuncio con rendering. Possono essere incluse interazioni come tempo di visualizzazione, clic, passaggi del mouse, o qualsiasi altra metrica utile che può essere raccolta. La procedura per ricevere questi richiede due passaggi. Innanzitutto, acquirenti e venditori devono registrarsi per ricevere questi report nel codice JavaScript di reporting. Il cliente dovrà quindi segnalare questi eventi.

Registrazione per ricevere eventi di interazione

La registrazione per gli eventi di interazione avviene in reportWin() e funzioni JavaScript reportResult() del venditore utilizzando una funzione JavaScript fornita dalla piattaforma: registerAdBeacon. Per registrarti e ricevere report sugli eventi, richiama semplicemente la funzione JavaScript della piattaforma JavaScript. Il seguente snippet utilizza l'reportWin() di un acquirente, ma lo stesso 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 delle chiavi di interazione devono corrispondere a ciò che il venditore segnala ricevere report.

Eventi di interazione con i report

Dopo aver registrato un'impressione, i clienti possono segnalare le interazioni al le piattaforme lato acquisti e lato vendite vincenti registrate in precedenza con AdSelectionManager.reportInteraction(). Per segnalare un evento relativo agli annunci:

1. Inizializza un oggetto AdSelectionManager.
2. Crea un oggetto ReportInteractionRequest con l'ID selezione annunci, chiave di interazione, dati delle interazioni e destinazione dei report.
3. Chiama il metodo reportInteraction() asincrono con l'oggetto request e 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 quanto segue: parametri:

• ID selezione annunci: un ID selezione annunci recuperato da un valore precedentemente restituito. AdSelectionOutcome.
• Chiave di interazione: una chiave stringa definita dal client che descrive l'azione essere segnalati. Deve corrispondere alla chiave registrata dal venditore oppure l'acquirente nelle funzioni JavaScript di reporting.
• Dati di interazione: una stringa contenente dati da includere nell'evento. report, per essere POSTATO ai server di reporting.
• Destinazioni report: una maschera di bit che specifica se gli eventi devono essere. segnalato all'acquirente, al venditore o a entrambi. Questi flag sono forniti e la maschera di destinazione finale possono essere create operazioni. Per generare un report relativo a una destinazione, puoi utilizzare il flag fornito dal direttamente dalla piattaforma. Per generare rapporti a più destinazioni, puoi utilizzare la funzione OR (|) per combinare i valori del flag.

Il metodo reportInteraction() asincrono utilizza OutcomeReceiver per segnalare il risultato della chiamata 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 mentre l'app è in esecuzione in background, Viene restituito IllegalStateException con una descrizione dell'errore.
  • Se il client non è in grado di chiamare reportInteraction(), viene Viene restituito LimitExceededException.
  • Se il pacchetto non è registrato per chiamare le API incentrate sulla tutela della privacy, viene Viene restituito SecurityException().
  • Se le interazioni dei report sull'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 smetterà di funzionare in silenzio.

Nota: l'assenza di errori non significa che i report sono stati eseguiti. Piuttosto, garantisce che Protected Audience proverà a segnalare le interazioni in qualche modo.

Endpoint di reporting delle interazioni

L'API di interazione con i report invia richieste POST HTTPS agli endpoint forniti da la Sell-Side Platform e la piattaforma lato acquisti vincente. Protected Audience corrisponderà le chiavi di interazione con gli URI dichiarati nel report JavaScript ed emettono una richiesta POST a ciascun endpoint per ciascuna interazione segnalata. Il tipo di contenuti della richiesta è in testo normale, dove il corpo è Dati sulle interazioni.

Report sulle interazioni con il miglior sforzo

L'reportInteraction() è progettata per garantire il completamento del tramite HTTP POST.

Aggiornamento giornaliero in background

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

• Indicatori di offerta per utente
• 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 da aggiornare.
• Ogni campo JSON viene convalidato in modo indipendente. Il client ignora qualsiasi campi in formato non corretto che non comportano aggiornamenti a quel particolare campo in la 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 delle fornito dal venditore.

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

• generateBid()
• reportWin()

Il codice JavaScript fornito dal venditore viene recuperato dall'URL della logica decisionale specificato in Il parametro AdSelectionConfig per l'API di selezione degli annunci. L'oggetto restituito JavaScript 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'asta oggetto di configurazione

• custom_audience_bidding_signals: oggetto JSON generato dalla piattaforma. La per questo oggetto JSON è:

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

  dove:

  • owner, buyer e name sono stringhe prese dalle proprietà con lo stesso nome del segmento di pubblico personalizzato che partecipa alla selezione degli annunci
  • activation_time e expiration_time sono l'ora di attivazione e scadenza del segmento di pubblico personalizzato, espressa in secondi dall'interfaccia Unix epoca
  • 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 in formato JSON di oggetti strutturati. Vengono passati come oggetti vuoti e verranno compilati nelle versioni future. Il loro formato non è applicato in modo forzato dalla piattaforma ed è gestito dalla tecnologia pubblicitaria.

Risultato:

• ad: è l'annuncio a cui fa riferimento l'offerta. Lo script può restituire una copia di l'annuncio ricevuto con metadati diversi. La proprietà render_url del si prevede che l'annuncio rimanga invariato.
• 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 qualsiasi degli indicatori di input non sia valido. Nella se viene restituito un valore diverso da zero da "Genera offerta", il processo di offerta invalidato 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: visualizza la documentazione di generateBid
• bid: il valore dell'offerta per l'annuncio

• ad_selection_config: un oggetto JSON che rappresenta 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: gli oggetti JSON vengono letti dall'sellerSignals Parametro API AdSelectionConfig

• trusted_scoring_signal: viene letta dal campo adSelectionSignals nella 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 è applicati 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 Parametro API Acquirente del segmento di pubblico. Vuota se la mappa non contiene voci per il valore specificato acquirente.

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: se i valori customAudienceSignals non sono validi
  • 2: se AdSelectionConfig non è 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 nella configurazione dell'asta oggetto

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: visualizza la documentazione di scoreAds
• render_url: l'URL di rendering dell'annuncio vincente
• bid: l'offerta offerta per l'annuncio vincente
• contextual_signals: visualizza la documentazione di generateBid

Output:

• status: 0 per le operazioni riuscite e un valore diverso da zero per gli errori
• results: un oggetto JSON contenente:
  • signals_for_buyer: un oggetto JSON passato a reportWin funzione
  • reporting_url: un URL utilizzato dalla piattaforma per inviare notifiche a impressione per l'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 per scoreAd
• signals_for_buyer: un oggetto JSON restituito da reportResult
• contextual_signals, custom_audience_signals: visualizza la documentazione per generateBid

Output:

• status: 0 per le operazioni riuscite e un valore diverso da zero per gli errori
• results: un oggetto JSON contenente:
  • reporting_url: un URL utilizzato dalla piattaforma per inviare notifiche a impressione al venditore

registerAdBeacon()

Nota: questa funzionalità è fornita dalla piattaforma Android e non deve essere implementata da ad tech.

function registerAdBeacon(
  interaction_key,
  reporting_uri
)

Parametri di input:

• interaction_key: una stringa che rappresenta l'evento. Questa è utilizzata alla piattaforma in un secondo momento, quando segnali le interazioni di eventi per cercare reporting_uri che devono essere informati. Questa chiave deve corrispondere a l'acquirente o il venditore si stanno registrando e i dati segnalati dal venditore.
• 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.

URI predefiniti per la selezione degli annunci

Gli URI predefiniti consentono ai tecnici pubblicitari di assegnare funzioni JavaScript per gli annunci logica decisionale di selezione in AdSelectionConfig e AdSelectionFromOutcomesConfig corso. Gli URI predefiniti non richiedono la rete per scaricare il codice JavaScript corrispondente. I tecnici pubblicitari 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 URI nel 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 degli URI predefiniti supportati

Caso d'uso 1: selezione degli annunci

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

Nome URI predefinito: highest-bid-wins

Questo URI predefinito fornisce un codice JavaScript che sceglie 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 report di base è https://www.ssp.com/reporting, l'URL predefinito L'URI sarebbe:

`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 selectAds(AdSelectionFromOutcomesConfig).

Nome URI predefinito: waterfall-mediation-truncation

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

Parametri obbligatori

bidFloor: la chiave del valore minimo dell'offerta trasmesso nel campo getSelectionSignals(). confrontato con l'annuncio dell'SDK di mediazione.

Utilizzo

Se gli indicatori di selezione degli annunci sono simili a {"bid_floor": 10}, gli indicatori risultanti l'URI predefinito sarebbe:

`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 un campione in Kotlin e Java, disponibili su GitHub.

Prerequisiti

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

• Esegui un server con gli endpoint HTTPS richiesti che restituiscano 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 le impressioni i report.

Endpoint HTTPS

Per testare la selezione degli annunci e i report sulle impressioni, è necessario configurare 7 HTTPS endpoint accessibili dal dispositivo di test o dall'emulatore:

1. Endpoint dell'acquirente che pubblica la logica di offerta JavaScript.
2. Un endpoint che pubblica gli indicatori di offerta.
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 praticità, il repository GitHub fornisce il codice JavaScript di base per i test scopi. Include inoltre definizioni del servizio OpenAPI di cui è possibile eseguire il deployment una piattaforma fittizia o di microservizi supportata. Per maggiori dettagli, consulta il progetto LEGGIMI.

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 telecomando recupero, 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 riga seguente alla nel tuo file AndroidManifest.xml:

<application
  android:debuggable="true">

Nota: assicurati di rimuovere android:debuggable="true" prima di spedire il tuo applicazione.

Per un esempio di come utilizzare queste sostituzioni, consulta il Centro Esempio di app dell'API Audience su GitHub.

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

È possibile eseguire l'override del recupero JavaScript lato vendite e lato acquisti in modo indipendente, anche se è necessario un endpoint HTTPS per pubblicare qualsiasi non stai fornendo override. Consulta 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 che sono di proprietà del tuo pacchetto.

Eseguire l'override del codice JavaScript lato vendite

Per configurare un'override di JavaScript lato vendite, procedi come indicato di seguito nel seguente esempio di codice:

1. Inizializza un oggetto AdSelectionManager.
2. Ottieni un riferimento a TestAdSelectionManager dal AdSelectionManager oggetto.
3. Crea un oggetto AdSelectionConfig.
4. Crea una AddAdSelectionOverrideRequest con AdSelectionConfig e un String che rappresenta il codice JavaScript che intendi utilizzare come override.
5. Chiama il metodo overrideAdSelectionConfigRemoteInfo() asincrono con Oggetto AddAdSelectionOverrideRequest e Executor pertinente e OutcomeReceiver.

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 ogni rappresentate dai campi di AdSelectionConfig. La differenza principale è che decisionLogicUrl può essere impostato su un valore segnaposto, così come sarà ignorato.

Per sostituire il codice JavaScript utilizzato durante la selezione degli annunci, il parametro decisionLogicJs deve contenere le firme delle funzioni lato venditore appropriate. Per un esempio di come leggere un file JavaScript come stringa, consulta la App di esempio dell'API Protected Audience su GitHub.

Il metodo overrideAdSelectionConfigRemoteInfo() asincrono utilizza 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 report che hai trasmesso come override.

Il callback onError() indica due possibili condizioni:

• 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 attivate, AdServiceException indica IllegalStateException come causa.

Reimposta sostituzioni lato vendite

Questa sezione presuppone che tu abbia sostituito il codice JavaScript lato vendite e che fai riferimento a TestAdSelectionManager e AdSelectionConfig utilizzata nella sezione precedente.

Per reimpostare gli override per tutte le AdSelectionConfigs:

1. Chiama 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 viene archiviato in AdSelectionConfig per tentare di recuperare il codice JavaScript richiesto.

Se la chiamata a resetAllAdSelectionConfigRemoteOverrides() non riesce, Il callback OutComeReceiver.onError() restituisce un valore AdServiceException. Se si tenta di rimuovere gli override con un'app non in esecuzione in modalità di debug con le opzioni sviluppatore attivate, AdServiceException indica IllegalStateException come causa.

Sostituire il codice JavaScript lato acquisti

1. Segui i passaggi per entrare a far parte di un segmento di pubblico personalizzato
2. Crea una AddCustomAudienceOverrideRequest con l'acquirente e il nome del segmento di pubblico personalizzato che vuoi sostituire, oltre al sulla logica e sui dati di offerta da utilizzare come sostituzione.
3. Chiama il metodo overrideCustomAudienceRemoteInfo() asincrono con AddCustomAudienceOverrideRequest e pertinente Oggetti Executor e OutcomeReceiver

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

Inoltre, puoi specificare due parametri aggiuntivi:

• biddingLogicJs: codice JavaScript che contiene la logica dell'acquirente utilizzata durante la selezione degli annunci. Vedi le firme delle funzioni richieste in questa 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 OutcomeReceiver per segnalare il risultato della chiamata API.

Il callback onResult() indica che l'override è stato applicato correttamente. Le chiamate successive a selectAds() utilizzano qualsiasi logica di offerta e generazione di report che hai passato 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 attivate, AdServiceException indica IllegalStateException come causa.

Reimposta sostituzioni lato acquisti

In questa sezione si presuppone che tu abbia eseguito l'override del codice JavaScript lato acquisti e che fai riferimento a TestCustomAudienceManager utilizzato sezione precedente.

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

1. Chiama il metodo resetAllCustomAudienceOverrides() asincrono con 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() utilizzare qualsiasi cosa siano biddingLogicUrl e trustedBiddingData archiviati in CustomAudience per tentare di recuperare i dati JavaScript.

Se la chiamata a resetCustomAudienceRemoteInfoOverride() non riesce, Il callback OutComeReceiver.onError() restituisce un valore AdServiceException. Se si tenta di rimuovere gli override con un'app non in esecuzione in modalità di debug con le opzioni sviluppatore attivate, 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 di segnalazione. Un semplice che restituisce 200 è sufficiente per il test. Il repository GitHub include Definizioni del servizio OpenAPI di cui è possibile eseguire il deployment in una simulazione o di microservizi. Per maggiori dettagli, consulta il progetto LEGGIMI.

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

Funzionalità da testare

• Fare prove di partecipazione, abbandono e configurazione di un segmento di pubblico personalizzato in base alle azioni utente.
• Esercitare l'avvio della selezione degli annunci sul dispositivo tramite JavaScript in hosting da remoto.
• Osservare in che modo l'associazione di un'app alle impostazioni dei segmenti di pubblico personalizzati può influire sull'annuncio i risultati della selezione.
• Esercitati con i report sulle impressioni 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. Per funzionalità in corso, 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 dal momento della 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 Trusted Bidding	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 massime totali 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 di lettura della connessione	5 secondi
	Tempo di esecuzione massimo per AdSelection nel complesso	10 secondi
	Tempo massimo di esecuzione 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
	Dimensione massima degli indicatori selezione annunci/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 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
	Tariffa massima 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 AdData in un'unica CA per l'analisi
URL	Lunghezza massima di qualsiasi stringa URL presa come input	Da definire
JavaScript	Tempo massimo di esecuzione	1 secondo per le offerte e il punteggio per i report sulle impressioni
	Memoria utilizzata massima	10 MB

Segnalare bug e problemi

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