Guide du développeur de l'API Topics

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

Préparation

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 que votre application utilise l'API Topics, vous devez inclure une autorisation et créer une configuration de services publicitaires dans votre fichier manifeste :

<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 :

<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_signature_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 :

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

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 :

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")
    }
}

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

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() :

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

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.

Test

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

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.