Definire i dati sul pubblico

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

L'API Protected Audience per Android può essere utilizzata per partecipare a e uscire da segmenti di pubblico personalizzati sul dispositivo di un utente. Quando crei e unisci un segmento di pubblico personalizzato, puoi delegare a un server da cui recupererai 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. Viene impostato implicitamente sul nome del pacchetto dell'app chiamante.
  • buyer: identificatore della rete pubblicitaria dell'acquirente che gestisce gli annunci per questo segmento di pubblico personalizzato.
  • name: un nome o un identificatore arbitrario per il segmento di pubblico personalizzato.

Inoltre, CustomAudience deve essere creato con i seguenti parametri obbligatori:

  • URL di aggiornamento giornaliero: un URL HTTPS su cui viene eseguita una query giornaliera in background per aggiornare gli indicatori di offerta per gli utenti e i dati di offerta attendibili di un segmento di pubblico personalizzato, nonché gli URL di rendering e i metadati per gli annunci.
  • URL della logica di offerta: un URL HTTPS sottoposto a query durante la selezione degli annunci per recuperare la logica di offerta JavaScript di un acquirente. Consulta le signature delle funzioni richieste in questo codice JavaScript.
  • ID di rendering dell'annuncio: un ID arbitrario impostato dalla tecnologia pubblicitaria dell'acquirente. Si tratta di un'ottimizzazione per la generazione del payload per B&A.

I parametri facoltativi per un oggetto CustomAudience possono includere:

  • Data e ora di attivazione: un segmento di pubblico personalizzato può partecipare alla selezione degli annunci e agli aggiornamenti giornalieri solo dopo la data e l'ora di attivazione. Ad esempio, può essere utile per coinvolgere gli utenti inattivi di un'app.
  • Data e ora di scadenza: una data e un'ora future dopo le quali il segmento di pubblico personalizzato viene rimosso dal dispositivo.
  • Indicatori per le offerte per gli utenti: una stringa JSON contenente indicatori per gli utenti, come la lingua preferita dell'utente, che viene utilizzata dalla logica di offerta JavaScript di un acquirente per generare offerte durante la procedura di selezione degli annunci. Questo formato consente alle piattaforme di ad tech di riutilizzare il codice su più piattaforme e semplifica il consumo nelle funzioni JavaScript.
  • Dati di asta attendibili: un URL HTTPS e un elenco di stringhe utilizzate durante la procedura di selezione degli annunci che recuperano gli indicatori di asta 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 a cui viene eseguita una query per eseguire il rendering dell'annuncio finale.
    • Metadati: un oggetto JSON serializzato come stringa contenente informazioni da utilizzare dalla logica di offerta dell'acquirente durante la procedura di selezione degli annunci.
    • Filtri annunci: un'entità che contiene tutte le informazioni necessarie per il filtro degli annunci di installazione di app e la limitazione della frequenza durante la selezione degli annunci.

Recuperare e unire un segmento di pubblico personalizzato

L'API fetchAndJoinCustomAudience consente agli acquirenti di delegare l'inclusione in un segmento di pubblico personalizzato sfruttando la presenza on-device delle loro SSP o MMP partner.

Affinché ciò funzioni, l'autore della chiamata sul dispositivo (che si tratti di un SDK MMP o SSP) crea un fetchAndJoinCustomAudienceRequest simile al seguente:

KotlinJava
/**
 * @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()

/**
 * @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 sostituiti da quelli restituiti dall'acquirente, dando all'utente chiamante sul dispositivo ulteriori controlli su quale segmento di pubblico personalizzato viene mantenuto.

fetchUri deve puntare a un endpoint del server gestito dall'acquirente, che restituirà un oggetto JSON Custom Audience corrispondente al formato visualizzato 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
      }
    }
  ]
}

Ulteriori informazioni su come viene risolto il problema lato API sono disponibili nella Proposta di design per la delega della CA di join.

Test

Dopo aver implementato la chiamata Fetch all'interno del codice client e aver configurato un endpoint 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 dei 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, le chiamate di recupero sono state aggiunte 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 unire un segmento di 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. Quindi, inizializza l'oggetto JoinCustomAudienceRequest con l'oggetto CustomAudience.
  3. Chiama joinCustomAudience() asincrono con l'oggetto JoinCustomAudienceRequest e gli oggetti Executor e OutcomeReceiver pertinenti.
KotlinJava
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)

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

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

Ecco un esempio di gestione dell'esito di joinCustomAudience():

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

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

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

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

Lasciare un segmento di pubblico personalizzato

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

  1. Inizializza l'oggetto CustomAudienceManager.
  2. Inizializza LeaveCustomAudienceRequest con buyer e name del segmento di pubblico personalizzato. Per scoprire di più su questi campi di immissione, consulta "Unisci direttamente un segmento di pubblico personalizzato".
  3. Chiama il metodo leaveCustomAudience() asincrono con l'oggetto LeaveCustomAudienceRequest e gli oggetti Executor e OutcomeReceiver pertinenti.
KotlinJava
val customAudienceManager: CustomAudienceManager =
    context.getSystemService(CustomAudienceManager::class.java)

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

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

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

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

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

Analogamente alla chiamata di joinCustomAudience(), OutcomeReceiver indica la fine di una chiamata API. Per contribuire a 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 all'API, indipendentemente dal fatto che un segmento di pubblico personalizzato corrispondente sia stato rimosso correttamente o meno.