Définir des données d'audience

Une audience personnalisée représente un groupe d'utilisateurs ayant des intentions ou des centres d'intérêt communs, d'après l'application d'un annonceur. Une application ou un SDK peut utiliser une audience personnalisée pour indiquer une audience spécifique, telle qu'une personne ayant laissé des articles dans un panier.

L'API Android Protected Audience permet de rejoindre et de quitter des audiences personnalisées sur l'appareil d'un utilisateur. Lorsque vous créez et rejoignez une audience personnalisée, vous pouvez déléguer à un serveur à partir duquel vous extrayez tout ou partie des propriétés de l'audience personnalisée, ou vous pouvez spécifier ces informations lorsque vous appelez directement l'API.

Audiences personnalisées

La combinaison des paramètres suivants identifie de manière unique chaque objet CustomAudience d'un appareil :

• owner : nom de package de l'application propriétaire. Il est implicitement défini sur le nom de package de l'application appelante.
• buyer : identifiant du réseau publicitaire de l'acheteur qui gère les annonces pour cette audience personnalisée.
• name : nom ou identifiant arbitraire pour l'audience personnalisée.

De plus, CustomAudience doit être créé avec les paramètres obligatoires suivants :

• URL de mise à jour quotidienne : URL HTTPS demandée quotidiennement en arrière-plan pour mettre à jour les signaux d'enchères utilisateur et les données d'enchères approuvées d'une audience personnalisée, et pour afficher les URL et les métadonnées pour les annonces.
• URL de logique d'enchères : une URL HTTPS demandée lors de la sélection d'une annonce pour récupérer la logique d'enchères JavaScript d'un acheteur. Consultez les signatures de fonctions requises dans ce JavaScript.
• ID de rendu des annonces : ID arbitraire défini par la technologie publicitaire de l'acheteur. Il s'agit d'une optimisation permettant de générer la charge utile pour les enchères et mises aux enchères.

Les paramètres facultatifs d'un objet CustomAudience peuvent inclure :

• Délai d'activation : une audience personnalisée ne peut participer à la sélection des annonces et aux mises à jour quotidiennes qu'après son délai d'activation. Cela peut être utile pour susciter l'engagement des utilisateurs inactifs, par exemple.
• Délai d'expiration : délai après lequel l'audience personnalisée sera supprimée de l'appareil.
• Signaux d'enchères de l'utilisateur : chaîne JSON contenant des signaux de l'utilisateur, tels que ses paramètres régionaux préférés, utilisée par le JavaScript de la logique d'enchères d'un acheteur pour générer des enchères lors du processus de sélection des annonces. Ce format aide les plates-formes de technologie publicitaire à réutiliser le code sur plusieurs plates-formes et à réduire la consommation des fonctions JavaScript.
• Données d'enchères de confiance : URL HTTPS et liste de chaînes utilisées lors du processus de sélection des annonces pour extraire les signaux d'enchères d'un serveur clés/valeurs de confiance.
• Annonces : liste d'objets AdData correspondant aux annonces qui participeront à la sélection des annonces. Chaque objet AdData comprend les éléments suivants :
  • URL de rendu : une URL HTTPS qui est interrogée pour afficher l'annonce finale.
  • Métadonnées : objet JSON sérialisé sous forme de chaîne contenant des informations qui seront utilisées par la logique d'enchères de l'acheteur lors du processus de sélection des annonces.
  • Filtres d'annonces : classe contenant toutes les informations nécessaires pour le filtrage des annonces incitant à installer une application et pour la limitation de la fréquence d'exposition lors de la sélection des annonces.

Extraire et rejoindre une audience personnalisée

L'API fetchAndJoinCustomAudience permet aux acheteurs de déléguer la participation à une audience personnalisée en exploitant la présence sur l'appareil de leurs MMP ou SSP partenaires.

Pour que cela fonctionne, l'appelant sur l'appareil (qu'il s'agisse d'un MMP ou d'un SDK SSP) crée un fetchAndJoinCustomAudienceRequest qui se présente comme suit:

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

Remarque importante concernant tous les paramètres facultatifs : s'ils sont définis dans la requête de récupération, leurs données ne peuvent pas être remplacées par ce qui est renvoyé par l'acheteur. L'appelant sur l'appareil dispose ainsi de contrôles supplémentaires sur ce que conserve l'audience personnalisée.

fetchUri doit diriger vers un point de terminaison de serveur géré par l'acheteur, qui renverra un objet JSON d'audience personnalisée correspondant au format présenté ici :

//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
      }
    }
  ]
}

Pour en savoir plus sur la résolution de ce problème côté API, consultez la proposition de conception pour participer à la délégation d'autorité de certification.

Tests

Une fois que vous avez implémenté l'appel Fetch dans le code client et que vous avez configuré un point de terminaison côté DSP pour renvoyer les données d'audience personnalisée, vous pouvez tester la délégation de participation à l'audience personnalisée. Avant d'exécuter votre application, vous devez exécuter les commandes sur la page Configuration de test. Une fois que vous avez exécuté ces commandes, vous devriez pouvoir commencer à effectuer des appels à l'aide de l'API Fetch.

Pour voir un exemple de ce flux, des appels de récupération ont été ajoutés au dépôt d'exemples Privacy Sandbox sur GitHub.

Rejoindre directement une audience personnalisée

Si vous disposez déjà de toutes les informations nécessaires pour créer et rejoindre une audience personnalisée, vous pouvez le faire directement à l'aide d'un appel d'API Protected Audience asynchrone. Pour créer ou rejoindre directement une audience personnalisée, procédez comme suit:

1. Initialisez l'objet CustomAudienceManager.
2. Créez un objet CustomAudience en indiquant des paramètres clés tels que le package de l'acheteur et un nom pertinent. Ensuite, initialisez l'objet JoinCustomAudienceRequest avec l'objet CustomAudience.
3. Appelez la méthode asynchrone joinCustomAudience() avec l'objet JoinCustomAudienceRequest et l'exécuteur (Executor) pertinent ainsi que les objets OutcomeReceiver.

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

Gérer les résultats de joinCustomAudience()

La méthode joinCustomAudience() asynchrone utilise l'objet OutcomeReceiver pour signaler le résultat de l'appel d'API.

• Le rappel onResult() signifie que l'audience personnalisée a bien été créée ou mise à jour.
• Le rappel onError() signifie deux conditions possibles.
  • Si le rappel JoinCustomAudienceRequest est initialisé avec des arguments non valides, l'AdServicesException indique IllegalArgumentException comme cause.
  • Toutes les autres erreurs reçoivent une AdServicesException avec IllegalStateException pour cause.

Voici un exemple de gestion du résultat de joinCustomAudience() :

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

Quitter une audience personnalisée

Si l'utilisateur ne répond plus aux critères d'entreprise d'une audience personnalisée donnée, une application ou un SDK peut appeler leaveCustomAudience() pour supprimer l'audience personnalisée de l'appareil. Pour supprimer une audience personnalisée (CustomAudience) en fonction de ses paramètres uniques, procédez comme suit :

1. Initialisez l'objet CustomAudienceManager.
2. Initialisez LeaveCustomAudienceRequest avec les éléments buyer et name de l'audience personnalisée. Pour en savoir plus sur ces champs de saisie, consultez Rejoindre directement une audience personnalisée.
3. Appelez la méthode asynchrone leaveCustomAudience() avec l'objet LeaveCustomAudienceRequest et l'exécuteur (Executor) pertinent ainsi que les objets OutcomeReceiver.

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

Comme pour l'appel de joinCustomAudience(), OutcomeReceiver indique la fin d'un appel d'API. Pour protéger la confidentialité, un résultat d'erreur ne fait pas la distinction entre les erreurs internes et les arguments non valides. Le rappel onResult() est appelé à la fin de l'appel d'API, qu'une audience personnalisée correspondante ait été supprimée ou non.