Configuration

Cette page explique comment configurer votre application ou votre jeu pour utiliser l'API Play Integrity. Vous devez activer les réponses de l'API, puis intégrer celle-ci dans votre application et dans son serveur backend. Des options de configuration, des fonctionnalités de test et des rapports supplémentaires deviennent disponibles une fois que vous associez le projet Google Cloud que vous utilisez pour l'API Play Integrity dans la Google Play Console.

Activer les réponses de l'API Play Integrity

Chaque application ou SDK qui appelle l'API Play Integrity doit utiliser un projet Google Cloud pour surveiller l'utilisation de l'API. Les applications sur Google Play peuvent associer un projet Cloud dans la Google Play Console pour activer les réponses de l'API Play Integrity. Si vous souhaitez créer un projet Cloud ou que votre application est distribuée exclusivement en dehors de Google Play, vous pouvez activer les réponses de l'API Play Integrity à partir de la console Google Cloud.

Configuration dans la Google Play Console (recommandée)

En activant les réponses de l'API Play Integrity dans la Google Play Console, vous avez accès à des options de configuration, des fonctionnalités de test et des rapports d'API supplémentaires. Cette option n'est disponible que pour les applications distribuées sur Google Play. Accédez à Publier > Intégrité de l'application. Sous API Play Integrity, sélectionnez Associer un projet Cloud. Sélectionnez le projet Cloud que vous souhaitez associer à votre application afin d'activer les réponses de l'API Play Integrity. Vous pouvez désormais intégrer l'API Play Integrity à votre application.

Configuration dans la console Google Cloud

Dans la console Google Cloud, créez un projet Cloud ou sélectionnez un projet Cloud existant que vous souhaitez utiliser avec l'API Play Integrity. Accédez à API et services. Sélectionnez Activer les API et les services. Recherchez l'API Play Integrity, puis activez-la. Vous pouvez désormais intégrer l'API Play Integrity à votre application.

Instructions de configuration pour les fournisseurs de SDK

Les fournisseurs de SDK doivent utiliser leur propre projet Google Cloud pour appeler l'API Play Integrity, de sorte que son utilisation soit attribuée au SDK et non à des applis individuelles qui l'utilisent. Cela signifie que les applications qui utilisent votre SDK n'ont pas besoin de configurer individuellement l'API Play Integrity. Vos requêtes adressées à l'API Play Integrity sont automatiquement comptabilisées dans l'utilisation de l'API de votre SDK et non dans l'application.

Les développeurs de SDK disposent de deux options pour configurer l'API Play Integrity : la Google Play SDK Console ou la console Google Cloud.

Lorsque vous activez les réponses de l'API Play Integrity dans la Google Play SDK Console, vous avez accès à des options de configuration supplémentaires. Accédez à SDK integrity (Intégrité du SDK), puis cliquez sur Settings (Paramètres). Dans "Configuration du projet", sélectionnez Associer un projet Cloud. Sélectionnez le projet Cloud que vous souhaitez associer à votre SDK afin d'activer les réponses de l'API Play Integrity. Vous pouvez désormais intégrer l'API Play Integrity à votre SDK. Notez que l'accès à la Google Play SDK Console est soumis à des critères d'éligibilité.

Utiliser la console Google Cloud

Vous pouvez activer les réponses de l'API Play Integrity depuis la console Google Cloud. Dans la console Google Cloud, créez un projet Cloud ou sélectionnez un projet Cloud existant que vous souhaitez utiliser avec l'API Play Integrity. Accédez à API et services. Sélectionnez Activer les API et les services. Recherchez l'API Play Integrity, puis activez-la. Vous pouvez désormais intégrer l'API Play Integrity à votre SDK.

Augmenter le nombre quotidien de requêtes API Play Integrity de votre SDK

Les fournisseurs de SDK qui souhaitent augmenter leur nombre maximal de requêtes quotidiennes doivent remplir le formulaire de demande de quota. Dans la section des commentaires ouverts, indiquez que vous envoyez une requête SDK et incluez vos coordonnées Maven (groupId:artifactId) ou une URL vers votre SDK.

Augmenter le nombre quotidien de requêtes API Play Integrity

Votre application sera soumise à une limite de 10 000 requêtes par jour au maximum. Vous pouvez demander à augmenter ce nombre maximal si votre application doit gérer un plus grand nombre d'utilisateurs. Pour cela, suivez les instructions ci-dessous.

Augmenter le nombre maximal de requêtes par jour

Pour pouvoir bénéficier d'une augmentation du nombre maximal de requêtes par jour, votre application doit être disponible sur Google Play en plus de tout autre canal de distribution. Même avec une augmentation du nombre maximal de requêtes quotidiennes, nous vous conseillons de continuer à limiter les requêtes classiques par utilisateur aux actions importantes et peu fréquentes afin de préserver les données utilisateur et la batterie.

Pour demander une augmentation du nombre maximal de requêtes quotidiennes, procédez comme suit :

  1. Associez le projet Google Cloud que vous utilisez pour l'API Play Integrity dans la Play Console.
  2. Assurez-vous d'implémenter correctement la logique d'API, y compris la stratégie recommandée concernant les nouvelles tentatives.
  3. Demandez une augmentation de quota à l'aide de ce formulaire.

L'augmentation du quota de l'API Play Integrity peut prendre jusqu'à une semaine. Nous vous recommandons donc vivement de surveiller votre utilisation de cette API dans la Google Play Console ou dans la console Google Cloud, où vous pouvez également définir des alertes de quota pour éviter toute interruption de service.

Les augmentations de quota de requêtes classiques seront automatiquement appliquées à l'appel du client pour générer des jetons d'intégrité et à l'appel du serveur pour déchiffrer et vérifier les jetons d'intégrité. Les augmentations de quota de requêtes standards sont appliquées à l'appel du serveur pour déchiffrer et vérifier les jetons d'intégrité.

Intégrer l'API Play Integrity à votre application

Pour intégrer l'API Play Integrity à votre application ou à votre SDK, suivez l'une des méthodes ci-dessous, en fonction de votre environnement de développement :

Kotlin ou Java

La dernière bibliothèque Android pour l'API Play Integrity est disponible dans le dépôt Maven de Google. Ajoutez la dépendance suivante au fichier build.gradle de votre application :

implementation 'com.google.android.play:integrity:1.3.0'

Unity

Installez le plug-in Google Play Integrity for Unity version 1.3.0 ou ultérieure. Pour obtenir des instructions, consultez Installer les packages Google pour Unity.

  • Toutes les versions 2019.x, 2020.x et ultérieures sont compatibles.
  • Si vous utilisez Unity 2018.x, les versions 2018.4 et ultérieures sont compatibles.
  • Unity 2017.x et les versions antérieures ne sont pas compatibles.

Natif

Installez le SDK Play Core natif 1.13.1 ou version ultérieure. Pour déterminer comment procéder, consultez le guide de configuration d'un environnement de développement de Play Core natif.

Configurer les réponses de l'API (facultatif)

La réponse de l'API inclut les évaluations par défaut renvoyées dans chaque requête. Si vous configurez l'intégration de l'API Play Integrity dans la Play Console, vous pouvez personnaliser la réponse de votre API.

Réponses par défaut

Les évaluations d'intégrité suivantes sont renvoyées par défaut dans la réponse de l'API Play Integrity :

Champ de réponse Valeur Description
Intégrité de l'appareil MEETS_DEVICE_INTEGRITY L'appli est exécutée sur un appareil Android équipé des services Google Play. L'appareil a réussi les contrôles d'intégrité du système et respecte la configuration Android requise.
Vide (valeur vide) L'application est exécutée sur un appareil présentant des signes d'attaque (hook d'API, par exemple) ou un piratage du système (mode root, par exemple), ou elle n'est pas exécutée sur un appareil physique (un émulateur n'ayant pas réussi les contrôles d'intégrité de Google Play, par exemple).
Détails du compte LICENSED L'utilisateur est autorisé à accéder à l'application. En d'autres termes, il a installé ou acheté votre application sur Google Play. L'utilisateur conserve les droits d'accès de l'application après sa désinstallation. Le compte de l'utilisateur est donc toujours concédé sous licence s'il récupère la même application par la suite.
UNLICENSED L'utilisateur n'est pas autorisé à accéder à l'application. C'est par exemple le cas s'il télécharge votre application indépendamment ou sans passer par Google Play.
UNEVALUATED Les détails concernant la licence n'ont pas été examinés, car une condition requise n'a pas été respectée. Plusieurs raisons peuvent expliquer cette situation. Par exemple :
  • L'appareil n'est pas suffisamment fiable.
  • L'utilisateur n'est pas connecté à Google Play.
  • La version de votre application installée sur l'appareil est inconnue de Google Play.
Intégrité de l'application PLAY_RECOGNIZED L'application et le certificat correspondent aux versions distribuées par Google Play.
UNRECOGNIZED_VERSION Le nom du certificat ou du package ne correspond pas aux données dont Google Play dispose.
UNEVALUATED L'intégrité de l'application n'a pas été examinée. Une condition requise n'a pas été respectée (l'appareil n'est pas suffisamment fiable, par exemple).

Réponses conditionnelles

Si vous distribuez l'application sur Google Play Jeux pour PC, vous recevrez automatiquement un libellé supplémentaire dans l'évaluation de l'intégrité de l'appareil :

Champ de réponse Libellé Description
Intégrité de l'appareil MEETS_VIRTUAL_INTEGRITY L'application est exécutée sur un émulateur Android équipé des services Google Play. L'émulateur réussit les contrôles d'intégrité du système et respecte la configuration Android requise.

Réponses facultatives

Si vous avez configuré l'intégration de l'API Play Integrity dans la Play Console ou dans la Google Play SDK Console, vous pouvez choisir de recevoir des informations dans la réponse de votre API.

Pour modifier vos réponses d'API, accédez à la Play Console, puis à Publier > Intégrité de l'application. Sous Réponses, apportez les modifications souhaitées et enregistrez-les.

Informations facultatives provenant des appareils

Les applis et les SDK peuvent accepter des libellés supplémentaires dans l'évaluation de l'intégrité de l'appareil. Dès lors que vous avez accepté de recevoir des libellés supplémentaires, la réponse sur l'intégrité de l'appareil inclut plusieurs libellés pour le même appareil, à condition que chacun des critères applicables aux libellés soit respecté. Vous pouvez préparer votre serveur backend à adopter un comportement différent selon l'éventail de réponses possibles. Par exemple, un appareil qui renvoie trois libellés (MEETS_STRONG_INTEGRITY, MEETS_DEVICE_INTEGRITY et MEETS_BASIC_INTEGRITY) peut être considéré comme plus sûr qu'un appareil qui ne renvoie qu'un seul libellé (MEETS_BASIC_INTEGRITY). Les niveaux d'activité récente de l'appareil peuvent également être pris en compte, avec des niveaux allant de LEVEL_1 (faible nombre de requêtes) à LEVEL_4 (nombre élevé de requêtes). Par exemple, un appareil qui renvoie un niveau d'activité considérablement plus élevé que le niveau d'activité moyen de votre appli est susceptible de générer un grand nombre de jetons d'intégrité à distribuer sur des appareils non vérifiés. Le niveau UNEVALUATED signale des problèmes de sécurité ou des problèmes techniques potentiels.

Champ de réponse Libellé Description
Intégrité de l'appareil MEETS_BASIC_INTEGRITY L'appli est exécutée sur un appareil qui réussit les contrôles d'intégrité de base du système. Cet appareil ne respecte peut-être pas la configuration Android requise et n'est éventuellement pas autorisé à exécuter les services Google Play. Par exemple, il est possible que l'appareil exécute une version non reconnue d'Android, qu'il utilise un bootloader déverrouillé ou qu'il n'ait pas été certifié par le fabricant.
MEETS_STRONG_INTEGRITY L'application est exécutée sur un appareil Android équipé des services Google Play et offre une bonne garantie de l'intégrité du système, telle qu'une preuve matérielle de l'intégrité du démarrage. L'appareil a réussi les contrôles d'intégrité du système et respecte la configuration Android requise.
Activité récente de l'appareil (bêta) LEVEL_1 Niveau le plus bas : L'appli a demandé 10 jetons d'intégrité ou moins sur cet appareil au cours de la dernière heure.
LEVEL_2 L'appli a demandé entre 11 et 25 jetons d'intégrité sur cet appareil au cours de la dernière heure.
LEVEL_3 L'appli a demandé entre 26 et 50 jetons d'intégrité sur cet appareil au cours de la dernière heure.
LEVEL_4 Niveau le plus élevé : L'appli a demandé plus de 50 jetons d'intégrité sur cet appareil au cours de la dernière heure.
UNEVALUATED Le niveau d'activité récente de l'appareil n'a pas été évalué. Plusieurs raisons peuvent expliquer cette situation. Par exemple :
  • L'appareil n'est pas suffisamment fiable.
  • La version de l'appli installée sur votre appareil est inconnue de Google Play.
  • L'appareil rencontre des problèmes techniques.

Détails de l'environnement facultatifs

Les applications peuvent choisir de recevoir des évaluations supplémentaires sur l'environnement. Une fois que vous avez accepté de recevoir l'évaluation Play Protect, la réponse de l'API inclut le champ des détails de l'environnement dans l'évaluation.

Champ de réponse Valeur Description
Évaluation Play Protect NO_ISSUES Play Protect est activé et n'a détecté aucun problème d'application sur l'appareil.
NO_DATA Play Protect est activé, mais aucune analyse n'a encore été effectuée. L'appareil ou l'application Play Store ont peut-être été réinitialisés récemment.
POSSIBLE_RISK Play Protect est désactivé.
MEDIUM_RISK Play Protect est activé et a détecté des applications potentiellement dangereuses installées sur l'appareil.
HIGH_RISK Play Protect est activé et a détecté des applications dangereuses installées sur l'appareil.
UNEVALUATED L'évaluation Play Protect n'a pas été menée. Une condition requise n'a pas été respectée (l'appareil n'est pas suffisamment fiable, par exemple).

Configurer les paramètres des requêtes classiques (facultatif)

Ignorez cette section si vous prévoyez uniquement d'envoyer des requêtes API standards.

Lorsque vous effectuez des requêtes classiques, les serveurs de Google Play gèrent par défaut le chiffrement des réponses utilisé par votre application lorsque vous interagissez avec l'API Play Integrity. Bien que nous vous recommandions d'utiliser cette option par défaut, vous pouvez également choisir de gérer et de télécharger vos clés de chiffrement de réponse en suivant les instructions ci-dessous.

Laisser Google gérer le chiffrement des réponses (option par défaut recommandée)

Pour protéger la sécurité de votre application, nous vous recommandons d'autoriser Google à générer et à gérer vos clés de chiffrement de réponse. Votre serveur backend appellera le serveur Google Play pour déchiffrer les réponses.

Gérer et télécharger vos clés de chiffrement de réponse

Si vous souhaitez déchiffrer l'évaluation de l'intégrité en local dans votre propre environnement de serveur sécurisé, vous pouvez gérer et télécharger vos clés de chiffrement de réponse. Pour gérer et télécharger vos clés de chiffrement de réponse, vous devez utiliser la Play Console. Votre application doit aussi être disponible sur Google Play en plus de tous les autres canaux de distribution. Suivez les instructions ci-dessous pour passer de clés de chiffrement de réponse gérées par Google à des clés autogérées.

Veillez à ne pas déchiffrer ni vérifier le jeton reçu à partir de votre application cliente. Veillez également à ne jamais exposer de clés de déchiffrement à l'application cliente.

Avant de modifier votre stratégie de gestion du chiffrement des réponses dans la Play Console, assurez-vous que votre serveur est correctement configuré pour déchiffrer et vérifier les jetons d'intégrité sur les serveurs de Google Play afin d'éviter toute interruption.

Basculer entre les clés de chiffrement de réponse gérées par Google et les clés gérées par vous-même

Si Google gère actuellement le chiffrement des réponses et que vous souhaitez gérer et télécharger vos clés de chiffrement vous-même, procédez comme suit :

  1. Connectez-vous à la Play Console.
  2. Sélectionnez une application qui utilise l'API Play Integrity.
  3. Dans la section Publier du menu de gauche, accédez à Intégrité de l'application.
  4. À côté de l'option API Play Integrity, cliquez sur Paramètres.
  5. Dans la section Requêtes classiques de la page, cliquez sur Modifier à côté de l'option Chiffrement de réponse.
  6. Dans la fenêtre qui s'affiche, cliquez sur Gérer et télécharger mes clés de chiffrement de réponse.
  7. Suivez les instructions d'importation d'une clé publique.
  8. Une fois que la fenêtre indique que l'importation a réussi, cliquez sur Enregistrer pour télécharger automatiquement vos clés chiffrées.
  9. Modifiez la logique du serveur pour déchiffrer et vérifier les jetons d'intégrité en local, dans votre propre environnement de serveur sécurisé, à l'aide de vos clés de chiffrement de réponse.
  10. (Facultatif) Le fait que vous gériez et téléchargiez vous-même vos clés de chiffrement de réponse n'empêche pas votre application de faire appel aux serveurs Google Play pour déchiffrer et vérifier la réponse.

Si vous gérez vous-même vos clés de chiffrement de réponse et souhaitez que Google gère le chiffrement des réponses, procédez comme suit :

  1. Modifiez la logique du serveur de façon à ce que le déchiffrement et la vérification des réponses aient uniquement lieu sur les serveurs de Google.
  2. Connectez-vous à la Play Console.
  3. Sélectionnez une application qui utilise l'API Play Integrity.
  4. Dans la section Publier du menu de gauche, accédez à Intégrité de l'application.
  5. À côté de l'option API Play Integrity, cliquez sur Paramètres.
  6. Dans la section Requêtes classiques de la page, cliquez sur Modifier à côté de l'option Chiffrement de réponse.
  7. Dans la fenêtre qui s'affiche, cliquez sur Laisser Google gérer mon chiffrement de réponse (recommandé).
  8. Cliquez sur Enregistrer les modifications.