Definire i dati sul pubblico

Un segmento di pubblico personalizzato rappresenta un gruppo di utenti con intenzioni o interessi comuni, come deciso da un'app inserzionista. Un'app o un SDK può utilizzare un segmento di pubblico personalizzato per indicare un segmento di pubblico specifico, ad esempio un utente che ha lasciato articoli in un carrello degli acquisti.

L'API Protected Audience di Android può essere utilizzata per entrare a far parte di segmenti di pubblico personalizzati e abbandonarli sul dispositivo di un utente. Quando crei un segmento di pubblico personalizzato e vi partecipi, puoi delegare a un server da cui recuperare alcune o tutte le proprietà del segmento di pubblico personalizzato oppure puoi specificare queste informazioni quando chiami direttamente l'API.

Segmenti di pubblico personalizzati

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

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

Inoltre, CustomAudience deve essere creato con questi parametri obbligatori:

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

I parametri facoltativi per un oggetto CustomAudience possono includere:

  • Ora di attivazione: un segmento di pubblico personalizzato può partecipare alla selezione degli annunci e agli aggiornamenti giornalieri solo dopo l'ora di attivazione. Questo può essere utile per coinvolgere gli utenti inattivi di un'app, ad esempio.
  • Ora di scadenza: un'ora futura dopo la quale il segmento di pubblico personalizzato viene rimosso dal dispositivo.
  • Indicatori di offerta dell'utente: una stringa JSON contenente indicatori dell'utente, ad esempio le impostazioni internazionali preferite dell'utente, che il codice JavaScript della logica di offerta di un acquirente utilizza per generare offerte durante la procedura di selezione degli annunci. Questo formato aiuta le piattaforme di tecnologia pubblicitaria a riutilizzare il codice su più piattaforme e semplifica il consumo nelle funzioni JavaScript.
  • Dati di offerta attendibili: un URL HTTPS e un elenco di stringhe utilizzati durante la procedura di selezione degli annunci che recuperano gli indicatori di offerta da un servizio Key/Value attendibile.
  • Annunci: un elenco di oggetti AdData corrispondenti agli annunci che partecipano alla selezione degli annunci. Ogni oggetto AdData è costituito da:
    • URL di rendering: un URL HTTPS su cui viene eseguita una query per eseguire il rendering dell'annuncio finale.
    • Metadati: un oggetto JSON serializzato come stringa contenente informazioni da utilizzare nella logica di offerta dell'acquirente durante la procedura di selezione degli annunci.
    • Filtri annuncio: una classe che contiene tutte le informazioni necessarie per il filtro degli annunci per l'installazione di app e per la quota limite durante la selezione degli annunci.

Recuperare e unire un segmento di pubblico personalizzato

L'API fetchAndJoinCustomAudience consente agli acquirenti di delegare l'aggiunta a un pubblico personalizzato sfruttando la presenza sul dispositivo delle MMP o delle SSP partner.

Affinché funzioni, il chiamante sul dispositivo (che si tratti di un SDK MMP o SSP) crea un fetchAndJoinCustomAudienceRequest simile al seguente:

Kotlin

/**
 * @param fetchUri The URL to retrieve the CA from.
 * (optional)@param name The name of the CA to join.
 * (optional)@param activationTime The time when the CA will activate.
 * (optional)@param expirationTime The time when the CA will expire,
    must be a time in the future otherwise this will fail
 * (optional)@param userBiddingSignals The user bidding signals used at auction.
*/

val request = FetchAndJoinCustomAudienceRequest.Builder(fetchUri)
    .setName(name)
    .setActivationTime(activationTime)
    .setExpirationTime(expirationTime)
    .setUserBiddingSignals(userBiddingSignals)
    .build()

Java

/**
 * @param fetchUri The URL to retrieve the CA from.
 * (optional)@param name The name of the CA to join.
 * (optional)@param activationTime The time when the CA will activate.
 * (optional)@param expirationTime The time when the CA will expire,
    must be a time in the future otherwise this will fail
 * (optional)@param userBiddingSignals The user bidding signals used at auction.
*/

FetchAndJoinCustomAudienceRequest request =
 new FetchAndJoinCustomAudienceRequest.Builder(fetchUri)
  .setName(name) //Optional
  .setActivationTime(activationTime) //Optional
  .setExpirationTime(expirationTime) //Optional
  .setUserBiddingSignals(userBiddingSignals) //Optional
  .build();

Una nota importante su tutti i parametri facoltativi è che, se vengono impostati all'interno della richiesta di recupero, i relativi dati non possono essere sovrascritti da quelli restituiti dall'acquirente, il che offre al chiamante sul dispositivo ulteriori controlli su quale segmento di pubblico personalizzato viene mantenuto.

fetchUri deve rimandare a un endpoint del server gestito dall'acquirente che restituirà un oggetto JSON del segmento di pubblico personalizzato corrispondente al formato mostrato qui:

//Return a 200 response with data matching the format of the following in the body
{
  "daily_update_uri": "https://js.example.com/bidding/daily",
  "bidding_logic_uri": "https://js.example.com/bidding",
  "user_bidding_signals": {
    "valid": true,
    "arbitrary": "yes"
  },
  "trusted_bidding_data": {
    "trusted_bidding_uri": "https://js.example.com/bidding/trusted",
    "trusted_bidding_keys": [
      "key1",
      "key2"
    ]
  },
  "ads": [
    {
      "render_uri": "https://js.example.com/render/fetch_and_join_ad1",
      "metadata": {
        "valid": 1
      }
    },
    {
      "render_uri": "https://js.example.com/render/fetch_and_join_ad2",
      "metadata": {
        "valid": 2
      }
    }
  ]
}

Per ulteriori informazioni su come viene risolto il problema lato API, consulta la proposta di progettazione per la delega di Join CA.

Test

Dopo aver implementato la chiamata Fetch all'interno del codice client e aver configurato un endpoint sul lato DSP per restituire i dati del segmento di pubblico personalizzato, puoi testare la delega dell'unione a un segmento di pubblico personalizzato. Prima di eseguire l'app, devi eseguire i comandi nella pagina Configurazione test. Dopo aver eseguito questi comandi, dovresti essere in grado di iniziare a effettuare chiamate utilizzando l'API Fetch.

Per vedere un esempio di questo flusso, sono state aggiunte chiamate di recupero al repository di esempi di Privacy Sandbox su GitHub.

Partecipare direttamente a un segmento di pubblico personalizzato

Se disponi già di tutte le informazioni necessarie per creare e partecipare a un pubblico personalizzato, puoi farlo direttamente utilizzando una chiamata asincrona dell'API Protected Audience. Per creare o partecipare direttamente a un segmento di pubblico personalizzato:

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

Kotlin

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

// Minimal initialization of a CustomAudience object
val audience: 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()

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

// Minimal initialization of a CustomAudience object
CustomAudience audience = 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();

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

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

Gestire i risultati di joinCustomAudience()

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

  • Il callback onResult() indica che il segmento di pubblico personalizzato è stato creato o aggiornato.
  • Il callback onError() indica due possibili condizioni.

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

Uscire da un segmento di pubblico personalizzato

Se l'utente non soddisfa più i criteri aziendali per un determinato pubblico personalizzato, un'app o un SDK può chiamare leaveCustomAudience() per rimuovere il pubblico personalizzato dal dispositivo. Per rimuovere un CustomAudience in base ai suoi parametri unici:

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

Kotlin

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

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

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

Java

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

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

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

Analogamente alla chiamata di joinCustomAudience(), i segnali OutcomeReceiver indicano la fine di una chiamata API. Per proteggere la privacy, un risultato di errore non distingue tra errori interni e argomenti non validi. Il callback onResult() viene chiamato al termine della chiamata API, indipendentemente dal fatto che un segmento di pubblico personalizzato corrispondente venga rimosso correttamente o meno.