Configuration

Cette page explique comment configurer votre application, votre jeu ou votre SDK pour utiliser l'API Play Integrity. Pour intégrer l'API, vous devez disposer d'un projet Google Cloud, qui est nécessaire pour commencer à envoyer des requêtes. Vous pouvez ensuite associer votre projet Google Cloud dans la Google Play Console (pour les applications) ou la Google Play SDK Console (pour les SDK). Vous devez associer votre projet pour accéder à des options de configuration, des fonctionnalités de test et des rapports d'API supplémentaires, et pour demander une augmentation de votre quota de requêtes quotidiennes.

Activer l'API Play Integrity

Chaque application ou SDK qui appelle l'API Play Integrity doit disposer d'un projet Google Cloud pour utiliser l'API et surveiller son utilisation. Il s'agit de la première étape obligatoire pour toutes les intégrations. Vous pouvez activer l'API Play Integrity dans la console Google Cloud ou passer directement à l'association de votre projet Cloud à Google Play. L'API Play Integrity sera alors activée pour vous.

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.

  1. Accédez à API et services.
  2. Sélectionnez Activer les API et les services.
  3. Recherchez l'API Play Integrity.
  4. Cliquez sur Activer.

Vous pouvez désormais intégrer l'API Play Integrity à votre application. Pour accéder aux fonctionnalités avancées et aux augmentations de quota, vous devez passer à l'étape d'association.

Associer à Google Play (recommandé)

Associez votre application ou votre SDK à Google Play en suivant ces instructions.

Pour les applications et les jeux sur Google Play

Les applications distribuées sur Google Play doivent associer leur projet Google Cloud dans la Google Play Console pour activer des fonctionnalités supplémentaires et demander un quota d'API quotidien plus élevé.

  1. Ouvrez la Google Play Console et sélectionnez votre application.
  2. Accédez à Tester et publier > Intégrité de l'appli.
  3. Sous API Play Integrity, cliquez sur Associer un projet Cloud.
  4. Sélectionnez le projet Google Cloud que vous prévoyez d'utiliser avec l'API Play Integrity. Si l'API Play Integrity n'est pas déjà activée pour le projet, elle le sera automatiquement lors de l'association.

Pour les fournisseurs de SDK sur la Play SDK Console

Les fournisseurs de SDK qui utilisent la Play SDK Console de Google peuvent associer leur projet Google Cloud pour attribuer l'utilisation de l'API au SDK plutôt qu'aux applications individuelles qui l'utilisent, activer des fonctionnalités supplémentaires et demander une augmentation du quota d'API quotidien. Notez que l'accès à la Google Play SDK Console est soumis à des critères d'éligibilité.

  1. Ouvrez la Google Play SDK Console et sélectionnez votre SDK.
  2. Accédez à Intégrité du SDK.
  3. Sous API Play Integrity, cliquez sur Associer un projet Cloud.
  4. Sélectionnez le projet Google Cloud que vous prévoyez d'utiliser avec l'API Play Integrity. Si l'API Play Integrity n'est pas déjà activée pour le projet, elle le sera automatiquement lors de l'association.

Comprendre les limites d'utilisation de l'API Play Integrity

Votre application ou votre SDK sont soumis à une limite quotidienne par défaut de 10 000 requêtes au total, associée au numéro de projet Cloud. Si vous prévoyez un volume plus élevé, vous pouvez demander une augmentation de quota.

Action Quota quotidien Notes
Demandes de jetons 10 000 Partagé entre les requêtes classiques et les préparations de jetons standards
Déchiffrement des jetons sur les serveurs Google 10 000 Partagé entre les requêtes classiques et standards

Augmenter le nombre maximal de requêtes par jour

L'augmentation du quota est soumise à des critères d'éligibilité. Les augmentations de quota s'appliquent à la fois à la génération de jetons côté client et aux appels de déchiffrement côté serveur. Le traitement des demandes peut prendre jusqu'à une semaine. Nous vous recommandons de surveiller votre utilisation de l'API Play Integrity dans la console Google Cloud et de définir des alertes de quota pour éviter toute interruption de service.

Même avec un quota plus élevé, continuez à limiter les requêtes classiques aux actions importantes et peu fréquentes afin de préserver la batterie et l'utilisation des données des utilisateurs.

Pour les applications et les jeux sur Google Play

Pour pouvoir bénéficier d'une augmentation de quota, votre application doit être disponible sur Google Play en plus de tout autre canal de distribution. Vous devez associer votre projet Google Cloud à votre application dans la Play Console. Les demandes de quota provenant de projets dissociés seront refusées.

Pour demander une augmentation :

  1. Associez le projet Google Cloud concerné dans la Play Console.
  2. Vérifiez que vous avez correctement implémenté la logique d'API, y compris les stratégies de nouvelle tentative appropriées.
  3. Envoyez le formulaire de demande de quota.

Pour les fournisseurs de SDK sur la Play SDK Console

Pour pouvoir bénéficier d'une augmentation de quota, votre SDK doit être revendiqué dans la console Google Play SDK et votre projet Cloud doit y être associé. L'accès à la Google Play SDK Console est soumis à des critères d'éligibilité.

Pour demander une augmentation :

  1. Associez votre projet Google Cloud dans la Google Play SDK Console.
  2. Remplissez le formulaire d'assistance de la Google Play SDK Console.

Dans la section des commentaires ouverts, décrivez votre cas d'utilisation, le type de requêtes API que vous effectuez (standard, classique ou les deux), la fréquence à laquelle vous effectuez des requêtes et le nombre maximal de requêtes par jour que vous souhaitez.

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.6.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 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 vous avez installé OpenUPM CLI, vous pouvez installer le registre OpenUPM avec 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 ciblé à la fenêtre Package Manager :

    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. Définissez le menu déroulant du champ "Étendue du gestionnaire" sur Mes registres.

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

Importer depuis GitHub

  1. Téléchargez la dernière version de .unitypackage depuis 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é), puis importez tous les éléments.

Unreal Engine

Les sections suivantes décrivent comment intégrer et configurer l'API Google Play Integrity pour les projets Unreal Engine.

Versions d'Unreal Engine compatibles

Le plug-in est compatible avec Unreal Engine 5.0 et toutes les versions ultérieures.

Configurer l'environnement de développement

  1. Téléchargez le plug-in Play Unreal Engine depuis le dépôt GitHub.

  2. Copiez le dossier GooglePlay dans le dossier Plugins de votre projet Unreal Engine.

  3. Ouvrez votre projet Unreal Engine et cliquez sur Edit → Plugins (Modifier → Modules complémentaires).

  4. Recherchez Google Play et cochez la case Activé.

  5. Redémarrez le projet de jeu et déclenchez une compilation.

  6. Ouvrez le fichier Build.cs de votre projet et ajoutez le module PlayIntegrity à PublicDependencyModuleNames :

    using UnrealBuildTool;

public class MyGame : ModuleRules
{
  public MyGame(ReadOnlyTargetRules Target) : base(Target)
  {
    // ...

    PublicDependencyModuleNames.Add("PlayIntegrity");

    // ...
  }
}

Natif

Suivez le guide de configuration native. Pour en savoir plus, consultez la documentation de référence sur l'API native de Play Integrity.

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 avez associé votre projet Cloud dans la Play Console ou la Play SDK Console, vous pouvez personnaliser la réponse de votre API pour inclure des informations supplémentaires.

Évaluations de l'intégrité 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'application est exécutée sur un appareil Android authentique et certifié. Sur Android 13 et versions ultérieures, il existe une preuve matérielle que le bootloader de l'appareil est verrouillé et que l'OS Android chargé est une image certifiée du fabricant de l'appareil.
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).
Informations sur le 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).

Google Play Jeux pour PC

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.

Évaluations de l'intégrité facultatives

Si vous avez associé votre projet Cloud dans la Play Console ou la Google Play SDK Console, vous pouvez choisir de recevoir des informations supplémentaires.

Pour apporter des modifications, accédez à la Play Console, puis à Tester et publier > Intégrité de l'application. À côté de l'API Play Integrity, cliquez sur Paramètres. Cliquez sur Modifier les réponses, apportez les modifications souhaitées et enregistrez-les.

Informations sur l'appareil

Les libellés d'appareil supplémentaires dans l'évaluation deviceIntegrity vous en disent plus sur l'environnement de l'appareil sur lequel l'application s'exécute. Un même appareil renvoie plusieurs libellés s'il répond aux critères de chacun d'eux. Vous pouvez utiliser ces libellés pour créer une stratégie d'application par niveaux. Par exemple, vous pouvez choisir de faire davantage confiance à un appareil qui renvoie trois libellés (MEETS_STRONG_INTEGRITY, MEETS_DEVICE_INTEGRITY et MEETS_BASIC_INTEGRITY) qu'à un appareil qui n'en renvoie qu'un (MEETS_BASIC_INTEGRITY).

Les attributs de l'appareil indiquent la version du SDK Android de l'OS Android sur l'appareil. À l'avenir, il pourra être étendu à d'autres attributs d'appareil.

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). Des niveaux d'activité élevés peuvent indiquer qu'un appareil est utilisé pour générer un nombre excessif de jetons à distribuer de manière abusive sur des appareils non vérifiés.

La récupération d'appareil vous permet de stocker des données personnalisées par appareil avec des appareils spécifiques. Vous pouvez les récupérer de manière fiable lorsque votre application est réinstallée ultérieurement sur le même appareil.

Une fois que vous avez accepté de recevoir des informations facultatives, la réponse de l'API inclut de nouveaux champs et de nouvelles réponses dans l'évaluation :

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. Le bootloader de l'appareil peut être verrouillé ou déverrouillé, et l'état du démarrage peut être validé ou non. Il est possible que l'appareil ne soit pas certifié. Dans ce cas, Google ne peut fournir aucune garantie concernant la sécurité, la confidentialité ou la compatibilité des applications. Sur Android 13 et versions ultérieures, le verdict MEETS_BASIC_INTEGRITY exige que la racine de confiance de l'attestation soit fournie par Google.
MEETS_STRONG_INTEGRITY L'application est exécutée sur un appareil Android authentique et certifié, doté d'une mise à jour de sécurité récente.
  • Sur Android 13 et versions ultérieures, le verdict MEETS_STRONG_INTEGRITY nécessite MEETS_DEVICE_INTEGRITY et des mises à jour de sécurité au cours de la dernière année pour toutes les partitions de l'appareil, y compris un correctif de partition de l'OS Android et un correctif de partition du fournisseur.
  • Sur Android 12 et versions antérieures, le verdict MEETS_STRONG_INTEGRITY ne nécessite qu'une preuve matérielle de l'intégrité du démarrage et n'exige pas que l'appareil dispose d'une mise à jour de sécurité récente. Par conséquent, lorsque vous utilisez MEETS_STRONG_INTEGRITY, il est recommandé de tenir compte également de la version du SDK Android dans le champ deviceAttributes.
Attributs de l'appareil sdkVersion: 19, 20, ..., 36 Version du SDK de l'OS Android exécutée 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. Le champ deviceAttributes est donc vide. Cela peut être dû à l'une des raisons suivantes :
  • L'appareil n'est pas suffisamment fiable.
  • L'appareil a rencontré des problèmes techniques.
Nombre de requêtes de jetons d'intégrité standards de l'API sur cet appareil au cours de la dernière heure par application Nombre de requêtes de jetons d'intégrité de l'API classique sur cet appareil au cours de la dernière heure par application
Activité récente de l'appareil LEVEL_1 (le plus bas) 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 se produire pour les 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 a rencontré des problèmes techniques.
Rappel d'appareil values: bitFirst, bitSecond, bitThird Il s'agit des valeurs de bits que vous avez définies par le passé pour l'appareil spécifique. Vous décidez de la signification de chaque bit. Les trois valeurs de bit sont définies sur "false" par défaut.
writeDates: yyyymmFirst, yyyymmSecond, yyyymmThird Il s'agit des dates d'écriture des valeurs de bit en UTC, précises à l'année et au mois près. La date d'écriture d'un bit de rappel est mise à jour chaque fois que le bit est défini sur "true" et supprimée lorsqu'il est défini sur "false".

Détails de l'environnement

Le risque d'accès à l'application vous indique si d'autres applications en cours d'exécution peuvent être utilisées pour capturer l'écran, afficher des superpositions ou contrôler l'appareil. Les services d'accessibilité vérifiés connus de Google Play sont automatiquement exclus de cette évaluation.

L'évaluation Play Protect vous indique si Google 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 des informations facultatives, la réponse de l'API inclut de nouveaux champs et de nouvelles réponses 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 et 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 calques 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 (non 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 (non 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 sont en cours d'exécution (non installées par Play ni préchargées sur l'appareil) 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 ni un appareil 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 la bibliothèque de l'API Play Integrity qui ne prend pas encore en charge 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.

Par défaut, Google Play gère le chiffrement des réponses, ce qui signifie que votre backend appelle le serveur de Google pour déchiffrer les verdicts. Vous pouvez également gérer vous-même les clés pour déchiffrer les données en local dans votre environnement de serveur sécurisé.

Laisser Google gérer le chiffrement des réponses (recommandé)

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

Gérer vos propres clés de chiffrement

Pour déchiffrer localement dans votre propre environnement de serveur sécurisé, vous pouvez télécharger des clés de chiffrement depuis la Play Console ou la Play SDK Console. Pour utiliser cette fonctionnalité, votre application doit être disponible sur Google Play.

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 gérées par Google et les clés gérées par vous-même

  1. Ouvrez la Play Console et sélectionnez votre application .
  2. Accédez à Tester et publier > Intégrité de l'application.
  3. À côté de l'option API Play Integrity, cliquez sur Paramètres.
  4. Sous Requêtes classiques, à côté de Chiffrement de réponse, cliquez sur Modifier.

Pour passer aux clés autogérées :

  1. Sélectionnez Gérer et télécharger mes clés de chiffrement de réponse, puis importez votre clé publique.
  2. Cliquez sur Enregistrer pour télécharger automatiquement vos clés chiffrées.
  3. Mettez à jour votre serveur backend sécurisé pour déchiffrer les réponses en local à l'aide de ces clés.

Pour passer aux clés gérées par Google :

  1. Sélectionnez Laisser Google gérer mon chiffrement de réponse (recommandé).
  2. Cliquez sur Enregistrer les modifications.
Précédent
Aperçu
Suivant
Envoyer une requête normale