Implémenter l'API Topics sur Android

Configuration

Pour implémenter l'API Topics, vous devez d'abord configurer votre environnement de développement. Pour ce faire, procédez comme suit:

  1. Utilisez le dernier SDK Android Privacy Sandbox pour obtenir la version la plus récente des API protégeant la confidentialité.

  2. Ajoutez les éléments suivants à votre fichier manifeste:

    • Autorisation:incluez l'autorisation ACCESS_ADSERVICES_TOPICS pour autoriser votre application à accéder à l'API Topics:

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

    • Configuration des services publicitaires:référencez un fichier de configuration des 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" />

      Spécifiez la ressource XML des services publicitaires référencée dans le fichier manifeste, telle que res/xml/ad_services_config.xml. Utilisez l'attribut allowAllToAccess pour accorder l'accès à tous les SDK, ou l'attribut allowSdksToAccess pour accorder l'accès à des SDK individuels. En savoir plus sur les autorisations des services publicitaires et le contrôle des accès au SDK

      <ad-services-config>
    <topics allowAllToAccess="true"/>
</ad-services-config>

  3. Inscrivez votre technologie publicitaire à la Privacy Sandbox pour appeler l'API Topics dans votre SDK. Pour effectuer des tests en local, vous pouvez désactiver la vérification de l'inscription à Topics à l'aide des commandes suivantes:

    adb shell setprop debug.adservices.disable_topics_enrollment_check true

  4. Activez l'accès à l'API Topics. Par défaut, l'API Topics est désactivée. Vous devez l'activer à l'aide de commandes ADB:

    adb shell device_config put adservices ppapi_app_signature_allow_list \"\*\"
    adb shell setprop debug.adservices.disable_topics_enrollment_check true

  5. Commencez votre implémentation en dupliquant la version Java ou Kotlin de l'application exemple pour vous familiariser avec la récupération des thèmes sur un appareil.

Demander un ensemble de thèmes

La fonctionnalité principale de l'API Topics réside dans la méthode getTopics() au sein de l'objet TopicsManager, comme illustré dans cet exemple:

Kotlin 

fun getTopics(
        getTopicsRequest: GetTopicsRequest,
        executor: Executor,
        callback: OutcomeReceiver<GetTopicsResponse, Exception>
    ) { }

Java 

public void getTopics (@NonNull GetTopicsRequest getTopicsRequest,
    @NonNull Executor executor,
    @NonNull OutcomeReceiver<GetTopicsResponse, Exception> callback)

Pour utiliser cette méthode, initialisez l'objet TopicsManager et les paramètres nécessaires afin de recevoir les données des thèmes. GetTopicsRequest transmet les informations nécessaires pour récupérer les données de l'API Topics, y compris un indicateur permettant d'indiquer si l'appelant agira en tant qu'observateur ou non. Si vous n'agissez pas en tant qu'observateur, l'appel getTopics renvoie un sujet de l'epoch précédente, mais n'a pas d'incidence sur les données des thèmes de l'epoch suivante. Le rappel OutcomeReceiver gère le résultat de manière asynchrone. Exemple :

Kotlin 

private fun topicGetter() {
    val mContext = baseContext
    val mTopicsManager = mContext.getSystemService(TopicsManager::class.java)
    val mExecutor: Executor = Executors.newCachedThreadPool()
    val shouldRecordObservation = false
    val mTopicsRequestBuilder: GetTopicsRequest.Builder = GetTopicsRequest.Builder()
    mTopicsRequestBuilder.setAdsSdkName(baseContext.packageName)
    mTopicsRequestBuilder.setShouldRecordObservation(shouldRecordObservation)
    mTopicsManager.getTopics(mTopicsRequestBuilder.build(), mExecutor,
        mCallback as OutcomeReceiver<GetTopicsResponse, Exception>)
}
private var mCallback: OutcomeReceiver<GetTopicsResponse, java.lang.Exception> =
object : OutcomeReceiver<GetTopicsResponse, java.lang.Exception> {
    override fun onResult(result: GetTopicsResponse) {
        // handle successful result
        val topicsResult = result.topics
        for (i in topicsResult.indices) {
            Log.i("Topic", topicsResult[i].getTopicId().toString())
        }
        if (topicsResult.size == 0) {
            Log.i("Topic", "Returned Empty")
        }
    }
    override fun onError(error: java.lang.Exception) {
        // handle error
        Log.i("Topic", "Error, did not return successfully")
    }
}

Java 

public void TopicGetter() {
    @NonNull Context mContext = getBaseContext();
    TopicsManager mTopicsManager = mContext.getSystemService(TopicsManager.class);
    Executor mExecutor = Executors.newCachedThreadPool();
    boolean shouldRecordObservation = false;
    GetTopicsRequest.Builder mTopicsRequestBuilder = new GetTopicsRequest.Builder();
    mTopicsRequestBuilder.setAdsSdkName(getBaseContext().getPackageName());
    mTopicsRequestBuilder.setShouldRecordObservation(shouldRecordObservation);
    mTopicsManager.getTopics(mTopicsRequestBuilder.build(), mExecutor, mCallback);
}
OutcomeReceiver mCallback = new OutcomeReceiver<GetTopicsResponse, Exception>() {
    @Override
    public void onResult(@NonNull GetTopicsResponse result) {
        //Handle Successful Result
        List<Topic> topicsResult = result.getTopics();
        for (int i = 0; i < topicsResult.size(); i++) {
            Log.i("Topic", topicsResult.get(i).getTopicId().toString());
        }
        if (topicsResult.size() == 0) {
            Log.i("Topic", "Returned Empty");
        }
    }
    @Override
    public void onError(@NonNull Exception error) {
        // Handle error
        Log.i("Topic", "Experienced an error, and did not return successfully");
    }
};

Une fois la configuration prête, vous pouvez passer un appel pour recevoir un objet GetTopicsResponse en réponse à la méthode getTopics():

Kotlin 

mTopicsManager.getTopics(mTopicsRequestBuilder.build(), mExecutor,
        mCallback as OutcomeReceiver<GetTopicsResponse, java.lang.Exception>)

Java 

mTopicsManager.getTopics(mTopicsRequestBuilder.build(), mExecutor, mCallback);

Cette invocation fournit une liste d'objets Topics contenant des valeurs d'ID correspondant aux thèmes de la taxonomie Open Source qui sont pertinents pour l'utilisateur, ou renvoie une erreur explicite. Les thèmes se présentent comme suit :

/Internet & Telecom/Text & Instant Messaging

Reportez-vous à la taxonomie pour obtenir la liste des thèmes possibles qui peuvent être renvoyés. Cette taxonomie est Open Source. Vous pouvez soumettre des suggestions de modifications à l'aide du bouton de commentaires situé en haut de cette page.

Tests

L'API Topics fournit des thèmes pertinents et récents en fonction de l'utilisation de l'application. Cette version préliminaire donne un aperçu des comportements de l'API. Nous améliorerons la qualité des thèmes dans les futures versions.

Pour une expérience optimale, nous vous recommandons un environnement de test avec plusieurs applications dans lesquelles vous appelez getTopics() pour voir comment les thèmes sont sélectionnés. Pour vous aider à faire vos premiers pas, le dépôt des API de protection de la confidentialité et du SDK Runtime sur GitHub contient un ensemble de projets Android Studio individuels, y compris des exemples qui montrent comment initialiser et appeler l'API Topics.

Le calcul des thèmes a lieu à la fin d'une époque. Par défaut, chaque epoch dure sept jours, mais vous pouvez modifier cet intervalle pour obtenir un résultat. La commande shell Android Debug Bridge suivante ramène la durée de l'epoch à cinq minutes :

adb shell device_config put adservices topics_epoch_job_period_ms 300000

Vous pouvez confirmer la valeur de topics_epoch_job_period_ms avec get :

adb shell device_config get adservices topics_epoch_job_period_ms

Pour déclencher manuellement le calcul de l'epoch, exécutez la commande suivante :

adb shell cmd jobscheduler run -f com.google.android.adservices.api 2

En plus de l'exemple d'application, un colab vous permet de tester différentes combinaisons d'informations sur l'application par rapport au classificateur de thèmes. Pour utiliser ce colab afin d'afficher les types de résultats que votre application est susceptible d'obtenir, appelez getTopics.

Informations de chiffrement

Avec l'introduction du chiffrement, les appels à GetTopics() génèrent désormais une réponse avec une liste d'objets EncryptedTopic. Le déchiffrement de ces résultats génère un objet au même format JSON que l'objet Topic précédent.

L'API Topics prend en charge l'implémentation ponctuelle du chiffrement hybride à clé publique (HPKE, Hybrid Public Key Encryption). L'appelant enregistré doit héberger une clé publique 32 bits sur le point de terminaison d'URL de chiffrement public fourni lors de l'enregistrement. Ces clés doivent être encodées en base64.

Les objets EncryptedTopic comportent trois champs. La liste des sujets renvoyés peut être obtenue à l'aide de la clé privée correspondante à la clé publique.

À des fins de développement, vous pouvez tester le chiffrement de l'API Topics en désactivant la vérification de l'enregistrement. Cela obligerait l'API à utiliser la clé publique de test pour chiffrer vos réponses. Vous pouvez déchiffrer les sujets chiffrés à l'aide de la clé privée correspondante.

Limites

Pour obtenir la liste des fonctionnalités en cours de développement pour l'API Topics, consultez les notes de version.

Signaler des bugs et des problèmes

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

Étapes suivantes

Découvrez comment les utilisateurs et les développeurs peuvent gérer et personnaliser l'API Topics en fonction de leurs préférences et de leurs besoins.
Découvrez le fonctionnement de Topics sur Android et les étapes principales du flux de l'API.

Voir aussi

Consultez nos ressources pour mieux comprendre l'API Topics sur Android.