Guide du développeur de l'API Topics

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

Lorsque vous lisez la documentation concernant la Privacy Sandbox sur Android, cliquez sur le bouton Preview développeur ou Bêta pour sélectionner la version du programme que vous utilisez, car les instructions peuvent varier.


Envoyer un commentaire

L'API Topics déduit des signaux précis relatifs aux centres d'intérêt sur l'appareil en fonction de l'utilisation de l'application. Ces signaux, appelés thèmes, sont partagés avec les annonceurs afin de faciliter les annonces ciblées par centres d'intérêt, sans suivre les utilisateurs individuels entre les applications. Pour en savoir plus sur l'API Topics, consultez la proposition de conception.

Important : Sélectionnez le bouton "Version des extensions du SDK" ou "Preview développeur" pour choisir la version du programme que vous utilisez, car les instructions peuvent varier.

Configuration

Utilisez la dernière version du SDK Android Privacy Sandbox pour obtenir la version la plus récente des API protégeant la confidentialité. Pour utiliser l'API Topics, vous devez inclure une autorisation et créer une configuration de service publicitaire pour votre application, comme indiqué ci-dessous :

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

Référencez une configuration de services publicitaires dans l'élément <application> de votre fichier manifeste :1

<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 liées aux services publicitaires et sur le contrôle des accès au SDK

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

Vous devez aussi activer l'accès à l'API Topics (désactivé par défaut) à l'aide de ces commandes adb.

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

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 (GetTopicsRequest getTopicsRequest, Executor executor,
    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. Pour initialiser les paramètres, créez des objets GetTopicsRequest, Executor et OutcomeReceiver pour le rappel. GetTopicsRequest transmet les informations nécessaires pour récupérer les données de l'API Topics. Executor vous permet de satisfaire à l'exigence selon laquelle getTopics() doit s'exécuter à partir du thread UI et où le rappel OutcomeReceiver doit gérer 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 = true
    val mTopicsRequestBuilder: GetTopicsRequest.Builder = GetTopicsRequest.Builder()
    mTopicsRequestBuilder.setAdsSdkName(baseContext.packageName)
    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());
    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");

    }
};

Demander un ensemble de thèmes

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);

L'appel ci-dessus 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 de l'environnement d'exécution de SDK 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 "epoch". 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 setprop debug.adservices.topics_epoch_job_period_ms 300000

Vous pouvez confirmer la valeur de topics_epoch_job_period_ms avec getprop :

adb shell getprop debug.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.

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. N'hésitez pas à nous signaler les problèmes que vous rencontrez et à partager vos idées pour améliorer la Privacy Sandbox sur Android.