Configurer AdServices pour Android

Suivez les instructions ci-dessous pour déclarer des autorisations spécifiques à l'API et configurer l'accès du SDK aux ressources gérées par l'API ciblée.

Déclarer des autorisations spécifiques à l'API AdServices

L'accès à chaque PPAPI nécessite une autorisation normal des services publicitaires. Dans le fichier manifeste, déclarez les autorisations d'accès appropriées qui correspondent aux API nécessaires à votre application ou à votre SDK.

API Attribution Reporting :

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

API Attribution Reporting (avec rapports de débogage) :

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

API Protected Audience/Custom Audience :

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

API Topics :

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

Si vous souhaitez recevoir des rapports de débogage avec l'API Attribution Reporting, incluez l'autorisation AD_ID:

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

Si votre projet dépend de modules ou de SDK, il est possible qu'ils déclarent déjà les autorisations requises des services publicitaires dans leurs fichiers manifestes. Par défaut, la compilation Gradle fusionne tous les fichiers manifestes en un seul fichier manifeste empaqueté dans votre application. Utilisez la vue Merged Manifest (Fichier manifeste fusionné) pour vérifier que les autorisations appropriées sont utilisées.

Si vous souhaitez empêcher la fusion d'autorisations dans votre application via des dépendances telles que les SDK, incluez le repère de nœud remove pour les autorisations concernées. L'exemple suivant montre comment empêcher la fusion de l'autorisation Topics.

<uses-permission android:name="android.permission.ACCESS_ADSERVICES_TOPICS"
    tools:node="remove" />

Configurer des services publicitaires spécifiques aux API

Comme pour les autorisations d'accès PPAPI, chaque API possède une entrée correspondante dans la configuration des services publicitaires. Cette configuration vous permet de contrôler précisément l'accès aux ressources gérées par les API de votre application ou du SDK intégré. Dans le fichier manifeste, spécifiez une propriété adservicesConfig comme indiqué dans l'exemple suivant :

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

      ...
</application>

Spécifiez la ressource XML des services publicitaires référencée dans le fichier manifeste, telle que res/xml/ad_services_config.xml. Pour chaque API protégeant la confidentialité applicable à votre application (ou SDK intégré), définissez l'attribut allowAllToAccess sur true pour accorder l'accès à tous les appelants.

Vous pouvez également utiliser l'attribut allowAdPartnersToAccess pour accorder un accès précis aux API pour chaque technologie publicitaire. Vous devrez fournir la liste des ID de compte d'enregistrement des développeurs obtenus via l'enregistrement. Si l'attribut allowAllToAccess est défini sur true, il est prioritaire sur tous les ID de compte d'enregistrement spécifiés dans l'attribut allowAdPartnersToAccess.

Les plates-formes de technologie publicitaire doivent également s'assurer que les clients d'applications accordent correctement l'accès aux API de protection de la confidentialité requises dans la configuration des services publicitaires.

L'exemple suivant montre comment spécifier un accès étendu pour autoriser tout ID de compte d'enregistrement à accéder à toutes les API protégeant la confidentialité:

<ad-services-config>
   <!-- Attribution API -->
   <attribution allowAllToAccess="true" />

   <!-- Topics API -->
   <topics allowAllToAccess="true" />

   <!-- Protected Audience on Android API -->
   <custom-audiences allowAllToAccess="true" />
</ad-services-config>

L'exemple suivant montre comment accorder un accès précis pour chaque API protégeant la confidentialité à des ID de compte d'enregistrement spécifiques :

<ad-services-config>
    <!-- Attribution API -->
    <attribution allowAdPartnersToAccess="ENROLLMENT-ID" allowAllToAccess="false" />

    <!-- Topics API -->
    <includes-sdk-library name="ENROLLMENT-ID" />
    <topics allowAdPartnersToAccess="ENROLLMENT-ID" allowAllToAccess="false" />

    <!-- Protected Audience on Android API -->
    <custom-audiences allowAdPartnersToAccess="ENROLLMENT-ID" allowAllToAccess="false" />
</ad-services-config>

Déclarer les dépendances à la bibliothèque Jetpack

Utilisez la version 1.0.0-beta01 ou une version ultérieure de la bibliothèque Jetpack ads-adservices pour intégrer les API de la Privacy Sandbox protégeant la confidentialité. Vous pouvez utiliser cette bibliothèque pour épargner à votre application les détails au niveau de la plate-forme et simplifier l'intégration avec les API protégeant la confidentialité.

  1. Ajoutez un dépôt Maven à votre projet.
  2. Déclarez les dépendances à la bibliothèque Jetpack ads-adservices dans le fichier build.gradle de votre application ou module.
  3. Utilisez les API des packages androidx.privacysandbox.ads.adservices.*.
  4. La bibliothèque Jetpack ads-adservices offre une compatibilité intégrée avec la coroutine Kotlin. Vous devrez peut-être intégrer les dépendances du cycle de vie appropriées pour votre projet afin de gérer les champs d'application des coroutines.

Vérifier la disponibilité de la version des extensions AdServices

Si vous utilisez la bibliothèque Jetpack ads-services pour l'intégration à des API protégeant la confidentialité, elle vérifie la disponibilité des API demandées dans la fonction obtain(). La fonction renvoie une valeur nulle si l'API demandée n'est pas disponible sur l'appareil. L'exemple suivant montre comment initialiser TopicsManager pour l'API Topics. L'accès aux autres API protégeant la confidentialité fonctionne de manière similaire.

Kotlin 

import androidx.privacysandbox.ads.adservices.topics.TopicsManager

// The initialization function will return null if the requested
// functionality is not available on the device.
val topicsManager = TopicsManager.obtain(context)

Java 

import androidx.privacysandbox.ads.adservices.topics.TopicsManager;

// The initialization function will return null if the requested
// functionality is not available on the device.
TopicsManager topicsManager = TopicsManager.obtain(context);

Si vous utilisez directement les API AdServices de l'extension du SDK, vérifiez la version des extensions AdServices incluant les API AdServices que vous souhaitez utiliser. Dans la documentation de référence de l'API, vous pouvez identifier la version dans laquelle une API AdServices particulière est introduite. Par exemple, la référence de l'API pour la classe TopicsManager indique "Added in Ad Services Extensions 4" (ajoutée dans l'extension AdServices 4). Utilisez les vérifications conditionnelles suivantes pour valider les extensions du SDK contenant les API AdServices.

Kotlin 

import android.os.ext.SdkExtensions

if (SDK_INT >= Build.VERSION_CODES.R && // The extensions API is available since R.
   SdkExtensions.getExtensionVersion(SdkExtensions.AD_SERVICES) >= 4) {

    // AdServices API is available.
...
}

Java 

import android.os.ext.SdkExtensions;

if (SDK_INT >= Build.VERSION_CODES.R && // The extensions API is available since R.
   SdkExtensions.getExtensionVersion(SdkExtensions.AD_SERVICES) >= 4) {

    // AdServices API is available.
...
}

Restriction d'accès au premier plan

Pour plus de transparence, l'accès au SDK Runtime et aux API protégeant la confidentialité est limité aux applications ayant une activité visible ou avec un RunningAppProcessInfo défini sur IMPORTANCE_FOREGROUND.