Guide du développeur FLEDGE sur Android

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

FLEDGE sur Android inclut l'API Custom Audience et l'API 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, 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 FLEDGE sur Android, consultez la proposition de conception.

Ce guide du développeur explique comment utiliser FLEDGE sur Android pour :

  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, vous devez :

  1. Configurer votre environnement de développement pour la Privacy Sandbox sur Android.
  2. Installer une image système sur un appareil compatible ou configurer un émulateur compatible avec la Privacy Sandbox sur Android.
  3. Dans un terminal, activer l'accès à l'API FLEDGE (désactivé par défaut) à l'aide de la commande adb suivante.

      adb shell device_config put adservices ppapi_app_allow_list \"*\"
    
  4. Inclure une autorisation ACCESS_ADSERVICES_CUSTOM_AUDIENCE dans le fichier manifeste de votre application :

      <uses-permission android:name="android.permission.ACCESS_ADSERVICES_CUSTOM_AUDIENCE" />
    
  5. 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" />
    
  6. 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>
    
  7. 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.

Kotlin

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

// Initialize a custom audience.
val audience = CustomAudience.Builder()
    .setBuyer(buyer)
    .setName(name)
    ...
    .build()

// Initialize a custom audience request.
val joinCustomAudienceRequest: JoinCustomAudienceRequest =
    JoinCustomAudienceRequest.Builder().setCustomAudience(audience).build()

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

Java

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

// Initialize a custom audience.
CustomAudience audience = new CustomAudience.Builder()
    .setBuyer(buyer)
    .setName(name)
    ...
    .build();

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

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

La 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, alors 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 : une 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.

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 : une 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 toutes les plates-formes et à réduire la consommation des fonctions JavaScript.
  • Données d'enchères de confiance : une URL HTTPS et une 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 : une 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 : un 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.

Voici un exemple d'instanciation d'objets CustomAudience :

Kotlin

// Minimal initialization of a CustomAudience object
val customAudience: CustomAudience = CustomAudience.Builder()
    .setBuyer(AdTechIdentifier.fromString("my.buyer.domain.name"))
    .setName("example-custom-audience-name")
    .setDailyUpdateUrl(Uri.parse("https://DAILY_UPDATE_URL"))
    .setBiddingLogicUrl(Uri.parse("https://BIDDING_LOGIC_URL"))
    .build()

Java

// Minimal initialization of a CustomAudience object
CustomAudience customAudience = CustomAudience.Builder()
    .setBuyer(AdTechIdentifier.fromString("my.buyer.domain.name"))
    .setName("example-custom-audience-name")
    .setDailyUpdateUrl(Uri.parse("https://DAILY_UPDATE_URL"))
    .setBiddingLogicUrl(Uri.parse("https://BIDDING_LOGIC_URL"))
    .build();

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.

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

Kotlin

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

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

Java

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

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

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.

Kotlin

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

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

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

Java

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

// Initialize a LeaveCustomAudienceRequest
LeaveCustomAudienceRequest leaveCustomAudienceRequest =
    new JoinCustomAudienceRequest.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 fera 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 FLEDGE, 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.

Kotlin

val adSelectionManager: AdSelectionManager =
    context.getSystemService(AdSelectionManager::class.java)

// Initialize AdSelectionConfig
val adSelectionConfig: AdSelectionConfig =
        AdSelectionConfig.Builder()
                .setSeller(seller)
                .setDecisionLogicUrl(decisionLogicUrl)
                .setCustomAudienceBuyers(customAudienceBuyers)
                .setAdSelectionSignals(adSelectionSignals)
                .setSellerSignals(sellerSignals)
                .setPerBuyerSignals(perBuyerSignals)
                .build()

// Run ad selection with AdSelectionConfig
adSelectionManager.selectAds(
    adSelectionConfig,
    executor,
    outcomeReceiver)

Java

AdSelectionManager adSelectionManager =
    context.getSystemService(AdSelectionManager.class);

// Initialize AdSelectionConfig
AdSelectionConfig adSelectionConfig =
        new AdSelectionConfig.Builder()
                .setSeller(seller)
                .setDecisionLogicUrl(decisionLogicUrl)
                .setCustomAudienceBuyers(customAudienceBuyers)
                .setAdSelectionSignals(adSelectionSignals)
                .setSellerSignals(sellerSignals)
                .setPerBuyerSignals(perBuyerSignals)
                .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 :

  • Vendeur : identifiant du réseau publicitaire du vendeur qui lance la sélection des annonces.
  • URL de logique de décision : une URL HTTPS interrogée pour obtenir la logique JavaScript du réseau publicitaire du vendeur. Consultez les signatures de fonctions requises dans ce JavaScript.
  • 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() des audiences personnalisées participantes.

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

  • Signaux de sélection d'annonces : un 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().
  • Signaux du vendeur : un 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().
  • Signaux de l'acheteur : une map 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 audiences personnalisées participantes des acheteurs.

Une fois qu'une annonce est sélectionnée, les résultats, les enchères et les signaux sont conservés en interne pour un rapport ultérieur. À partir du rappel ResultReceiver.onResult(), vous obtiendrez un résultat AdSelectionOutcome contenant :

  • une URL de rendu de l'annonce gagnante, obtenue à partir de 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() fournira 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 recevront une AdServicesException avec IllegalStateException pour cause.

Signaler une impression d'annonce

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 AdSelectionConfig et l'exécuteur (Executor) pertinent ainsi que les objets OutcomeReceiver.

Java

AdSelectionManager adSelectionManager =
    context.getSystemService(AdSelectionManager.class);

// Initialize a ReportImpressionRequest
ReportImpressionRequest adSelectionConfig =
        new ReportImpressionRequest.Builder()
                .setAdSelectionId(adSelectionId)
                .setAdSelectionConfig(adSelectionConfig);
                .build();

// Request to report the impression with the ReportImpressionRequest
adSelectionManager.reportImpression(
    reportImpressionRequest,
    executor,
    outcomeReceiver);

Kotlin

val adSelectionManager = context.getSystemService(AdSelectionManager::class.java)

// Initialize a ReportImpressionRequest
val adSelectionConfig: ReportImpressionRequest =
    ReportImpressionRequest.Builder()
        .setAdSelectionId(adSelectionId)
        .setAdSelectionConfig(adSelectionConfig);
        .build()

// Request to report the impression with the ReportImpressionRequest
adSelectionManager.reportImpression(
    reportImpressionRequest,
    executor,
    outcomeReceiver)

Initialisez ReportImpressionRequest avec les paramètres obligatoires suivants :

  • ID de sélection d'annonces : un 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 la sélection d'annonces est terminée.
  • Le rappel onError() indique les conditions possibles suivantes :
    • Si l'appel est initialisé avec un argument d'entrée non valide, l'AdServicesException indiquera IllegalArgumentException comme en étant la cause.
    • Toutes les autres erreurs recevront une AdServicesException avec IllegalStateException pour cause.

Points de terminaison des rapports sur les impressions

L'API d'impression des rapports enverra 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 utilisera l'URL de logique des enchères spécifiée dans l'audience personnalisée pour extraire le JavaScript de la logique d'enchères de l'acheteur.
  • Appelez la fonction JavaScript reportResult(), qui doit renvoyer l'URL du rapport sur les impressions de l'acheteur.

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

  • Utilisez l'URL de 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 reportWin(), qui doit renvoyer l'URL du rapport sur les impressions de l'acheteur.

Obtenir les meilleurs rapports sur les impressions

reportImpression() est conçu pour compléter au mieux les rapports.

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 ignorera tous les champs incorrects qui ne généreront aucune mise à jour de ce champ particulier dans la réponse.
  • Une réponse HTTP vide ou un objet JSON "{}" vide n'entraînera 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 :

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 :

generateBid()

function generateBid(
   ad,
   auction_signals,
   per_buyer_signals,
   trusted_bidding_signals,
   contextual_signals,
   user_signals,
   custom_audience_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_signals : objet JSON généré par la plate-forme. Le format de cet objet JSON est le suivant :

    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 : une 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 renvoyé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 de la map perBuyerSignal dans le paramètre d'API AdSelectionConfig en utilisant l'acheteur d'audience personnalisée actuel comme clé. Ce champ est vide si la map 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

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 qui sera transmis à la fonction reportWin
    • reporting_url : une URL qui permettra à la plate-forme de 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 sur scoreAds
  • signals_for_buyer : objet JSON renvoyé par reportResult
  • contextual_signals, custom_audience_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 :
    • reporting_url : une URL qui permettra à la plate-forme de notifier l'impression au vendeur

Tests

Pour vous aider à démarrer avec FLEDGE, nous avons créé des exemples d'applications en Kotlin et Java, disponibles sur GitHub.

Conditions préalables

FLEDGE nécessite du JavaScript lors de la sélection des annonces et 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 savoir comment effectuer des forçages, consultez l'application exemple FLEDGE 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 FLEDGE montre comment lire le code de ce fichier et 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.

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 ci-dessous :

  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.

Kotlin

val testAdSelectionManager: TestAdSelectionManager =
  context.getSystemService(AdSelectionManager::class.java).getTestAdSelectionManager()

// Initialize AdSelectionConfig =
val adSelectionConfig = new AdSelectionConfig.Builder()
    .setSeller(seller)
    .setDecisionLogicUrl(decisionLogicUrl)
    .setCustomAudienceBuyers(customAudienceBuyers)
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .build()

// Initialize AddAddSelectionOverrideRequest
val request = AddAdSelectionOverrideRequest.Builder()
    .setAdSelectionConfig(adSelectionConfig)
    .setDecisionLogicJs(decisionLogicJS)
    .build()

// Run the call to override the JavaScript for the given AdSelectionConfig
// Note that this only takes effect in apps marked as debuggable
testAdSelectionManager.overrideAdSelectionConfigRemoteInfo(
    request,
    executor,
    outComeReceiver)

Java

TestAdSelectionManager testAdSelectionManager =
  context.getSystemService(AdSelectionManager.class).getTestAdSelectionManager();

// Initialize AdSelectionConfig =
AdSelectionConfig adSelectionConfig = new AdSelectionConfig.Builder()
    .setSeller(seller)
    .setDecisionLogicUrl(decisionLogicUrl)
    .setCustomAudienceBuyers(customAudienceBuyers)
    .setAdSelectionSignals(adSelectionSignals)
    .setSellerSignals(sellerSignals)
    .setPerBuyerSignals(perBuyerSignals)
    .build();

// Initialize AddAddSelectionOverrideRequest
AddAdSelectionOverrideRequest request = AddAdSelectionOverrideRequest.Builder()
    .setAdSelectionConfig(adSelectionConfig)
    .setDecisionLogicJs(decisionLogicJS)
    .build();

// Run the call to override the JavaScript for the given AdSelectionConfig
// Note that this only takes effect in apps marked as debuggable
testAdSelectionManager.overrideAdSelectionConfigRemoteInfo(
    request,
    executor,
    outComeReceiver);

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 savoir comment lire un fichier JavaScript sous forme de chaîne, consultez l'application exemple FLEDGE 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 application 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é.

Kotlin

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

Java

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

Une fois que vous avez réinitialisé les forçages côté vente, les futurs appels de selectAds() utilisent la decisionLogicUrl stockée 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 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.

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.

Kotlin

val testCustomAudienceManager: TestCustomAudienceManager =
  context.getSystemService(CustomAudienceManager::class.java).getTestCustomAudienceManager()

// Join custom audience

// Build the AddCustomAudienceOverrideRequest
val request = AddCustomAudienceOverrideRequest.Builder()
    .setBuyer(buyer)
    .setName(name)
    .setBiddingLogicJs(biddingLogicJS)
    .setTrustedBiddingSignals(trustedBiddingSignals)
    .build()

// Run the call to override JavaScript for the given custom audience
testCustomAudienceManager.overrideCustomAudienceRemoteInfo(
    request,
    executor,
    outComeReceiver)

Java

TestCustomAudienceManager testCustomAudienceManager =
  context.getSystemService(CustomAudienceManager.class).getTestCustomAudienceManager();

// Join custom audience

// Build the AddCustomAudienceOverrideRequest
AddCustomAudienceOverrideRequest request =
    AddCustomAudienceOverrideRequest.Builder()
        .setBuyer(buyer)
        .setName(name)
        .setBiddingLogicJs(biddingLogicJS)
        .setTrustedBiddingSignals(trustedBiddingSignals)
        .build();

// Run the call to override JavaScript for the given custom audience
testCustomAudienceManager.overrideCustomAudienceRemoteInfo(
    request,
    executor,
    outComeReceiver);

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 à utiliser 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 futurs appels de selectAds() utiliseront la logique d'enchères et de création de rapports que vous avez transmise pour le remplacement.

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

Kotlin

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

Java

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

Une fois que vous avez réinitialisé les forçages côté achat, les futurs appels 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 à FLEDGE que la génération de rapports sur les impressions a abouti.

Fonctionnalité à tester

  • Testez de rejoindre/quitter et configurer une audience personnalisée en fonction des actions précédentes de l'utilisateur.
  • Testez 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 processus FLEDGE. 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.

Élément Description de la limite Valeur limite
Audience personnalisée (CA) Nombre maximal d'annonces par audience personnalisée 100
Nombre maximal d'audiences personnalisées par application 1000
Nombre maximal d'applications pouvant créer une audience personnalisée 1000
Délai maximal d'activation d'une autorité de certification après sa création 60 jours
Délai d'expiration maximal d'une audience personnalisée à partir de son heure d'activation 60 jours
Nombre maximal d'audiences personnalisées sur l'appareil 4 000
Taille maximale du nom de l'audience personnalisée 200 octets
Taille maximale de l'URI d'exploration quotidien 400 octets
Taille maximale de l'URI de la logique d'enchères 400 octets
Taille maximale des données d'enchères de confiance 10 Ko
Taille maximale des signaux d'enchères utilisateur 10 Ko
Taux maximal d'appel de leaveCustomAudience par acheteur 1 par seconde
Taux maximal d'appel de joinCustomAudience par acheteur 1 par seconde
Récupération en arrière-plan de l'autorité de certification Délai d'inactivité de la connexion 5 secondes
Expiration du délai de lecture HTTP 30 secondes
Taille maximale totale de téléchargement 10 Ko
Durée maximale d'une itération de récupération 5 minutes
Nombre maximal d'autorités de certification mises à jour par tâche 1000
Sélection des annonces Nombre maximal d'acheteurs À déterminer
Nombre maximal d'audiences personnalisées par acheteur À déterminer
Nombre maximal d'annonces dans une enchère À déterminer
Délai d'expiration de la connexion initiale 5 secondes
Délai d'expiration de la lecture de la connexion 5 secondes
Temps d'exécution maximal de l'élément AdSelection global 10 secondes
Durée maximale d'exécution des enchères par autorité de certification dans AdSelection 5 secondes
Durée d'exécution maximale de l'attribution du score dans AdSelection 5 secondes
Temps d'exécution maximal par acheteur dans AdSelection À déterminer
Taille maximale des signaux de sélection d'annonces/de vendeur/par acheteur À déterminer
Taille maximale des scripts vendeur/acheteurs À déterminer
Tarif d'appel maximal pour selectAds 1 RPS
Rapports sur les impressions Délai minimal avant la suppression de la sélection des annonces de la persistance 24 h
Nombre maximal d'annonces de stockage sélectionnées À déterminer
Taille maximale de l'URL de sortie des rapports À déterminer
Durée maximale de la génération des rapports sur les impressions À déterminer
Nombre maximal de tentatives pour les appels de notification À déterminer
Délai d'inactivité de la connexion 5 secondes
Temps d'exécution global maximal pour reportImpression 2 secondes
Tarif d'appel maximal pour reportImpressions 1 RPS
Annonces Taille maximale de la liste d'annonces 10 Ko partagés par tous les éléments AdData dans une autorité de certification unique (à déterminer pour le contexte)
URL Longueur maximale d'une chaîne d'URL en tant qu'entrée À déterminer
JavaScript Temps d'exécution maximal 1 seconde pour les enchères et l'attribution des scores dans les rapports sur les impressions
Mémoire maximale utilisée 10 Mo

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.