Cette page a été traduite par l'API Cloud Translation.

Ajouté au niveau d'API 34
Également disponible dans Ad Services Extensions 4

Gestionnaire de sélection des annonces

public class AdSelectionManager
extends Object

java.lang.Object
↳	android.adservices.adselection.AdSelectionManager

AdSelection Manager fournit des API pour les SDK publicitaires et d'applications afin d'exécuter les processus de sélection des annonces, ainsi que générer des rapports sur les impressions.

Résumé

Méthodes publiques
`static AdSelectionManager`	`get(Context context)` Méthode par défaut permettant de créer une instance d'AdSelectionManager.
`void`	`getAdSelectionData(GetAdSelectionDataRequest request, Executor executor, OutcomeReceiver<GetAdSelectionDataOutcome, Exception> receiver)` Collecte des données d'audience personnalisées à partir de l'appareil.
`TestAdSelectionManager`	`getTestAdSelectionManager()`
`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.
`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`.
`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`.
`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.
`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.
`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)`.

Méthodes héritées

De la classe


        
          java.lang.Object

`Object`	`clone()` Crée et affiche une copie de cet objet.
`boolean`	`equals(Object obj)` Indique si un autre objet est "égal à" celui-ci.
`void`	`finalize()` Appelée par le récupérateur de mémoire sur un objet lorsque la récupération de mémoire détermine qu'il n'y a plus de référence à l'objet.
`final Class<?>`	`getClass()` Affiche la classe d'exécution de cet objet (`Object`).
`int`	`hashCode()` Affiche une valeur de code de hachage pour l'objet.
`final void`	`notify()` Active un seul thread en attente sur l'écran de cet objet.
`final void`	`notifyAll()` Active tous les threads en attente sur l'écran de cet objet.
`String`	`toString()` Renvoie une représentation de l'objet sous forme de chaîne.
`final void`	`wait(long timeoutMillis, int nanos)` Entraîne l'attente du thread actuel jusqu'à son activation, généralement via une notification ou une interruption, ou après qu'un certain délai s'est écoulé.
`final void`	`wait(long timeoutMillis)` Entraîne l'attente du thread actuel jusqu'à son activation, généralement via une notification ou une interruption, ou après qu'un certain délai s'est écoulé.
`final void`	`wait()` Entraîne l'attente du thread actuel jusqu'à son activation, généralement via une notification ou une interruption.

Méthodes publiques

get

Ajouté au niveau d'API 34
Également disponible dans la section Extensions de services publicitaires 6

public static AdSelectionManager get (Context context)

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

Paramètres
`context`	`Context`: `Context` à utiliser Cette valeur ne peut pas être `null`.

Renvoie
`AdSelectionManager`	Une instance `AdSelectionManager` Cette valeur ne peut pas être `null`.

getAdSelectionData

Ajoutée à Android UpsideDownCakePrivacySandbox

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

Paramètres
`request`	`GetAdSelectionDataRequest` : cette valeur ne peut pas être `null`.
`executor`	`Executor` : cette valeur ne peut pas être `null`. Les événements de rappel et d'écouteur sont envoyés via `Executor`, ce qui permet de contrôler facilement le thread qui est utilisé. Pour envoyer des événements via le thread principal de votre vous pouvez utiliser `Context.getMainExecutor()` Sinon, fournissez un `Executor` qui sera envoyé à un thread approprié.
`receiver`	`OutcomeReceiver` : cette valeur ne peut pas être `null`.

Gestionnaire de la sélection d'annonces getTest

Ajouté au niveau d'API 34
Également disponible dans Ad Services Extensions 4

public TestAdSelectionManager getTestAdSelectionManager ()

Renvoie
`TestAdSelectionManager`	Cette valeur ne peut pas être `null`.

persistAdSelectionResult

Ajoutée à Android UpsideDownCakePrivacySandbox

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

Paramètres
`request`	`PersistAdSelectionResultRequest` : cette valeur ne peut pas être `null`.
`executor`	`Executor` : cette valeur ne peut pas être `null`. Les événements de rappel et d'écouteur sont envoyés via `Executor`, ce qui permet de contrôler facilement le thread qui est utilisé. Pour envoyer des événements via le thread principal de votre vous pouvez utiliser `Context.getMainExecutor()` Sinon, fournissez un `Executor` qui sera envoyé à un thread approprié.
`receiver`	`OutcomeReceiver` : cette valeur ne peut pas être `null`.

reportEvent

Ajoutée à Android UpsideDownCakePrivacySandbox

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

Paramètres
`request`	`ReportEventRequest` : cette valeur ne peut pas être `null`.
`executor`	`Executor` : cette valeur ne peut pas être `null`.
`receiver`	`OutcomeReceiver` : cette valeur ne peut pas être `null`.

rapportImpression

Ajouté au niveau d'API 34
Également disponible dans Ad Services Extensions 4

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:

registerAdBeacon est appelé plusieurs fois. Si cette erreur est détectée reportWin/reportResult, l'ensemble d'associations d'origine sera enregistré
registerAdBeacon ne comporte pas exactement 1 argument "dict".
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

Paramètres
`request`	`ReportImpressionRequest` : cette valeur ne peut pas être `null`.
`executor`	`Executor` : cette valeur ne peut pas être `null`.
`receiver`	`OutcomeReceiver` : cette valeur ne peut pas être `null`.

selectAds

Ajoutée à Android UpsideDownCakePrivacySandbox

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.

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

Paramètres
`adSelectionFromOutcomesConfig`	`AdSelectionFromOutcomesConfig` : cette valeur ne peut pas être `null`.
`executor`	`Executor` : cette valeur ne peut pas être `null`. Les événements de rappel et d'écouteur sont envoyés via `Executor`, ce qui permet de contrôler facilement le thread qui est utilisé. Pour envoyer des événements via le thread principal de votre vous pouvez utiliser `Context.getMainExecutor()` Sinon, fournissez un `Executor` qui sera envoyé à un thread approprié.
`receiver`	`OutcomeReceiver` : cette valeur ne peut pas être `null`.

selectAds

Ajouté au niveau d'API 34

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.

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

Paramètres
`adSelectionConfig`	`AdSelectionConfig` : cette valeur ne peut pas être `null`.
`executor`	`Executor` : cette valeur ne peut pas être `null`. Les événements de rappel et d'écouteur sont envoyés via `Executor`, ce qui permet de contrôler facilement le thread qui est utilisé. Pour envoyer des événements via le thread principal de votre vous pouvez utiliser `Context.getMainExecutor()` Sinon, fournissez un `Executor` qui sera envoyé à un thread approprié.
`receiver`	`OutcomeReceiver` : cette valeur ne peut pas être `null`.

updateAdCounterHistogram

Ajoutée à Android UpsideDownCakePrivacySandbox

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:

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

Une IllegalStateException est renvoyée via outcomeReceiver si l'appel ne proviennent pas d'une application avec une activité de premier plan.

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

Paramètres
`updateAdCounterHistogramRequest`	`UpdateAdCounterHistogramRequest` : cette valeur ne peut pas être `null`.
`executor`	`Executor` : cette valeur ne peut pas être `null`. Les événements de rappel et d'écouteur sont envoyés via `Executor`, ce qui permet de contrôler facilement le thread qui est utilisé. Pour envoyer des événements via le thread principal de votre vous pouvez utiliser `Context.getMainExecutor()` Sinon, fournissez un `Executor` qui sera envoyé à un thread approprié.
`outcomeReceiver`	`OutcomeReceiver` : cette valeur ne peut pas être `null`.