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.
Utiliser la Google Play SDK Console (recommandé)
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 à Intégrité du SDK, puis cliquez sur Paramètres. Sous "Project configuration" (Configuration du projet), sélectionnez Link a Cloud project (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 :
- Associez le projet Google Cloud que vous utilisez pour l'API Play Integrity dans la Play Console.
- Assurez-vous d'implémenter correctement la logique d'API, y compris la stratégie recommandée concernant les nouvelles tentatives.
- 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.4.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 Play | LICENSED |
L'utilisateur est autorisé à accéder à l'application. En d'autres termes, l'utilisateur a installé ou mis à jour votre application depuis Google Play sur son appareil. |
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 :
|
|
| 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 applications et les SDK peuvent accepter des libellés d'appareil 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 n'en renvoie qu'un (MEETS_BASIC_INTEGRITY).
Vous pouvez également activer l'activité récente de l'appareil. L'activité récente de l'appareil renvoie un niveau 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 peut tenter de générer un grand nombre de jetons d'intégrité à distribuer sur des appareils non vérifiés.
Vous pouvez également activer les attributs de l'appareil, qui indiquent la version du SDK Android de l'OS Android exécuté sur l'appareil. À l'avenir, il pourra être étendu à d'autres attributs d'appareil.
| 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. | ||
| Requêtes de jetons d'intégrité d'API standards sur cet appareil au cours de la dernière heure par application | Requêtes de jetons d'intégrité API classiques sur cet appareil au cours de la dernière heure par application | ||
| Activité récente de l'appareil | LEVEL_1 (la plus basse) |
10 ou moins | 5 ou moins |
LEVEL_2 |
Entre 11 et 25 | Entre 6 et 10 | |
LEVEL_3 |
Entre 26 et 50 | Entre 11 et 15 | |
LEVEL_4 (le plus élevé) |
Plus de 50 | Plus de 15 | |
UNEVALUATED |
L'activité récente de l'appareil n'a pas été évaluée. Cela peut être dû aux raisons suivantes :
|
||
| Attributs de l'appareil | sdkVersion: 19, 20, ..., 35 |
Version du SDK de l'OS Android exécuté sur l'appareil.
Le nombre renvoyé correspond à Build.VERSION_CODES. |
|
| Vide (valeur vide) | La version du SDK n'est pas évaluée, car une condition requise n'a pas été respectée. Dans ce cas, le champ sdkVersion n'est pas défini. Par conséquent, le champ deviceAttributes est vide.
Cela peut être dû aux raisons suivantes :
|
||
Détails de l'environnement facultatifs
Les applications peuvent choisir de recevoir des évaluations supplémentaires sur l'environnement. Le risque d'accès des applis vous indique si d'autres applications en cours d'exécution peuvent capturer l'écran, afficher des superpositions ou contrôler l'appareil. L'évaluation Play Protect vous indique si Play Protect est activé sur l'appareil et s'il a détecté un logiciel malveillant connu.
Une fois que vous avez accepté de recevoir ces évaluations, 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 du risque d'accès à l'application | KNOWN_INSTALLED |
Les applications sont installées par Google Play ou préchargées sur la partition système par le fabricant de l'appareil. |
KNOWN_CAPTURING |
Des applications installées par Google Play ou préchargées sur l'appareil sont en cours d'exécution et peuvent être utilisées pour lire ou capturer les entrées et les sorties de l'application à l'origine de la demande (par exemple, les applications d'enregistrement d'écran). | |
KNOWN_CONTROLLING |
Des applications installées par Google Play ou préchargées sur l'appareil sont en cours d'exécution et peuvent être utilisées pour contrôler l'appareil, ainsi que les entrées et sorties de l'application à l'origine de la demande (par exemple, les applications de commande à distance). | |
KNOWN_OVERLAYS |
Des applications installées par Google Play ou préchargées sur l'appareil sont en cours d'exécution et peuvent afficher des superpositions sur l'application à l'origine de la demande. | |
UNKNOWN_INSTALLED |
D'autres applications, qui n'ont pas été installées par Google Play ou qui ont été préchargées sur la partition système par le fabricant de l'appareil, sont installées. | |
UNKNOWN_CAPTURING |
D'autres applications en cours d'exécution (qui ne sont pas installées par Play ni préchargées sur l'appareil) peuvent être utilisées pour lire ou capturer les entrées et les sorties de l'application à l'origine de la demande (par exemple, les applications d'enregistrement d'écran). | |
UNKNOWN_CONTROLLING |
D'autres applications en cours d'exécution (qui ne sont pas installées par Play ni préchargées sur l'appareil) peuvent être utilisées pour contrôler l'appareil et les entrées et sorties de l'application à l'origine de la demande (par exemple, les applications de commande à distance). | |
UNKNOWN_OVERLAYS |
D'autres applications (non installées par Play ni préchargées sur l'appareil) sont en cours d'exécution et peuvent afficher des superpositions sur l'application à l'origine de la demande. | |
| Vide (valeur vide) | Le risque d'accès à l'application n'est pas examiné si une condition requise n'a pas été respectée. Dans ce cas, le champ appAccessRiskVerdict est vide. Plusieurs raisons peuvent expliquer cette situation. Par exemple :
|
|
| É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 :
- Connectez-vous à la Play Console.
- Sélectionnez une application qui utilise l'API Play Integrity.
- Dans la section Publier du menu de gauche, accédez à Intégrité de l'application.
- À côté de l'option API Play Integrity, cliquez sur Paramètres.
- Dans la section Requêtes classiques de la page, cliquez sur Modifier à côté de l'option Chiffrement de réponse.
- Dans la fenêtre qui s'affiche, cliquez sur Gérer et télécharger mes clés de chiffrement de réponse.
- Suivez les instructions d'importation d'une clé publique.
- 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.
- 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.
- (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 :
- 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.
- Connectez-vous à la Play Console.
- Sélectionnez une application qui utilise l'API Play Integrity.
- Dans la section Publier du menu de gauche, accédez à Intégrité de l'application.
- À côté de l'option API Play Integrity, cliquez sur Paramètres.
- Dans la section Requêtes classiques de la page, cliquez sur Modifier à côté de l'option Chiffrement de réponse.
- Dans la fenêtre qui s'affiche, cliquez sur Laisser Google gérer mon chiffrement de réponse (recommandé).
- Cliquez sur Enregistrer les modifications.