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

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

Unity

Les sections suivantes décrivent comment intégrer et configurer l'API Google Play Integrity pour les projets Unity. Elles couvrent les versions Unity compatibles, les méthodes d'installation et la configuration de l'environnement.

Versions d'Unity compatibles

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

Configurer l'environnement de développement

OpenUPM-CLI

Si la CLI OpenUPM est installée, vous pouvez installer le Registre OpenUPM à l'aide de la commande suivante:

openupm add com.google.play.integrity

OpenUPM

  1. Ouvrez les paramètres du gestionnaire de paquets en sélectionnant l'option de menu Unity Edit > Project Settings > Package Manager (Modifier > Paramètres du projet > Gestionnaire de paquets).

  2. Ajoutez OpenUPM en tant que registre à portée à la fenêtre du Gestionnaire de paquets:

    Name: package.openupm.com
URL: https://package.openupm.com
Scopes: com.google.external-dependency-manager
  com.google.play.common
  com.google.play.core
  com.google.play.integrity

  3. Ouvrez le menu du gestionnaire de paquets en sélectionnant l'option de menu Unity Window > Package Manager (Fenêtre > Gestionnaire de paquets).

  4. Dans le menu déroulant de l'étendue du gestionnaire, sélectionnez Mes registres.

  5. Sélectionnez le package Google Play Integrity plug-in for Unity (Plug-in Google Play Integrity pour Unity) dans la liste des packages, puis appuyez sur Install (Installer).

Importer depuis GitHub

  1. Téléchargez la dernière version de .unitypackage sur GitHub.

  2. Importez le fichier .unitypackage en sélectionnant l'option de menu Unity Assets > Import package > Custom Package (Éléments > Importer un package > Package personnalisé) et en important tous les éléments.

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 :
  • 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 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'application est exécutée sur un appareil qui réussit les contrôles d'intégrité de base du système. Pour les appareils Android 13 ou version ultérieure, elle nécessite l'attestation des clés de la plate-forme Android. 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é, un démarrage non validé 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. Pour les appareils Android 13 et versions ultérieures, une mise à jour de sécurité doit avoir été effectuée au cours de la dernière année. 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 :
  • L'appareil n'est pas suffisamment fiable.
  • La version de votre application installée sur l'appareil est inconnue de Google Play.
  • L'appareil rencontre des problèmes techniques.
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 :
  • L'appareil n'est pas suffisamment fiable.
  • La version de votre application installée sur l'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. 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 (qui ne sont pas 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 :
  • L'appareil n'est pas suffisamment fiable.
  • Le facteur de forme de l'appareil n'est pas un téléphone, une tablette ou un pliable.
  • L'appareil n'est pas équipé d'Android 6 (niveau d'API 23) ou version ultérieure.
  • La version de votre application installée sur l'appareil est inconnue de Google Play.
  • La version du Google Play Store installée sur l'appareil est obsolète.
  • Jeux uniquement : Le compte utilisateur ne dispose pas d'une licence Play pour le jeu.
  • Une requête standard a été utilisée avec le paramètre verdictOptOut.
  • Une requête standard a été utilisée avec une version de bibliothèque de l'API Play Integrity qui n'est pas encore compatible avec le risque d'accès à l'application pour les requêtes standards.
É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.
Précédent
Aperçu
Suivant
Envoyer une requête normale