Guide du développeur de l'API Protected Audience

Lorsque vous lisez la documentation concernant la Privacy Sandbox sur Android, cliquez sur le bouton Preview développeur ou Bêta pour sélectionner la version du programme que vous utilisez, car les instructions peuvent varier.

L'API Protected Audience sur Android (anciennement FLEDGE) inclut les API Custom Audience et Ad Selection. Les plates-formes et les annonceurs de technologie publicitaire peuvent utiliser ces API pour diffuser des annonces personnalisées en fonction de l'engagement avec une application précédente, ce qui limite le partage d'identifiants entre les applications ainsi que le partage des informations d'interaction de l'utilisateur avec des tiers.

L'API Custom Audience est centrée sur l'abstraction "audience personnalisée", qui représente un groupe d'utilisateurs ayant des intentions communes. Un annonceur peut enregistrer un utilisateur avec une audience personnalisée et lui associer des annonces pertinentes. Ces informations sont stockées localement et peuvent être utilisées pour aiguiller les enchères des annonceurs, ainsi que le filtrage et l'affichage des annonces.

L'API Ad Selection fournit un framework qui permet à plusieurs développeurs de lancer une mise aux enchères locale pour une audience personnalisée. Pour ce faire, le système prend en compte les annonces pertinentes associées à l'audience personnalisée et effectue un traitement supplémentaire sur les annonces qu'une plate-forme de technologie publicitaire renvoie à l'appareil.

Les plates-formes de technologie publicitaire peuvent intégrer ces API pour implémenter le remarketing qui préserve la confidentialité des utilisateurs. D'autres cas d'utilisation, comme les annonces incitant à installer une application, seront pris en charge dans les prochaines versions. Pour en savoir plus sur l'API Protected Audience sur Android, consultez la proposition de conception.

Ce guide explique comment utiliser l'API Protected Audience sur Android pour effectuer les actions suivantes :

1. Gérer les audiences personnalisées
2. Configurer et diffuser la sélection d'annonces sur un appareil
3. Générer des rapports sur les impressions d'annonces

Avant de commencer

Avant de commencer, procédez comme suit :

1. Configurez votre environnement de développement pour la Privacy Sandbox sur Android.
2. Installez une image système sur un appareil compatible ou configurez un émulateur prenant en charge la Privacy Sandbox sur Android.

3. Dans un terminal, activez l'accès à l'API Protected Audience (désactivé par défaut) à l'aide de la commande adb suivante.

     adb shell device_config put adservices ppapi_app_allow_list \"*\"
   

4. Dans un terminal, activez la création de rapports sur les balises à l'aide des commandes adb suivantes.

    adb shell device_config put adservices fledge_beacon_reporting_metrics_enabled true
    adb shell device_config put adservices fledge_register_ad_beacon_enabled true
   

5. Inclure une autorisation ACCESS_ADSERVICES_CUSTOM_AUDIENCE dans le fichier manifeste de votre application :

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

6. Référencer une configuration de services publicitaires dans l'élément <application> de votre fichier manifeste :

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

7. Spécifier la ressource XML des services publicitaires référencée dans votre fichier manifeste, telle que res/xml/ad_services_config.xml. En savoir plus sur les autorisations des services publicitaires et le contrôle des accès au SDK.

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

8. Par défaut, l'API Ad Selection limite la quantité maximale de mémoire que des enchères ou qu'un script de création de rapports sur les impressions peut allouer. La fonctionnalité de limitation de la mémoire nécessite WebView version 105.0.5195.58 ou ultérieure. La plate-forme applique une vérification des versions, et les appels des API selectAds et reportImpression échouent si tel n'est pas le cas. Vous pouvez configurer cette vérification de deux manières :

   • Option 1 : exécutez la commande adb suivante pour désactiver cette vérification :

     adb device_config put fledge_js_isolate_enforce_max_heap_size false
     

   • Option 2 : installez WebView bêta depuis le Google Play Store. La version de WebView doit être supérieure ou égale à la version mentionnée précédemment.

Rejoindre une audience personnalisée

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. Pour créer ou rejoindre une audience personnalisée de manière asynchrone, 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)

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

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

En appelant joinCustomAudience() de manière répétée avec une autre instance de CustomAudience, toute valeur CustomAudience existante est mise à jour avec la valeur owner, buyer et les paramètres name correspondants. Pour des raisons de confidentialité, le résultat de l'API ne fait pas la distinction entre "création" et "mise à jour".

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.

Voici un exemple d'instanciation d'objets CustomAudience :

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

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

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

Lancer une sélection d'annonces

Pour sélectionner des annonces à l'aide de l'API Protected Audience, appelez la méthode selectAds() :

1. Initialisez un objet AdSelectionManager.
2. Créez un objet AdSelectionConfig.
3. Appelez la méthode asynchrone selectAds() avec l'objet AdSelectionConfig et l'exécuteur (Executor) pertinent ainsi que les objets OutcomeReceiver.

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
)

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

La méthode selectAds() requiert une entrée AdSelectionConfig, dans laquelle vous devez spécifier les paramètres obligatoires suivants :

• Seller (Vendeur) : identifiant du réseau publicitaire du vendeur qui lance la sélection des annonces.
• Decision logic URL : URL HTTPS interrogée pour obtenir la logique JavaScript du réseau publicitaire du vendeur.
  • URL HTTPS : URL interrogée pour obtenir la logique JavaScript du réseau publicitaire du vendeur. Consultez les signatures de fonctions requises.
  • URI prédéfini : qui respecte le format de sélection d'annonces de FLEDGE. L'exception IllegalArgumentException est générée si un URI prédéfini non compatible ou non valide est transmis.
• Acheteurs d'audiences personnalisées : liste complète des identifiants des réseaux publicitaires de l'acheteur qui sont autorisés par le vendeur à participer au processus de sélection des annonces. Ces identifiants d'acheteurs correspondent à CustomAudience.getBuyer() parmi les audiences personnalisées participantes.

Les paramètres suivants peuvent éventuellement être spécifiés pour une sélection d'annonces plus personnalisée :

• Ad selection signals (Signaux de sélection d'annonces) : objet JSON, sérialisé sous forme de chaîne, contenant des signaux utilisés par le JavaScript de la logique d'enchères récupéré à partir de CustomAudience.getBiddingLogicUrl().
• Seller signals (Signaux du vendeur) : objet JSON, sérialisé sous forme de chaîne, contenant les signaux utilisés par la logique de décision JavaScript du vendeur récupérée à partir de AdSelectionConfig.getDecisionLogicUrl().
• Per buyer signals (Signaux par acheteur) : mappage d'objets JSON, sérialisés en tant que chaînes, contenant des signaux utilisés par le JavaScript de la logique d'enchères de certains acheteurs récupérée à partir de CustomAudience.getBiddingLogicUrl(), qui sont identifiés par les champs des acheteurs correspondant aux audiences personnalisées participantes.
• Annonces contextuelles : ensemble d'annonces candidates qui sont collectées directement auprès des acheteurs lors d'enchères qui ont lieu en dehors d'enchères Protected Audience.

Une fois qu'une annonce est sélectionnée, les résultats, les enchères et les signaux sont conservés en interne pour permettre la création de rapports. Le rappel OutcomeReceiver.onResult() renvoie un AdSelectionOutcome contenant les éléments suivants :

• Une URL de rendu de l'annonce gagnante, générée par AdData.getRenderUrl().
• Un ID de sélection d'annonces propre à l'utilisateur de l'appareil. Cet ID permet de générer des rapports sur l'impression d'annonce.

Si la sélection des annonces ne s'effectue pas correctement pour des raisons telles que des arguments non valides, des délais d'inactivité ou une utilisation excessive des ressources, le rappel OutcomeReceiver.onError() générera une AdServicesException avec les comportements suivants :

• Si la sélection d'annonces est lancée avec des arguments non valides, AdServicesException indiquera IllegalArgumentException comme en étant la cause.
• Toutes les autres erreurs reçoivent une AdServicesException avec IllegalStateException pour cause.

Annonces contextuelles

Protected Audience peut intégrer des annonces contextuelles à des enchères protégées. Les annonces contextuelles doivent être sélectionnées sur le serveur ad tech et renvoyées à l'appareil en dehors des API Protected Audience. Les annonces contextuelles peuvent ensuite être incluses aux enchères via l'AdSelectionConfig, où elles fonctionnent de la même manière que les annonces sur l'appareil, y compris en ce qui concerne l'éligibilité au filtrage des annonces à exclure. Une fois les enchères Protected Audience terminées, vous devez appeler reportImpression(). reportWin() est appelé dans l'annonce contextuelle gagnante, comme dans les rapports sur les impressions, afin que l'annonce gagnante soit reçue sur un appareil. Chaque annonce contextuelle nécessite un acheteur, une enchère, un lien vers la logique de création de rapports, une URL de rendu et les métadonnées de l'annonce.

Pour déployer des annonces contextuelles dans l'application, l'application cible doit créer un objet ContextualAds :

val contextualAds: ContextualAds =
  Builder().setBuyer(AdTechIdentifier.fromString(mBiddingLogicUri.getHost()))
    //Pass in your valid app install ads
    .setDecisionLogicUri(mContextualLogicUri)
    .setAdsWithBid(appInstallAd)
    .build()

ContextualAds contextualAds = new ContextualAds.Builder()
  .setBuyer(AdTechIdentifier.fromString(mBiddingLogicUri.getHost()))
  .setDecisionLogicUri(mContextualLogicUri)
  //Pass in your valid app install ads
  .setAdsWithBid(appInstallAd)
  .build();

L'objet ContextualAds généré peut ensuite être transmis lors de la création de l'objet AdSelectionConfig :

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

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

Filtrage des annonces incitant à installer une application

Le filtrage des annonces incitant à installer une application vous permet de filtrer les annonces d'installation correspondant aux applications déjà installées sur un appareil.

La première étape consiste à définir les annonceurs qui peuvent filtrer le package installé. Cela doit se produire dans l'appli que vous souhaitez cibler avec une annonce.

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

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

Lors de l'exécution du code précédent, les annonceurs transmis peuvent filtrer les applications installées que vous spécifiez lors de la génération de leurs enchères. Pour empêcher un annonceur d'accéder à l'état d'installation de cette application, exécutez à nouveau ce code en supprimant les informations le concernant.

L'étape suivante consiste à configurer le filtrage des annonces dans l'application de l'éditeur. Le tiers qui diffuse l'annonce dans l'application de l'éditeur (généralement un SDK côté offre) doit initialiser son objet AdFilters avec des informations sur les annonces associées aux applications qu'il souhaiterait filtrer :

// Instantiate AdFilters object with package names.
val filters: AdFilters = Builder().setAppInstallFilters(
    Builder().setPackageNames(setOf("example.target.app")).build()
  ).build()

// Instantiate AdFilters object with package names.
AdFilters filters = new AdFilters.Builder()
.setAppInstallFilters(
  new AppInstallFilters.Builder()
  .setPackageNames(Collections.singleton("example.target.app"))
  .build())
.build();

Les éditeurs côté demande peuvent également définir un AdFilter pour les annonces qui existent dans leurs audiences personnalisées.

AdFilters peut également être transmis au moment d'instancier un nouvel objet AdData :

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

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

Filtrage de la limite de la fréquence d'exposition

Le filtrage de la limite de la fréquence d'exposition permet aux technologies publicitaires de limiter le nombre de diffusions des annonces. Le filtrage de la limite de la fréquence d'exposition réduit la surexposition des annonces et optimise la sélection d'annonces de substitution pour une campagne publicitaire donnée.

Un filtre de limite de la fréquence d'exposition comporte deux composants principaux : le type d'événement d'annonce et la clé de compteur d'annonces. Vous pouvez utiliser les types d'événements d'annonce suivants :

• Victoire : une victoire indique que l'annonce a remporté une mise aux enchères. Les événements gagnants sont automatiquement mis à jour par l'API Protected Audience et ne peuvent pas être appelés directement par le développeur. Les données gagnantes ne sont visibles que par les annonces d'une audience personnalisée donnée.
• Impression : indépendamment de reportImpression, un appelant sur l'appareil (SSP ou MMP) utilise updateAdCounterHistogram() pour appeler des événements d'impression au point choisi dans le code. Les événements d'impression sont visibles par toutes les annonces appartenant à une DSP donnée et ne se limitent pas aux annonces de la même audience personnalisée.
• Vue : l'événement est appelé par l'appelant sur l'appareil (SSP ou MMP) à un point du code qu'il choisit à l'aide d'un appel à updateAdCounterHistogram(). Les événements de vue sont visibles par toutes les annonces appartenant à une DSP donnée et ne se limitent pas aux annonces de la même audience personnalisée.
• Clic : l'événement est appelé par l'appelant sur l'appareil (SSP ou MMP) à un point du code qu'il choisit à l'aide d'un appel à updateAdCounterHistogram(). Les événements de clic sont visibles par toutes les annonces appartenant à une DSP donnée et ne se limitent pas aux annonces de la même audience personnalisée.

Dans l'application d'éditeur, un SSP ou un MMP présent sur l'appareil appelle des événements d'annonce. Lorsque updateAdCounterHistogram() est appelé, le compteur d'un filtre de limite de la fréquence d'exposition est incrémenté de sorte que les futures enchères disposent d'informations à jour sur l'exposition d'un utilisateur à une annonce donnée. Les types d'événements d'annonce ne sont pas obligatoirement liés à l'action de l'utilisateur correspondant et sont fournis pour aider les appelants à structurer leur système d'événements. Pour incrémenter les compteurs d'annonces au moment d'un événement, l'acteur sur l'appareil fournit l'ID de sélection d'annonces de l'enchère publicitaire gagnante.

Les clés de compteur d'annonces sont des entiers 32 bits arbitraires signés, attribués par une technologie publicitaire de l'acheteur. Elles correspondent à un ensemble d'annonces donné, tel que défini par la DSP. Étant donné que les clés de compteur d'annonces sont limitées aux annonces appartenant à une DSP donnée, ces clés peuvent être sélectionnées sans chevaucher les histogrammes d'une autre technologie publicitaire. Les clés de compteur d'annonces sont utilisées pour incrémenter les identifiants spécifiques aux DSP dans les annonces d'une DSP ou dans une audience personnalisée donnée afin de filtrer les annonces lors des futures mises aux enchères.

Les clés de compteur peuvent être utilisées pour donner la priorité aux annonces qui sont les plus susceptibles d'intéresser un utilisateur donné en fonction de ses interactions avec les autres annonces d'une technologie publicitaire d'un acheteur donné. Par exemple, une annonce ayant enregistré un niveau élevé d'engagement suite à l'enchère gagnante, aux vues et aux clics représente un point de données déduit. Pour illustrer ce point : une annonce pour des clubs de golf pour gauchers peut indiquer que l'utilisateur ne s'intéresserait pas à des clubs pour droitiers. Un filtre de limite de la fréquence d'exposition défini pour une clé de compteur attribuée à des annonces pour gauchers pourrait filtrer les annonces pour les clubs pour droitiers.

Pour utiliser la limitation de la fréquence d'exposition dans votre enchère, vous devez d'abord créer des objets KeyedFrequencyCap, comme indiqué ci-dessous :

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

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

Une fois les objets KeyedFrequencyCap créés, vous pouvez les transmettre dans un objet AdFilters.

val filters: AdFilters = Builder()
  .setFrequencyCapFilters(
    Builder()
      .setKeyedFrequencyCapsForImpressionEvents(
        ImmutableObject.of(keyedFrequencyCapForImpression)
      )
      .setKeyedFrequencyCapsForClickEvents(
        ImmutableObject.of(keyedFrequencyCapForClick)
      )
  ).build()

AdFilters filters = new AdFilters.Builder()
    .setFrequencyCapFilters(new FrequencyCapFilters.Builder()
        .setKeyedFrequencyCapsForImpressionEvents(
            ImmutableObject.of(keyedFrequencyCapForImpression)
        )
        .setKeyedFrequencyCapsForClickEvents(
            ImmutableObject.of(keyedFrequencyCapForClick)
        )
    ).build();

Lorsque l'objet AdFilters est renseigné avec des filtres de limite de la fréquence d'exposition, il peut être transmis lors de la création de l'audience personnalisée :

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

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

Lorsque des filtres de limite de la fréquence d'exposition sont appliqués à une audience personnalisée, la SSP peut ensuite appeler le clic, l'affichage ou les événements d'impression nécessaires.

val callerAdTech: AdTechIdentifier = mAdSelectionConfig.getSeller()

val request: UpdateAdCounterHistogramRequest = Builder(
  adSelectionId,
  FrequencyCapFilters.AD_EVENT_TYPE_CLICK,  //CLICK, VIEW, or IMPRESSION
  callerAdTech
).build()

AdTechIdentifier callerAdTech = mAdSelectionConfig.getSeller();

UpdateAdCounterHistogramRequest request =
  new UpdateAdCounterHistogramRequest.Builder(
      adSelectionId,
      FrequencyCapFilters.AD_EVENT_TYPE_CLICK, //CLICK, VIEW, or IMPRESSION
      callerAdTech
).build();

Les annonces ayant atteint les limites de filtre de limite de la fréquence d'exposition prédéfinie sont exclues de la mise aux enchères. Le filtrage a lieu avant que la logique d'enchères ne soit exécutée pour les enchères sur l'appareil et lorsque la charge utile est générée pour les enchères des services d'enchères et de mise aux enchères. Ce kit offre aux technologies publicitaires la flexibilité d'utiliser les interactions entre les utilisateurs et les annonces dans leurs audiences personnalisées pour cibler les annonces tout en minimisant leur surexposition.

Filtrage des annonces contextuelles sans appels réseau

En l'absence de demande de remarketing sur l'appareil, vous pouvez exécuter une sélection d'annonces contextuelles sans appels réseau. Grâce à des URI prédéfinis et une liste d'annonces contextuelles avec enchères, la plate-forme peut ignorer la récupération de la logique d'enchères, des signaux d'enchères et des signaux d'évaluation. Elle utilise un URI prédéfini pour sélectionner l'annonce contextuelle associée à l'enchère la plus élevée.

Pour améliorer la latence, les technologies publicitaires peuvent exécuter un flux de sélection d'annonces n'incluant que des annonces contextuelles avec une fonctionnalité de filtrage des annonces sans appel réseau. Pour ce faire, utilisez des URI prédéfinis pour les signaux d'évaluation. Reportez-vous à la section Cas d'utilisation et noms d'URI prédéfinis compatibles pour obtenir la liste des implémentations scoreAds.

Pour exécuter la sélection des annonces sans appels réseau, procédez comme suit :

1. Configurer le filtrage des annonces
2. Créer vos annonces contextuelles

3. Créez un objet AdSelectionConfig avec les éléments suivants :

   1. Liste d'acheteurs vide
   2. URI prédéfini permettant de sélectionner l'enchère la plus élevée
   3. Annonces contextuelles
   4. URI vide pour les signaux d'évaluation L'URI vide est autorisé à indiquer que vous ne souhaitez pas utiliser l'extraction des signaux de confiance pour l'évaluation :

   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. Lancez une sélection d'annonces :

   adSelectionManager.selectAds(
       adSelectionConfig,
       executor,
       outcomeReceiver);
   

Exécuter votre propre code JavaScript de création de rapports tout en utilisant des URI prédéfinis

Aujourd'hui, la plate-forme Privacy Sandbox ne dispose que d'une implémentation JavaScript de base pour la création de rapports pour les URI prédéfinis. Si vous souhaitez exécuter votre propre JavaScript de création de rapports tout en utilisant des URI prédéfinis pour une sélection d'annonces à faible latence, vous pouvez ignorer l'élément DecisionLogicUri entre la sélection des annonces et les exécutions de rapports.

1. Suivez la procédure de sélection des annonces contextuelles à l'aide d'URI prédéfinis.

2. Créez une copie de votre AdSelectionConfig avant de générer des rapports.

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

3. Générez un rapport sur les impressions :

   // adSelectionId is from the result of the previous selectAds run
   ReportImpressionRequest request = new ReportImpressionRequest(
     adSelectionId,
     adSelectionConfigWithYourReportingJS);
   adSelectionManager.reportImpression(
     request,
     executor,
     outcomeReceiver);
   

Exécuter une médiation en cascade

La médiation en cascade nécessite que plusieurs SDK tiers (réseaux tiers) soient ordonnés par un réseau de médiation de SDK propriétaire. La médiation en cascade est effectuée de la même manière, que la mise aux enchères ait eu lieu sur l'appareil ou via des services d'enchères et de mise aux enchères.

Réseaux tiers

Les réseaux tiers doivent fournir un adaptateur permettant au réseau de médiation d'appeler les méthodes nécessaires à une mise aux enchères :

• Lancer une sélection d'annonces
• Générer des rapports sur les impressions

Voici un exemple d'adaptateur réseau de médiation :

class NetworkAdaptor {
    private val adSelectionManager : AdSelectionManager

    init {
        adSelectionManager = context.getSystemService(AdSelectionManager::class.java)
    }

    fun selectAds() {...}

    fun reportImpressions() {...}
}

class NetworkAdaptor {
    AdSelectionManager adSelectionManager;

    public NetworkAdaptor() {
        AdSelectionManager adSelectionManager =
            context.getSystemService(AdSelectionManager.class);
    }

    public void selectAds() {...}

    public void reportImpressions() {...}
}

Chaque SDK possède ses propres clients et gestionnaires de services de sélection d'annonces, ainsi que sa propre implémentation selectAds et reportImpressions. Les fournisseurs de SDK peuvent se reporter aux sections expliquant comment lancer une sélection d'annonces pour les enchères sur l'appareil ou à la section de présentation des enchères et des mises aux enchères pour ces dernières. Suivez la procédure permettant de générer des rapports sur les impressions d'annonces (en suivant les instructions du rapport sur les impressions SSP uniques).

Réseau de médiation

Comme les réseaux tiers, les réseaux de médiation nécessitent des implémentations selectAds et reportImpression. Pour en savoir plus, consultez les sections Lancer une sélection d'annonces et Générer des rapports sur les impressions d'annonces.

Les réseaux de médiation sont chargés d'exécuter la chaîne de médiation et de s'y insérer. La section suivante explique comment configurer et exécuter ce processus.

Récupérer les planchers d'enchères et la chaîne de médiation

Le réseau de médiation est chargé de récupérer les annonces contextuelles propriétaires, la chaîne de médiation et les planchers d'enchères des réseaux tiers. Cela peut se produire dans une requête de récupération des annonces contextuelles exécutées par le réseau de médiation. La chaîne de médiation détermine comment effectuer des itérations sur les réseaux tiers, et les prix planchers des enchères peuvent être transmis au processus d'enchères en tant que adSelectionSignals.

Positionnement sur le réseau dans la chaîne de médiation

Un SDK de médiation peut se positionner dans la chaîne de médiation en fonction de son eCPM en temps réel pour les enchères d'annonces propriétaires. Dans l'API Protected Audience, les enchères d'annonces sont opaques. Un SDK de médiation doit utiliser AdSelectionFromOutcomesConfig pour pouvoir comparer l'enchère d'une annonce propriétaire donnée au prix plancher du prochain réseau tiers dans la chaîne. Si l'enchère propriétaire est supérieure au prix plancher de l'enchère, cela signifie que le SDK de médiation passe devant ce réseau tiers.

Lancer une sélection d'annonces

Pour récupérer une annonce propriétaire potentielle, le réseau de médiation peut effectuer une mise aux enchères sur l'appareil en suivant les étapes de la section Lancer une sélection d'annonces. Cela génère une annonce propriétaire possible, une enchère et un AdSelectionId qui sera utilisé dans le processus de médiation.

Créer un élément AdSelectionFromResultssConfig

Un élément AdSelectionFromOutcomesConfig permet au réseau de médiation de transmettre une liste d'AdSelectionIds (résultats des enchères précédentes), des signaux de sélection d'annonces et un URI pour extraire le code JavaScript qui sélectionnera une annonce parmi plusieurs possibilités. La liste des identifiants de sélection d'annonce (AdSelectionId) avec leurs enchères et les signaux sont transmis au code JavaScript qui peut renvoyer l'un des AdSelectionIds s'il dépasse le prix plancher de l'enchère, ou rien si la chaîne de médiation doit continuer.

Les réseaux de médiation créent un AdSelectionFromOutcomesConfig à l'aide de l'AdSelectionId propriétaire de la section précédente et du plancher d'enchères correspondant au réseau tiers en question. Un nouvel AdSelectionFromOutcomesConfig doit être créé pour chaque étape de la chaîne de médiation.

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

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

Le forçage de la méthode selectAds() pour la médiation en cascade nécessite une entrée AdSelectionFromOutcomesConfig, dans laquelle vous devez spécifier les paramètres obligatoires suivants :

• Seller (Vendeur) : identifiant du réseau publicitaire du vendeur qui lance la sélection des annonces.
• AdSelectionIds : liste singleton d'une exécution selectAds() précédente pour une annonce propriétaire.
• Signaux de sélection d'annonces : objet JSON, sérialisé en tant que chaîne, contenant des signaux à utiliser par la logique d'enchères de l'acheteur. Dans ce cas, incluez le prix plancher extrait pour le réseau tiers donné.
• Selection Logic URI (URI de la logique de sélection) : URL HTTPS interrogée lors de la sélection d'annonce pour extraire le code JavaScript du réseau de médiation afin de sélectionner une annonce gagnante. Consultez les signatures de fonctions requises dans cet extrait JavaScript. Le code JavaScript doit renvoyer l'annonce tierce si l'enchère est supérieure à son prix plancher. Sinon, elle renvoie null. Cela permet au SDK de médiation de tronquer la chaîne de médiation lorsqu'une annonce gagnante est identifiée.

Une fois le AdSelectionOutcomesConfig créé, appelez la méthode selectAds() du réseau tiers qui se trouve en premier sur la chaîne.

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)

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

Orchestrer la médiation en cascade

Voici l'ordre des opérations à exécuter lors du processus de médiation.

1. Lancez la sélection d'une annonce propriétaire.
2. Itérez la chaîne de médiation. Pour chaque réseau tiers, procédez comme suit :
   1. Créez la AdSelectionFromOutcomeConfig, y compris le outcomeId propriétaire et le plancher d'enchères du SDK tiers.
   2. Appelez selectAds() avec la configuration de l'étape précédente.
   3. Si le résultat n'est pas vide, renvoyez l'annonce.
   4. Appelez la méthode selectAds() de l'adaptateur réseau actuel du SDK. Si le résultat n'est pas vide, renvoyez l'annonce.
3. Si aucun gagnant n'apparaît dans la chaîne, renvoyez l'annonce propriétaire.

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

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

Générer des rapports sur les impressions d'annonces

Deux méthodes permettent de générer un rapport sur une impression d'annonce, selon le mode de mise en concurrence des annonces. Si vous êtes un seul SSP diffusant des enchères, suivez cette section. Si vous souhaitez implémenter la médiation en cascade, suivez les étapes décrites dans la section Générer des rapports sur les impressions de médiation en cascade.

Rapports sur les impressions SSP uniques

Une fois qu'une annonce gagnante a été sélectionnée dans le workflow de sélection des annonces, vous pouvez signaler l'impression aux plates-formes côté achat et côté vente participantes à l'aide de la méthode AdSelectionManager.reportImpression(). Pour générer un rapport sur une impression d'annonce :

1. Initialisez un objet AdSelectionManager.
2. Compilez un objet ReportImpressionRequest avec l'ID de sélection d'annonces.
3. Appelez la méthode asynchrone reportImpression() avec l'objet ReportImpressionRequest et l'exécuteur (Executor) pertinent ainsi que les objets OutcomeReceiver.

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

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)

Initialisez ReportImpressionRequest avec les paramètres obligatoires suivants :

• Ad selection ID (ID de sélection d'annonces) : ID propre à l'utilisateur de l'appareil et identifiant une sélection d'annonces réussie.
• Configuration des sélections d'annonces : la même configuration que celle utilisée dans l'appel selectAds() identifié par l'ID de sélection d'annonces fourni.

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

• Le rappel onResult() indique si des URL de rapport sur les impressions ont été créées et si la requête a été planifiée.
• Le rappel onError() indique les conditions possibles suivantes :
  • Si l'appel est initialisé avec un argument d'entrée non valide, AdServicesException indique une cause (IllegalArgumentException).
  • Toutes les autres erreurs reçoivent une AdServicesException avec IllegalStateException pour cause.

Générer des rapports sur les impressions de médiation en cascade

Un SDK de médiation doit suivre le SDK gagnant pour déclencher ses flux de rapports. Les SDK participant à une chaîne de médiation doivent fournir une méthode permettant au médiateur d'appeler le déclenchement de son propre flux de rapports. Un SDK participant à une mise aux enchères par médiation peut suivre les étapes ci-dessus pour implémenter ses propres rapports.

Les SSP peuvent utiliser cet exemple de code de SDK tiers comme prototype pour participer aux flux de médiation :

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

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

Points de terminaison des rapports sur les impressions

L'API de rapports sur les impressions envoie des requêtes GET HTTPS aux points de terminaison fournis par la plate-forme côté vente et par la plate-forme côté achat gagnante :

Point de terminaison de la plate-forme côté achat :

• L'API utilise l'URL de logique des enchères spécifiée dans l'audience personnalisée pour extraire le JavaScript fourni par l'acheteur, qui comprend une logique permettant d'afficher une URL de création de rapports sur les impressions.
• Appelez la fonction JavaScript reportWin(), qui doit afficher l'URL du rapport sur les impressions de l'acheteur.

Point de terminaison de la plate-forme côté vente :

• Utilisez l'URL de la logique de décision spécifiée dans l'objet AdSelectionConfig pour récupérer le JavaScript de la logique de décision du vendeur.
• Appelez la fonction JavaScript reportResult(), qui doit renvoyer l'URL du rapport sur les impressions du vendeur.

Rapports sur les services d'enchères et de mise aux enchères

Une mise aux enchères exécutée sur des services d'enchères intègre toutes les informations nécessaires à la création de rapports, y compris les URL générées pour les rapports sur les interactions avec les annonces. Ces informations sont incluses dans la réponse chiffrée de l'enchère côté serveur. Lorsque la réponse est déchiffrée, les URL appropriées sont enregistrées auprès de la plate-forme. La création de rapports sur les annonces et les impressions suit donc les étapes décrites ci-dessus.

Obtenir les meilleurs rapports sur les impressions possibles

La méthode reportImpression() est conçue pour compléter au mieux les rapports.

Créer des rapports sur les interactions avec les annonces

Protected Audience permet de générer des rapports sur des interactions plus précises pour les annonces affichées. Il peut s'agir d'interactions telles que la durée de visionnage, les clics, les pointages ou toute autre métrique utile pouvant être collectée. Le processus pour recevoir ces rapports comprend deux étapes. Tout d'abord, les acheteurs et les vendeurs doivent demander explicitement à les recevoir dans leur code JavaScript de création de rapports. Le client doit ensuite signaler ces événements.

Demander à recevoir les événements d'interaction

Pour demander à recevoir les événements d'interaction, utilisez la fonction JavaScript reportWin() de l'acheteur et la fonction JavaScript reportResult() du vendeur à l'aide d'une fonction JavaScript fournie par la plate-forme : registerAdBeacon. Pour demander à recevoir un rapport sur les événements, il vous suffit d'appeler la fonction JavaScript de la plate-forme à partir de votre code JavaScript de création de rapports. L'extrait de code suivant utilise le reportWin() de l'acheteur, mais la même approche s'applique à reportResult().

reportWin(
  adSelectionSignals,
  perBuyerSignals,
  signalsForBuyer,
  contextualSignals,
  customAudienceSignals) {
    ...
    // Calculate reportingUri, clickUri, viewUri, and hoverUri

    registerAdBeacon({"click": clickUri, "view": viewUri, "hover": hoverUri});

    return reportingUri;
}

Créer des rapports sur les événements d'interaction

Après avoir enregistré une impression, les clients peuvent indiquer les interactions aux plates-formes côté vente et côté achat ayant remporté cette impression et précédemment enregistrées à l'aide de la méthode AdSelectionManager.reportInteraction(). Pour signaler un événement d'annonce :

1. Initialisez un objet AdSelectionManager.
2. Créez un objet ReportInteractionRequest avec l'ID de sélection d'annonces, la clé d'interaction, les données d'interaction et la destination du rapport.
3. Appelez la méthode asynchrone reportInteraction() avec l'objet request, ainsi que les objets Executor et OutcomeReceiver pertinents.

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

Initialisez ReportInteractionRequest avec les paramètres obligatoires suivants :

• ID de sélection d'annonces : ID de sélection d'annonces récupéré à partir d'un AdSelectionOutcome précédemment renvoyé.
• Clé d'interaction : clé de chaîne définie par le client décrivant l'action signalée. Elle doit correspondre à la clé enregistrée par le vendeur ou l'acheteur dans les fonctions JavaScript de création de rapports.
• Données d'interaction : chaîne contenant les données à inclure dans le rapport sur les événements, à renvoyer aux serveurs de création de rapports.
• Destinations du rapport : masque de bits indiquant si les événements doivent être signalés à l'acheteur, au vendeur ou aux deux. Ces indicateurs sont fournis par la plate-forme, et le masque de destination final peut être créé à l'aide d'opérations au niveau du bit. Pour créer un rapport pour une seule destination, vous pouvez utiliser l'indicateur fourni directement par la plate-forme. Pour créer un rapport pour plusieurs destinations, vous pouvez utiliser l'opérateur OR au niveau du bit (|) afin de combiner les valeurs des indicateurs.

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

• Le rappel onResult() indique que l'appel de création de rapports sur les interactions est valide.
• Le rappel onError() indique les conditions possibles suivantes :
  • Si l'appel est effectué lorsque l'application s'exécute en arrière-plan, une IllegalStateException est affichée avec une description de l'échec.
  • Si l'appel de reportInteraction() par le client est limité, une LimitExceededException est affichée.
  • Si le package n'est pas enregistré pour appeler les API protégeant la confidentialité, une SecurityException() est affichée.
  • Si les interactions de création de rapports de l'appli sont différentes de l'appli qui a appelé selectAds(), une IllegalStateException est affichée.
• Si l'utilisateur n'a pas autorisé l'activation des API Privacy Sandbox, l'appel échouera en mode silencieux.

Points de terminaison de création des rapports sur les interactions

L'API de création de rapports sur les interactions envoie des requêtes HTTPS POST aux points de terminaison fournis par la plate-forme côté vente et par la plate-forme côté achat gagnante. Protected Audience met en correspondance les clés d'interaction avec les URI déclarés dans le code JavaScript de création de rapports et envoie une requête POST à chaque point de terminaison pour chaque interaction signalée. Le type de contenu de la requête correspond à du texte brut, tandis que le corps correspond aux données d'interaction.

Obtenir les meilleurs rapports sur les interactions

Le reportInteraction() est conçu pour compléter au mieux les rapports via une requête POST HTTP.

Mise à jour quotidienne en arrière-plan

Lorsque vous créez une audience personnalisée, votre application ou votre SDK peut initialiser les métadonnées associées. En outre, la plate-forme peut mettre à jour les métadonnées d'audience personnalisées suivantes avec un processus de mise à jour quotidienne en arrière-plan.

• Signaux d'enchères de l'utilisateur
• Données d'enchères de confiance
• Liste AdData

Ce processus interroge l'URL de mise à jour quotidienne définie dans l'audience personnalisée et l'URL peut renvoyer une réponse JSON.

• La réponse JSON peut contenir l'un des champs de métadonnées compatibles devant être mis à jour.
• Chaque champ JSON est validé indépendamment. Le client ignore les champs non valides, ce qui ne génère aucune mise à jour de ces champs dans la réponse.
• Une réponse HTTP vide ou un objet JSON "{}" vide n'entraîne aucune mise à jour des métadonnées.
• La taille du message de réponse doit être limitée à 10 Ko.
• Tous les URI doivent utiliser HTTPS.
• trusted_bidding_uri doit partager les mêmes valeurs ETLD+1 que l'acheteur.

Exemple : réponse JSON pour une mise à jour quotidienne en arrière-plan

{
    "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 pour la sélection des annonces

Le processus de sélection des annonces orchestre l'exécution du JavaScript fourni par l'acheteur et par le vendeur.

Le code JavaScript fourni par l'acheteur est récupéré à partir de l'URL de logique d'enchères spécifiée dans l'audience personnalisée. Le JavaScript renvoyé doit inclure les fonctions suivantes :

• generateBid()
• reportWin()

Le code JavaScript fourni par le vendeur est récupéré à partir de l'URL de logique de décision spécifiée dans le paramètre AdSelectionConfig de l'API de sélection des annonces. Le JavaScript renvoyé doit inclure les fonctions suivantes :

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

Paramètres d'entrée :

• ad : objet JSON au format var ad = { 'render_url': url, 'metadata': json_metadata };.
• auction_signals, per_buyer_signals : objets JSON spécifiés dans l'objet de configuration des enchères.

• custom_audience_bidding_signals : objet JSON généré par la plate-forme. Voici le format de cet objet 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"
  }
  

  où :

  • owner, buyer et name sont des chaînes provenant des propriétés portant le même nom que l'audience personnalisée participant à la sélection d'annonces.
  • activation_time et expiration_time sont les heures d'activation et d'expiration de l'audience personnalisée, exprimées en secondes depuis l'epoch Unix.
  • ca_user_bidding_signals est une chaîne JSON spécifiée dans le champ userBiddingSignals de CustomAudience au moment de la création.
  • trusted_bidding_signals, contextual_signals et user_signals sont des objets JSON. Ils sont actuellement transmis en tant qu'objets vides et seront remplis dans les futures versions. Leur format n'est pas appliqué par la plate-forme et est géré par la technologie publicitaire.

Résultat :

• ad : est l'annonce à laquelle l'enchère fait référence. Le script est autorisé à renvoyer une copie de l'annonce reçue avec des métadonnées différentes. La propriété render_url de l'annonce ne doit pas avoir été modifiée.
• bid : une valeur flottante représentant la valeur de l'enchère pour cette annonce.
• status : valeur entière qui peut être :
  • 0 : pour une exécution réussie ;
  • 1 : (ou toute valeur non nulle) si l'un des signaux d'entrée n'est pas valide. Dans le cas où une valeur non nulle serait affichée par le processus de génération d'enchères, le processus d'enchères serait invalidé pour toutes les annonces d'audience personnalisée.

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

Paramètres d'entrée :

• ad : consultez la documentation generateBid.
• bid : valeur de l'enchère pour l'annonce.

• ad_selection_config : objet JSON représentant le paramètre AdSelectionConfig de l'API selectAds. Son format est le suivant :

  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 : objets JSON lus depuis le paramètre d'API sellerSignals AdSelectionConfig.

• trusted_scoring_signal : lu à partir du champ adSelectionSignals dans le paramètre d'API AdSelectionConfig.

• contextual_signals, user_signals : objets JSON. Ils sont actuellement transmis en tant qu'objets vides et seront remplis dans les futures versions. Leur format n'est pas appliqué par la plate-forme et est géré par la technologie publicitaire.

• per_buyer_signals : objet JSON lu à partir du mappage perBuyerSignal dans le paramètre d'API AdSelectionConfig en utilisant l'acheteur d'audience personnalisée actuel comme clé. Ce champ est vide si le mappage ne contient aucune entrée pour l'acheteur donné.

Sortie :

• score : une valeur flottante représentant le score pour cette annonce.
• status : une valeur entière qui peut être :
  • 0 : pour une exécution réussie
  • 1 : au cas où les customAudienceSignals ne seraient pas valides
  • 2 : au cas où AdSelectionConfig serait incorrect
  • 3 : au cas où l'un des autres signaux serait incorrect
  • Toute valeur non nulle entraînera l'échec du processus, la valeur déterminera le type d'exception générée

selectOutcome()

function selectOutcome(
  outcomes,
  selection_signals) {
    return {'status': 0, 'result': null};
}

Paramètres d'entrée :

• outcomes : objet JSON {"id": id_string, "bid": bid_double}.
• selection_signals : objets JSON spécifiés dans l'objet de configuration de la mise aux enchères.

Sortie :

• status : 0 en cas de réussite, et non nulle en cas d'échec.
• result : l'un des résultats transmis ou la valeur nulle.

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

Paramètres d'entrée :

• ad_selection_config : consultez la documentation sur scoreAds
• render_url : l'URL de rendu de l'annonce gagnante
• bid : l'enchère proposée pour l'annonce gagnante
• contextual_signals : consultez la documentation sur generateBid

Sortie :

• status: 0 en cas de réussite, et non nulle en cas d'échec
• results : un objet JSON contenant :
  • signals_for_buyer : un objet JSON transmis à la fonction reportWin.
  • reporting_url : une URL utilisée par la plate-forme pour notifier l'impression à l'acheteur.

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

Paramètres d'entrée :

• ad_selection_signals, per_buyer_signals : consultez la documentation pour scoreAd.
• signals_for_buyer : objet JSON renvoyé par reportResult.
• contextual_signals, custom_audience_signals : consultez la documentation pour generateBid.

Sortie :

• status: 0 en cas de réussite, et non nulle en cas d'échec
• results : un objet JSON contenant :
  • reporting_url : une URL utilisée par la plate-forme pour notifier l'impression au vendeur.

registerAdBeacon()

function registerAdBeacon(
  beacons
)

Paramètres d'entrée :

• beacons: objet contenant des paires clé/valeur de clés d'interaction et d'URI de création de rapports. Il a le format suivant :

  let beacons = {
    'interaction_key': 'reporting_uri',
    'interaction_key': 'reporting_uri',
    ...
  }
  

  • interaction_key : chaîne représentant l'événement. Elle sera utilisée par la plate-forme ultérieurement lors de la création de rapports sur les interactions au niveau des événements pour rechercher les reporting_uri qui doivent être notifiés. Cette clé doit correspondre à ce que l'acheteur ou le vendeur enregistre, et à ce que le vendeur signale.
  • reporting_uri : URI permettant de recevoir les rapports sur les événements. Il doit être spécifique au type d'événement signalé. Il doit accepter une requête POST pour traiter les données signalées avec l'événement.

  Exemple :

    let beacons = {
      'click': 'https://reporting.example.com/click_event',
      'view': 'https://reporting.example.com/view_event'
    }
  

URI prédéfinis pour la sélection des annonces

Les URI prédéfinis permettent aux technologies publicitaires de désigner des fonctions JavaScript pour la logique de décision de la sélection d'annonces dans les classes AdSelectionConfig et AdSelectionFromOutcomesConfig. Les URI prédéfinis ne nécessitent pas d'appels réseau pour télécharger le JavaScript correspondant. Les technologies publicitaires peuvent utiliser des URI prédéfinis sans avoir à configurer un domaine enregistré pour héberger le JavaScript.

Un URI prédéfini est construit au format suivant :

ad-selection-prebuilt:<use-case>/<name>?<required-script-generation-parameters>

La plate-forme Privacy Sandbox fournit du code JavaScript à l'aide des informations de cet URI dans l'environnement d'exécution.

Une IllegalArgumentException est générée dans les cas suivants :

• Un des paramètres obligatoires est absent de l'URI.
• L'URI comporte des paramètres non reconnus.

Cas d'utilisation et noms d'URI prédéfinis compatibles

Cas d'utilisation 1 : ad-selection

Les URI prédéfinis dans le cas d'utilisation ad-selection sont acceptés dans le flux selectAds(AdSelectionConfig).

Nom d'URI prédéfini : highest-bid-wins

Cet URI prédéfini fournit un JavaScript qui choisit l'annonce associée à l'enchère la plus élevée après la mise aux enchères. Il fournit également une fonction de base pour la création de rapports afin de signaler l'URI de rendu (render_uri) et l'enchère (bid) de l'annonce gagnante

Paramètres obligatoires

reportingUrl : l'URL de base pour la création de rapports paramétrée avec l'URI de rendu (render_uri) et l'enchère (bid) de l'annonce gagnante :

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

Utilisation

Si votre URL de base pour la création de rapports est https://www.ssp.com/reporting, l'URI prédéfini est le suivant :

`ad-selection-prebuilt://ad-selection/highest-bid-wins/?reportingUrl=https://www.ssp.com/reporting`

Cas d'utilisation 2 : ad-selection-from-outcomes

Les URI prédéfinis dans le cas d'utilisation ad-selection-from-outcomes sont compatibles avec le workflow selectAds(AdSelectionFromOutcomesConfig).

Nom d'URI prédéfini : waterfall-mediation-truncation

L'URI prédéfini waterfall-mediation-truncation fournit le JavaScript qui implémente la logique de troncation de la médiation en cascade dans laquelle le JavaScript renvoie une annonce propriétaire si l'enchère (bid) est supérieure ou égale au prix plancher (bid floor) et renvoie null dans les autres cas.

Paramètres obligatoires

bidFloor : clé de la valeur du prix plancher de l'enchère transmise dans getSelectionSignals() et comparée à l'annonce du SDK de médiation.

Utilisation

Si les signaux de sélection des annonces ressemblent à {"bid_floor": 10}, l'URI prédéfini qui en résulte est le suivant :

`ad-selection-prebuilt://ad-selection-from-outcomes/waterfall-mediation-truncation/?bidFloor=bid_floor`

Tests

Pour vous aider à faire vos premiers pas avec l'API Protected Audience, nous avons créé des applications exemples en Kotlin et Java, disponibles sur GitHub.

Conditions préalables

L'API Protected Audience nécessite du code JavaScript lors de la sélection des annonces et de la création des rapports sur les impressions. Il existe deux méthodes pour fournir ce JavaScript dans un environnement de test :

• Exécuter un serveur avec les points de terminaison HTTPS requis qui renvoie le JavaScript
• Forcer la récupération à distance en fournissant le code nécessaire à partir d'une source locale

Ces deux approches nécessitent la configuration d'un point de terminaison HTTPS pour gérer les rapports sur les impressions.

Points de terminaison HTTPS

Pour tester la sélection des annonces et les rapports sur les impressions, vous devez configurer sept points de terminaison HTTPS auxquels votre appareil de test ou votre émulateur peut accéder :

1. Point de terminaison de l'acheteur qui diffuse le JavaScript de la logique d'enchères.
2. Un point de terminaison qui diffuse les signaux d'enchères.
3. Point de terminaison du vendeur qui diffuse le code JavaScript de la logique de décision.
4. Point de terminaison qui diffuse des signaux d'évaluation.
5. Point de terminaison du rapport sur les impressions de l'acheteur ayant remporté l'enchère.
6. Point de terminaison du rapport sur les impressions du vendeur.
7. Un point de terminaison pour diffuser les mises à jour quotidiennes d'une audience personnalisée.

Pour plus de commodité, le dépôt GitHub fournit du code JavaScript de base à des fins de test. Il inclut également les définitions de service OpenAPI, qui peuvent être déployées sur une plate-forme fictive ou sur une plate-forme de microservices compatibles. Pour en savoir plus, consultez le fichier README du projet.

Forcer la récupération à distance de JavaScript

Cette fonctionnalité est destinée aux tests de bout en bout. Pour forcer l'extraction à distance, votre application doit s'exécuter en mode débogage avec les options pour les développeurs activées.

Pour activer le mode débogage pour votre application, ajoutez la ligne suivante à l'attribut d'application dans votre fichier AndroidManifest.xml :

<application
  android:debuggable="true">

Pour découvrir comment utiliser ces forçages, consultez l'application exemple de l'API Protected Audience sur GitHub.

Vous devez ajouter votre propre JavaScript personnalisé pour gérer les routines de sélection des annonces telles que les enchères, les évaluations et les rapports. Vous trouverez des exemples de code JavaScript de base qui traitent toutes les requêtes requises dans le dépôt GitHub. L'application exemple de l'API Protected Audience montre comment lire le code de ce fichier et comment le préparer pour le forcer.

Vous pouvez forcer la récupération JavaScript côté vente et côté achat, mais vous aurez besoin d'un point de terminaison HTTPS pour diffuser tout code JavaScript pour lequel vous ne fournissez pas de forçage. Consultez le fichier README pour découvrir comment configurer un serveur qui gère ces cas de figure.

Il n'est possible de forcer la récupération JavaScript que pour les audiences personnalisées appartenant à votre package.

Forcer le JavaScript côté vente

Pour configurer un forçage du JavaScript côté vente, procédez comme suit dans l'exemple de code suivant :

1. Initialisez un objet AdSelectionManager.
2. Obtenez une référence à TestAdSelectionManager à partir de l'objet AdSelectionManager.
3. Créez un objet AdSelectionConfig.
4. Créez une AddAdSelectionOverrideRequest avec l'objet AdSelectionConfig et une chaîne (String) représentant le JavaScript que vous souhaitez utiliser comme remplacement.
5. Appelez la méthode asynchrone overrideAdSelectionConfigRemoteInfo() avec l'objet AddAdSelectionOverrideRequest et l'exécuteur (Executor) pertinent ainsi que les objets OutcomeReceiver.

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)

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

Consultez la section Lancer une sélection d'annonces pour en savoir plus sur ce que chacun des champs d'AdSelectionConfig représente. La principale différence est que decisionLogicUrl peut être définie sur une valeur d'espace réservé puisqu'elle sera ignorée.

Afin de forcer le JavaScript utilisé lors de la sélection des annonces, decisionLogicJs doit contenir les signatures de fonction côté vendeur appropriées. Pour découvrir comment lire un fichier JavaScript sous forme de chaîne, consultez l'application exemple de l'API Protected Audience sur GitHub.

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

Le rappel onResult() signifie que le forçage a bien été appliqué. Les futurs appels de selectAds() utiliseront les logiques de décision et de création de rapports que vous avez transmises pour le forçage.

Le rappel onError() signifie deux conditions possibles :

• Si une tentative de forçage est effectuée avec des arguments non valides, AdServiceException indiquera IllegalArgumentException comme en étant la cause.
• Si vous tentez de forcer une appli qui ne s'exécute pas en mode débogage avec les options pour les développeurs activées, AdServiceException indiquera IllegalStateException comme en étant la cause.

Réinitialiser les forçages côté vente

Cette section suppose que vous avez ignoré le JavaScript côté vente et que vous faites référence à TestAdSelectionManager et à AdSelectionConfig utilisés dans la section précédente.

Pour réinitialiser les forçages pour toutes les AdSelectionConfigs :

1. Appelez la méthode resetAllAdSelectionConfigRemoteOverrides() asynchrone avec l'objet OutcomeReceiver approprié.

// Resets overrides for all AdSelectionConfigs
testAadSelectionManager.resetAllAdSelectionConfigRemoteOverrides(
  outComeReceiver)

// Resets overrides for all AdSelectionConfigs
testAdSelectionManager.resetAllAdSelectionConfigRemoteOverrides(
    outComeReceiver);

Une fois que vous avez réinitialisé les forçages côté vente, les appels à selectAds() utilisent l'élément decisionLogicUrl stocké dans AdSelectionConfig pour tenter de récupérer le JavaScript requis.

Si l'appel de resetAllAdSelectionConfigRemoteOverrides() échoue, le rappel OutComeReceiver.onError() fournit une AdServiceException. Si vous tentez de supprimer les forçages alors qu'une appli ne s'exécute pas en mode débogage avec les options pour les développeurs, AdServiceException indiquera IllegalStateException comme en étant la cause.

Remplacer le JavaScript côté achat

1. Suivez les étapes permettant de rejoindre une audience personnalisée.
2. Créez une AddCustomAudienceOverrideRequest avec l'acheteur (buyer) et le nom (name) de l'audience personnalisée que vous souhaitez remplacer, en plus de la logique d'enchères et des données que vous souhaitez utiliser pour ce remplacement.
3. Appelez la méthode asynchrone overrideCustomAudienceRemoteInfo() avec l'objet AddCustomAudienceOverrideRequest et l'exécuteur (Executor) pertinent ainsi que les objets OutcomeReceiver.

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)

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

Les valeurs pour buyer et name sont les mêmes que celles utilisées pour créer l'audience personnalisée. En savoir plus sur ces champs

Vous pouvez également spécifier deux paramètres supplémentaires :

• biddingLogicJs : JavaScript contenant la logique de l'acheteur utilisée lors de la sélection des annonces. Consultez les signatures de fonctions requises dans ce JavaScript.
• trustedBiddingSignals : signaux d'enchères à utiliser lors de la sélection des annonces. À des fins de test, il peut s'agir d'une chaîne vide.

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

Le rappel onResult() signifie que le forçage a bien été appliqué. Les appels ultérieurs envoyés à selectAds() utilisent la logique d'enchères et de création de rapports que vous avez transmise pour le forçage.

Le rappel onError() signifie deux conditions possibles.

• Si une tentative de forçage est effectuée avec des arguments non valides, AdServiceException indiquera IllegalArgumentException comme en étant la cause.
• Si vous tentez de forcer une appli qui ne s'exécute pas en mode débogage avec les options pour les développeurs activées, AdServiceException indiquera IllegalStateException comme en étant la cause.

Réinitialiser les forçages côté acheteur

Cette section suppose que vous avez ignoré le JavaScript côté achat et que vous faites référence à TestCustomAudienceManager utilisé dans la section précédente.

Pour réinitialiser les forçages de toutes les audiences personnalisées :

1. Appelez la méthode resetAllCustomAudienceOverrides() asynchrone avec les objets Executor et OutcomeReceiver pertinents.

// Resets overrides for all custom audiences
testCustomAudienceManager.resetCustomAudienceRemoteInfoOverride(
    executor,
    outComeReceiver)

// Resets overrides for all custom audiences
testCustomAudienceManager.resetCustomAudienceRemoteInfoOverride(
    executor,
    outComeReceiver)

Une fois que vous avez réinitialisé les forçages côté achat, les appels ultérieures de selectAds() utilisent les biddingLogicUrl et trustedBiddingData stockés dans CustomAudience pour essayer de récupérer le JavaScript requis.

Si l'appel de resetCustomAudienceRemoteInfoOverride() échoue, le rappel OutComeReceiver.onError() fournit une AdServiceException. Si vous tentez de supprimer les forçages lorsqu'une application ne s'exécute pas en mode débogage avec les options pour les développeurs activées, AdServiceException indiquera IllegalStateException comme en étant la cause.

Configurer un serveur de création de rapports

Lorsque vous utilisez des forçages de récupération à distance, vous devez tout de même configurer un serveur auquel votre appareil ou émulateur peut accéder pour répondre aux événements de rapport. Un point de terminaison simple qui renvoie 200 suffit à effectuer des tests. Le dépôt GitHub inclut également les définitions de service OpenAPI, qui peuvent être déployées sur une plate-forme fictive ou sur une plate-forme de microservices compatibles. Pour en savoir plus, consultez le fichier README du projet.

Lorsque vous cherchez les définitions OpenAPI, recherchez le fichier "reporting-server.json". Ce fichier contient un point de terminaison simple qui renvoie 200, ce qui représente un code de réponse HTTP. Ce point de terminaison est utilisé pendant selectAds() et signale à l'API Protected Audience que les rapports sur les impressions ont bien été générés.

Fonctionnalité à tester

• Essayez de rejoindre/quitter et configurer une audience personnalisée en fonction des actions précédentes de l'utilisateur.
• Testez le lancement de la sélection d'annonces sur l'appareil à l'aide de JavaScripts hébergés à distance.
• Observez comment l'association d'une application à des paramètres d'audience personnalisés peut influer sur les résultats de la sélection des annonces.
• Testez la génération de rapports sur les impressions après la sélection des annonces.

Limites

Le tableau suivant présente les limites applicables au traitement de API Protected Audience. Celles-ci présentées peuvent changer en fonction des commentaires que nous recevrons. Pour les fonctionnalités en cours, consultez les notes de version.

Signaler des bugs et des problèmes

Vos commentaires sont essentiels pour la Privacy Sandbox sur Android. Signalez-nous les problèmes que vous rencontrez et vos idées pour améliorer Privacy Sandbox sur Android.