Gestionnaire de sélection des annonces

get

public static AdSelectionManager get (Context context)

Méthode par défaut permettant de créer une instance d'AdSelectionManager.

getAdSelectionData

public void getAdSelectionData (GetAdSelectionDataRequest request, 
                Executor executor, 
                OutcomeReceiver<GetAdSelectionDataOutcome, Exception> receiver)

Collecte des données d'audience personnalisées à partir de l'appareil. Renvoie un blob compressé et chiffré à envoyer à des serveurs d'enchères pour la sélection des annonces. Pour en savoir plus, consultez la page Enchères et les services d'enchères.

Les annonces d'audience personnalisée doivent avoir un ad_render_id pour pouvoir être collectées.

Consultez AdSelectionManager#persistAdSelectionResult pour savoir comment traiter les résultats de la sélection d'annonces s'exécute côté serveur avec le blob généré par cette API.

La sortie est transmise par le récepteur, qui renvoie soit un GetAdSelectionDataOutcome pour une exécution réussie, soit un Exception qui inclut le type de l'exception générée et le message d'erreur correspondant.

Si l'exception IllegalArgumentException est générée, cela est dû à un argument d'entrée non valide. reçues par l'API pour exécuter la sélection d'annonces.

Si l'IllegalStateException est générée avec le message d'erreur "Failure of AdSelection" services.", cela est dû à une défaillance interne du service de sélection d'annonces.

Si l'exception TimeoutException est générée, cela se produit lorsqu'un délai avant expiration est atteint. au cours du processus d'enchères, d'évaluation ou de sélection globale pour trouver l'annonce gagnante.

Si l'exception LimitExceededException est générée, cela se produit lorsque le package appelant dépasse les limites de débit autorisées et est limité.

Si l'exception SecurityException est générée, cela se produit lorsque l'appelant n'est pas autorisé. ou si l'autorisation n'est pas demandée.
Nécessite AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

Gestionnaire de la sélection d'annonces getTest

public TestAdSelectionManager getTestAdSelectionManager ()

persistAdSelectionResult

public void persistAdSelectionResult (PersistAdSelectionResultRequest request, 
                Executor executor, 
                OutcomeReceiver<AdSelectionOutcome, Exception> receiver)

Permet de conserver les résultats de la sélection d'annonces côté serveur. Pour en savoir plus, consultez la page Enchères et les services d'enchères

Consultez AdSelectionManager#getAdSelectionData pour savoir comment générer un blob chiffré pour une sélection d'annonces côté serveur.

La sortie est transmise par le récepteur, qui renvoie soit un AdSelectionOutcome. pour une exécution réussie, ou une Exception inclut le type de l'exception générée et le message d'erreur correspondant.

Si l'exception IllegalArgumentException est générée, cela est dû à un argument d'entrée non valide. reçues par l'API pour exécuter la sélection d'annonces.

Si l'IllegalStateException est générée avec le message d'erreur "Failure of AdSelection" services.", cela est dû à une défaillance interne du service de sélection d'annonces.

Si l'exception TimeoutException est générée, cela se produit lorsqu'un délai avant expiration est atteint. au cours du processus d'enchères, d'évaluation ou de sélection globale pour trouver l'annonce gagnante.

Si l'erreur LimitExceededException est générée, cela se produit lorsque le package appelant dépasse les limites de débit autorisées et est limité.

Si l'exception SecurityException est générée, cela se produit lorsque l'appelant n'est pas autorisé. ou si l'autorisation n'est pas demandée.
Nécessite AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

reportEvent

public void reportEvent (ReportEventRequest request, 
                Executor executor, 
                OutcomeReceiver<Object, Exception> receiver)

Informe le service qu'un nouvel événement d'annonce doit être consigné pour l'annonce sélectionnée par exécution de la sélection d'annonces identifiée par adSelectionId. Un événement d'annonce est une occurrence arrive à une annonce associée à l'élément adSelectionId donné. Il n'y a aucune garantie que lorsque l'événement d'annonce sera signalé. Il est possible que les rapports sur les événements soient retardés et qu'ils ne soient par lot.

Le service récupère reportingUri à l'aide de ReportEventRequest#getKey(). enregistré dans registerAdBeacon. Consultez la documentation de reportImpression(ReportImpressionRequest, Executor, OutcomeReceiver) pour en savoir plus sur registerAdBeacon. Ensuite, le service associe ReportEventRequest#getData() au corps d'une requête POST. envoyer la requête. Le corps de la requête POST aura la content-type de text/plain, et les données seront transmises dans charset=UTF-8.

La sortie est transmise par le récepteur, qui renvoie un Object vide pour une ou une exécution réussie, ou Exception inclut le type de l'exception générée et le message d'erreur correspondant.

Si l'exception IllegalArgumentException est générée, cela est dû à un argument d'entrée non valide. à l'API pour signaler l'événement d'annonce.

Si l'IllegalStateException est générée avec le message d'erreur "Failure of AdSelection" services.", cela est dû à une défaillance interne du service de sélection d'annonces.

Si l'exception LimitExceededException est générée, cela se produit lorsque le package appelant dépasse les limites de débit autorisées et est limité.

Si l'exception SecurityException est générée, cela se produit lorsque l'appelant n'est pas autorisé. ou si l'autorisation n'est pas demandée.

Les événements seront consignés au maximum une fois dans la mesure du possible.
Nécessite AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

rapportImpression

public void reportImpression (ReportImpressionRequest request, 
                Executor executor, 
                OutcomeReceiver<Object, Exception> receiver)

Informe le service qu'une nouvelle impression doit être enregistrée pour l'annonce sélectionnée par exécution de la sélection d'annonces identifiée par adSelectionId. Il n'existe aucune garantie quant au moment est enregistrée. Il est possible que la création des rapports sur les impressions soit retardée par lot.

Pour calculer l'URL de rapport sur le vendeur gagnant, le service extrait le code JavaScript du vendeur logique de l'élément AdSelectionConfig#getDecisionLogicUri() trouvé à l'emplacement ReportImpressionRequest.getAdSelectionConfig(). Ensuite, le service exécute l'une des disponibles dans le code JS du vendeur, appelées reportResult, qui fournissent des signaux sur l'appareil ainsi que ReportImpressionRequest#getAdSelectionConfig() comme paramètres d'entrée.

Voici la définition de la fonction de 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 } }; }

Pour calculer l'URL de rapport de l'acheteur ayant remporté l'enchère, le service extrait l'URL Logique JavaScript récupérée via le CustomAudience.getBiddingLogicUri() de l'acheteur. Ensuite, le service exécute l'une des fonctions situées dans le code JS de l'acheteur, appelée reportWin, en fournissant signaux sur l'appareil, signals_for_buyer calculés par reportResult et de ReportImpressionRequest#getAdSelectionConfig() en tant que paramètres d'entrée.

Voici la définition de la fonction de reportWin:

function reportWin(ad_selection_signals, per_buyer_signals, signals_for_buyer, contextual_signals, custom_audience_reporting_signals) { return {'status': 0, 'results': {'reporting_url': reporting_url } }; }

En outre, les acheteurs et les vendeurs ont la possibilité de s'inscrire pour recevoir des rapports sur des les événements d'annonce. Pour ce faire, il peut appeler la fonction registerAdBeacon fournie par la plate-forme. dans reportWin et reportResult pour les acheteurs et les vendeurs, respectivement.

Voici la définition de la fonction de registerBeacon:

function registerAdBeacon(beacons), où beacons est un dictionnaire de chaîne à paires de chaînes

Pour chaque événement d'annonce pour lequel un acheteur/vendeur est intéressé par des rapports, il doit ajouter une paire event_key: event_reporting_uri au dictionnaire beacons, où event_key est un identifiant pour cet événement spécifique. Ce event_key doit correspondre ReportEventRequest#getKey() lorsque le SDK appelle reportEvent(ReportEventRequest, Executor, OutcomeReceiver). De plus, chaque event_reporting_uri doit s'analyser correctement en Uri. Ce correspondra à la Uri signalée lorsque le SDK appelle reportEvent(ReportEventRequest, Executor, OutcomeReceiver).

Lorsque l'acheteur/le vendeur a ajouté toutes les paires pour lesquelles il souhaite recevoir des événements, il peut invoquer registerAdBeacon(beacons), où beacons est le nom du dictionnaire auquel les paires ont été ajoutées.

registerAdBeacon génère une TypeError dans les situations suivantes:

1. registerAdBeacon est appelé plusieurs fois. Si cette erreur est détectée reportWin/reportResult, l'ensemble d'associations d'origine sera enregistré
2. registerAdBeacon ne comporte pas exactement 1 argument "dict".
3. Le contenu de l'argument 1 "dict" ne correspond pas à toutes les associations String: String.

La sortie est transmise par receiver, qui renvoie soit un Object vide. pour une exécution réussie, ou Exception inclut le type de l'exception générée et le message d'erreur correspondant.

Si l'exception IllegalArgumentException est générée, cela est dû à un argument d'entrée non valide. reçues par l'API pour signaler l'impression.

Si l'IllegalStateException est générée avec le message d'erreur "Failure of AdSelection" services.", cela est dû à une défaillance interne du service de sélection d'annonces.

Si l'exception LimitExceededException est générée, cela se produit lorsque le package appelant dépasse les limites de débit autorisées et est limité.

Si l'exception SecurityException est générée, cela se produit lorsque l'appelant n'est pas autorisé. ou si l'autorisation n'est pas demandée.

Dans la mesure du possible, les impressions ne sont pas comptabilisées plus d'une fois.
Nécessite AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

selectAds

public void selectAds (AdSelectionFromOutcomesConfig adSelectionFromOutcomesConfig, 
                Executor executor, 
                OutcomeReceiver<AdSelectionOutcome, Exception> receiver)

Sélectionne une annonce parmi les résultats de sélections d'annonces déjà diffusées.

L'entrée adSelectionFromOutcomesConfig est fournie par le SDK Ads, et l'objet AdSelectionFromOutcomesConfig est transféré via un appel de liaison. Pour cette raison, le la taille totale de ces objets est liée aux limites de l'IPC Android. En cas d'échec du transfert AdSelectionFromOutcomesConfig génère une TransactionTooLargeException.

La sortie est transmise par le récepteur, qui renvoie soit un AdSelectionOutcome. pour une exécution réussie, ou une Exception inclut le type de l'exception générée et le message d'erreur correspondant.

L'entrée adSelectionFromOutcomesConfig contient:

• Seller doit être un AdTechIdentifier enregistré. Sinon, IllegalStateException sera générée.
• List of ad selection ids doit exister et provenir d'appels selectAds(AdSelectionConfig, Executor, OutcomeReceiver) provenant de la même application. Sinon, IllegalArgumentException pour la validation des entrées déclenchera la diffusion de l'annonce ne respectant pas les règles de sélection.
• Selection logic URI qui peut suivre le protocole HTTPS ou le format prédéfini de sélection des annonces des schémas.

  Si l'URI suit le schéma HTTPS, l'hôte doit correspondre à seller. Sinon, une exception IllegalArgumentException est générée.

  Les URI prédéfinis permettent de remplacer une logique prédéfinie prédéfinie par une logique JavaScript pour selectOutcome. L'URI prédéfini pour ce point de terminaison doit suivre :

  • ad-selection-prebuilt://ad-selection-from-outcomes/<name>?<script-generation-parameters>

  Si un URI prédéfini non compatible est transmis ou si la fonctionnalité d'URI prédéfini est désactivée par la service, la commande IllegalArgumentException est générée.

  Consultez la liste des AdSelectionFromOutcomesConfig.Builder#setSelectionLogicUri pour en savoir plus <name> et <script-generation-parameters> obligatoire.

Si l'exception IllegalArgumentException est générée, cela est dû à un argument d'entrée non valide. reçues par l'API pour exécuter la sélection d'annonces.

Si l'IllegalStateException est générée avec le message d'erreur "Failure of AdSelection" services.", cela est dû à une défaillance interne du service de sélection d'annonces.

Si l'exception TimeoutException est générée, cela se produit lorsqu'un délai avant expiration est atteint. au cours du processus d'enchères, d'évaluation ou de sélection globale pour trouver l'annonce gagnante.

Si l'exception LimitExceededException est générée, cela se produit lorsque le package appelant dépasse les limites de débit autorisées et est limité.

Si l'exception SecurityException est générée, cela se produit lorsque l'appelant n'est pas autorisé. ou si l'autorisation n'est pas demandée.
Nécessite AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

selectAds

public void selectAds (AdSelectionConfig adSelectionConfig, 
                Executor executor, 
                OutcomeReceiver<AdSelectionOutcome, Exception> receiver)

Exécute le processus de sélection des annonces sur l'appareil afin de sélectionner une annonce de remarketing pour l'appelant. application.

L'entrée adSelectionConfig est fournie par le SDK Ads, et l'objet AdSelectionConfig est transféré via un appel de liaison. Pour cette raison, la taille totale de ces objets est liée aux limites d'IPC Android. En cas d'échec du transfert de AdSelectionConfig, une exception TransactionTooLargeException est générée.

L'entrée adSelectionConfig contient Decision Logic Uri qui pourrait suivre soit le schéma HTTPS, soit le schéma prédéfini Sélection d'annonces.

Si l'URI suit le schéma HTTPS, l'hôte doit correspondre à seller. Sinon, Une exception IllegalArgumentException est générée.

Les URI prédéfinis permettent de remplacer une logique prédéfinie prédéfinie par une logique JavaScript pour scoreAds. L'URI prédéfini pour ce point de terminaison doit suivre :

• ad-selection-prebuilt://ad-selection/<name>?<script-generation-parameters>

Si un URI prédéfini non compatible est transmis ou si la fonctionnalité d'URI prédéfini est désactivée par la service, la commande IllegalArgumentException est générée.

Consultez les AdSelectionConfig.Builder#setDecisionLogicUri pour connaître les <name> et les <script-generation-parameters> obligatoire.

La sortie est transmise par le récepteur, qui renvoie soit un AdSelectionOutcome. pour une exécution réussie, ou une Exception inclut le type de l'exception générée et le message d'erreur correspondant.

Si l'exception IllegalArgumentException est générée, cela est dû à un argument d'entrée non valide. reçues par l'API pour exécuter la sélection d'annonces.

Si l'IllegalStateException est générée avec le message d'erreur "Failure of AdSelection" services.", cela est dû à une défaillance interne du service de sélection d'annonces.

Si l'exception TimeoutException est générée, cela se produit lorsqu'un délai avant expiration est atteint. au cours du processus d'enchères, d'évaluation ou de sélection globale pour trouver l'annonce gagnante.

Si l'erreur LimitExceededException est générée, cela se produit lorsque le package appelant dépasse les limites de débit autorisées et est limité.

Si l'exception SecurityException est générée, cela se produit lorsque l'appelant n'est pas autorisé. ou si l'autorisation n'est pas demandée.
Nécessite AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE

updateAdCounterHistogram

public void updateAdCounterHistogram (UpdateAdCounterHistogramRequest updateAdCounterHistogramRequest, 
                Executor executor, 
                OutcomeReceiver<Object, Exception> outcomeReceiver)

Met à jour les histogrammes de compteur pour une annonce précédemment sélectionnée par un appel à selectAds(android.adservices.adselection.AdSelectionConfig, java.util.concurrent.Executor, android.os.OutcomeReceiver).

Les histogrammes de compteur sont utilisés lors de la sélection des annonces pour informer le filtrage de la limitation de la fréquence d'exposition sur les annonces candidates, dans lesquelles les annonces dont les limites du nombre d'expositions sont atteintes ou dépassées sont supprimées lors de la sélection des annonces.

Les histogrammes de compteur ne peuvent être mis à jour que pour les annonces spécifiées par le adSelectionId donné, renvoyé par un appel récent à la sélection d'annonces FLEDGE à partir de la même application appelante.

Un SecurityException est renvoyé via outcomeReceiver si:

1. L'application n'a pas déclaré les autorisations appropriées dans son fichier manifeste.
2. l'application ou l'entité identifiée par l'callerAdTechIdentifier ne sont pas autorisées pour utiliser l'API.

Un LimitExceededException est renvoyé via outcomeReceiver si l'appel dépasse la limitation d'API de l'application appelante.

Dans tous les autres cas d'échec, outcomeReceiver renvoie un Object vide. Notez que, pour protéger la confidentialité des utilisateurs, les erreurs internes ne sont pas renvoyées par le biais d'un une exception.
Nécessite AdServicesPermissions.ACCESS_ADSERVICES_CUSTOM_AUDIENCE