Google Play Integrity API en 2026 : un guide pas à pas
L’API Play Integrity répond à une question précise et concrète pour votre backend : cette requête provient-elle bien de la copie de mon application publiée par Google Play, sur un appareil qui est bien ce qu’il prétend être ? Votre serveur demande à Google un verdict d’intégrité, reçoit une charge utile signée et décide — côté serveur, jamais côté client — du degré de confiance à accorder à l’interaction. C’est la méthode standard pour ralentir les builds altérés, les clients scriptés, les émulateurs et les copies installées en sideload avant qu’ils n’atteignent l’économie de votre jeu, vos droits d’abonnement ou vos revenus publicitaires.
Ce guide suit l’ordre dans lequel vous travaillerez réellement : activer l’API, lier un projet Cloud, choisir entre une requête standard et une requête classique, préchauffer le fournisseur de jetons, demander et déchiffrer un jeton, lire les champs de verdict, gérer les quotas et les codes d’erreur, et déployer l’application des règles sans bloquer les utilisateurs payants. Une règle traverse tout cela — l’API vous fournit des signaux pour vos propres décisions, et le seul moyen durable de passer un contrôle d’intégrité est de livrer une application authentique via le canal officiel.
1. Ce que l'API atteste, et ce qu'elle n'atteste pas
Trois familles de verdicts reviennent par défaut, et chacune répond à une question différente.
- appIntegrity — cela provient-il de votre binaire non modifié ?
appRecognitionVerdictrenvoiePLAY_RECOGNIZEDlorsque le package et le certificat correspondent à ce que distribue Google Play,UNRECOGNIZED_VERSIONlorsque le certificat ou le nom de package ne correspond pas aux registres Play, etUNEVALUATEDlorsqu’un prérequis a été manqué. - deviceIntegrity — l’appareil est-il authentique ? Par défaut,
deviceRecognitionVerdictpeut contenirMEETS_DEVICE_INTEGRITY: un appareil Android authentique et certifié, avec une preuve matérielle sur Android 13 et versions supérieures que le bootloader est verrouillé et que le logiciel chargé est authentique. Un appareil qui ne satisfait aucun label voit simplement le champ omis. - accountDetails — l’utilisateur détient-il un droit d’accès ? Le champ
appLicensingVerdictrenvoieLICENSED(installée ou mise à jour depuis Google Play),UNLICENSEDouUNEVALUATED.
Deux points de discipline comptent plus que la liste des champs. Premièrement, Google indique clairement que l’API fonctionne mieux en complément d’autres signaux, dans le cadre d’une stratégie globale de lutte contre les abus et non comme mécanisme unique — un verdict n’est qu’une donnée parmi d’autres, et le traiter comme le seul filtre produit à la fois des faux positifs et des contournements faciles. Deuxièmement, ce sont des signaux de risque, pas des jugements sur vos utilisateurs : un passionné sur un appareil rooté n’est pas un criminel, et la réponse doit être proportionnée à ce qui est réellement en jeu sur cet écran.
2. Étape 1 — activez l’API et liez un projet Cloud
Chaque application ou SDK qui appelle l’API a besoin d’un projet Google Cloud, car c’est là que l’usage est surveillé et le quota géré.
- Dans la Google Cloud Console, créez un nouveau projet ou choisissez-en un existant que vous souhaitez utiliser.
- Rendez-vous dans API et services → Activer les API et services, recherchez Play Integrity API et cliquez sur Activer.
- Ensuite, associez ce projet à votre application. Dans la Play Console, ouvrez votre application, allez dans Protected with Play, trouvez Play Integrity API et choisissez Get started.
La liaison est l’étape qui débloque tout le reste. Un projet activé dans Cloud mais non lié dans la Play Console — ou dans la Play SDK Console pour les SDK — n’est pas éligible aux options de configuration supplémentaires ni à une augmentation de quota. Le flux de liaison active l’API pour vous si vous avez sauté l’étape dans la console, donc l’un ou l’autre ordre fonctionne ; sauter la liaison, non.
Le déchiffrement nécessite un identifiant que votre application ne doit jamais embarquer. Créez un compte de service dans le projet Cloud lié et appelez le point de terminaison de décodage depuis votre serveur avec le scope playintegrity. Le client demande des jetons ; seul le serveur les ouvre.
3. Étape 2 — choisir une demande standard ou classique
Il existe deux styles de requête, et choisir le bon dès le départ évite une réécriture plus tard.
- Les requêtes standard sont le choix par défaut pour les applications sur Google Play. Elles fonctionnent sur Android 5.0 (niveau d’API 21) et versions supérieures, et reposent sur deux appels : préparer le fournisseur de jeton d’intégrité en amont, puis demander un jeton au moment où vous en avez réellement besoin.
- Les requêtes classiques existent pour les cas que les requêtes standard ne couvrent pas — notamment les applications distribuées exclusivement en dehors de Google Play, et les SDK. Structurellement, une requête classique est un appel unique qui prend un
nonceque vous générez, et les applications non distribuées sur Play doivent aussi transmettre leur numéro de projet Cloud avecsetCloudProjectNumber(). Les applications sur Play sont liées via la console et ne le définissent pas dans la requête.
Si votre application est sur Google Play, la solution standard s’impose. Optez pour la version classique uniquement si la distribution se fait réellement en dehors de Play, ou si une intégration spécifique vous y contraint.
4. Étape 3 — préchauffer le fournisseur, puis demander le jeton
Une requête standard est volontairement scindée en deux pour que la partie lente ne pèse jamais sur le chemin critique de l’utilisateur.
Préparez, ou préchauffez, le fournisseur de jeton d’intégrité. Appelez-le bien avant d’avoir besoin d’un verdict — généralement au lancement de l’application, ce qui fonctionne bien car l’appel est asynchrone et n’affecte pas le temps de démarrage. Le préchauffage permet à Google Play de mettre en cache des informations d’attestation partielles sur l’appareil afin que la requête ultérieure soit rapide ; une nouvelle préparation est aussi un moyen plus léger de rendre le prochain verdict plus actuel. Le fournisseur lui-même peut expirer s’il est conservé trop longtemps, ce qui se manifeste par INTEGRITY_TOKEN_PROVIDER_INVALID ; dans ce cas, demandez un nouveau fournisseur plutôt que de réessayer avec celui qui est périmé.
Demandez un jeton d’intégrité à la demande. Lorsque l’application effectue un appel serveur que vous souhaitez garantir, demandez un jeton et envoyez-le à votre backend. Joignez un hash de requête : calculez un condensé — par exemple SHA-256 des paramètres stables — et transmettez-le, car l’API renvoie cette valeur dans la réponse signée. Sans lui, un jeton est lié à l’appareil mais pas à la requête spécifique, ce qui est précisément la faille qu’un proxy exploite pour le réutiliser ailleurs.
Les requêtes classiques utilisent à la place un nonce que vous fournissez. Il est transmis tel quel à Google, donc n'y mettez jamais de données personnelles ou sensibles, et il doit être un Base64 valide d'une longueur acceptée — sinon vous récoltez NONCE_TOO_SHORT, NONCE_TOO_LONG ou NONCE_IS_NOT_BASE64 au lieu d'un verdict.
5. Étape 4 — déchiffrer et vérifier sur votre serveur
Le jeton qui atteint votre backend est chiffré et inutilisable tant que Google ne le déchiffre pas. Avec les identifiants de votre compte de service et la portée playintegrity, votre serveur appelle :
POST https://playintegrity.googleapis.com/v1/PACKAGE_NAME:decodeIntegrityToken { "integrity_token": "INTEGRITY_TOKEN" }
Ce qui revient est une charge utile JSON en texte brut. Avant de regarder le moindre verdict, validez les détails de la requête, car la charge utile n’a de sens que si c’est bien la réponse à votre requête :
requestPackageNamedoit correspondre à votre nom de package ;requestHashdoit être égal au hachage que vous avez envoyé ;timestampMillisdoit être récent — comparez-le à une fenêtre de fraîcheur (une fenêtre autorisée en millisecondes) et rejetez tout ce qui est plus ancien, car un jeton périmé est un candidat au rejeu.
Google Play applique également une protection automatique contre la relecture, empêchant la réutilisation d’un jeton d’intégrité de nombreuses fois. Considérez cela comme un filet de sécurité plutôt qu’un substitut à votre propre contrôle de fraîcheur, et décodez le jeton côté serveur au moment de l’action au lieu d’en mettre un en cache pour la journée.
6. Lire la charge utile sans surbloquer
La charge utile est du JSON contenant requestDetails, appIntegrity, deviceIntegrity, accountDetails et — une fois que vous avez activé l’option — environmentDetails. L’ordre des champs n’est pas garanti, lisez donc toujours par clé. Une échelle de décision exploitable ressemble à ceci.
- Confirmez d’abord l’application :
PLAY_RECOGNIZEDsignifie que le binaire et le certificat sont bien ceux distribués par Play. - Examinez ensuite l’appareil :
MEETS_DEVICE_INTEGRITYest le seuil par défaut. Les libellés supplémentaires —MEETS_BASIC_INTEGRITY,MEETS_STRONG_INTEGRITYetMEETS_VIRTUAL_INTEGRITY— sont facultatifs et relèvent d’une stratégie par paliers, pas d’une première version. - Utilisez
accountDetailslà où les droits d’accès comptent :UNLICENSEDsignifie que le compte ne dispose d’aucun droit Play, bien que sur certains appareils plus anciens un droit puisse persister après la désinstallation ; lisez-le donc comme un indice plutôt que comme un fait. - Si vous avez activé
environmentDetails, leappAccessRiskVerdictvous indique si des applications capables de capturer l'écran ou de dessiner des superpositions sont présentes — sa listeappsDetectedutilise des valeurs telles queKNOWN_INSTALLED,UNKNOWN_INSTALLEDetUNKNOWN_CAPTURING— et le verdict Play Protect résume l'état de Play Protect sur l'appareil.
Deux cas non évidents méritent une attention particulière. Les émulateurs qui passent les contrôles d'intégrité système et satisfont aux exigences de compatibilité essentielles de Android peuvent recevoir leur propre libellé d'appareil, donc « émulateur » ne signifie pas automatiquement « attaquant ». Et un appareil qui ne correspond à aucun libellé omet entièrement le champ, ce qui signifie qu'un code qui suppose que la clé est toujours présente plante au lieu d'échouer en mode sécurisé.
7. Quota, codes d’erreur et échec sécurisé
Par défaut, votre application peut effectuer jusqu'à 10 000 requêtes par jour sur l'ensemble des installations. Ce plafond est atteint plus vite que les équipes ne l'imaginent après une mise en ligne, alors surveillez l'usage dans le projet Cloud lié et demandez une augmentation tant que la courbe vous laisse de la marge. Le dépassement se manifeste par TOO_MANY_REQUESTS (code d'erreur -8), que vous absorbez par un backoff exponentiel plutôt qu'en bloquant les utilisateurs.
La gestion des erreurs est le point où les intégrations échouent le plus souvent. Traitez celles-ci comme transitoires et réessayez avec un backoff : NETWORK_ERROR (-3), TOO_MANY_REQUESTS (-8), GOOGLE_SERVER_UNAVAILABLE (-12) et CLIENT_TRANSIENT_ERROR (-18). Les autres sont liées à l'environnement — pas de Play Store, pas de services Play, une version obsolète des services Play, un compte Play manquant, un numéro de projet Cloud que l'API rejette. Les recommandations de Google pour ces cas consistent à considérer le résultat comme si le client avait échoué aux vérifications, tout en gardant l'interaction utilisable dans la mesure du raisonnable.
Traitez les erreurs comme une question de politique, pas seulement comme un chemin de code. Bloquer tous ceux dont l’appareil paraît inhabituel transforme un signal anti-abus en problème de rétention ; ignorer silencieusement chaque échec est l’erreur inverse. Décidez surface par surface — un classement peut être permissif, un rechargement de portefeuille peut être strict — et consignez la décision pour que le prochain ingénieur hérite du raisonnement.
Google propose aussi des boîtes de dialogue de remédiation : des flux déclenchés par l'application et guidés par Google qui aident un utilisateur légitime à réparer le problème sous-jacent, comme installer la version officielle depuis Play ou rétablir la connectivité, au lieu de le laisser dans une impasse. Et si vous devez repérer les abus répétés provenant du même matériel après une application des règles, la fonctionnalité device recall (bêta) est faite pour cela.
8. Le déployer sans casser l'expérience de vos utilisateurs
Télémétrie avant application des règles. Journalisez les verdicts et leur distribution pendant quelques semaines avant de conditionner quoi que ce soit, afin de connaître la proportion réelle de résultats UNEVALUATED et UNLICENSED dans votre propre base d’installations, et non dans le billet de blog de quelqu’un d’autre. Appliquez ensuite les règles par paliers : d’abord le libellé d’appareil par défaut, puis les libellés supplémentaires, et une surface à la fois. Gardez le client capable de distinguer « réessayer » de « non », et assurez-vous que l’application se dégrade proprement lorsque l’API est simplement indisponible — un utilisateur sur un réseau instable ne doit pas perdre l’accès à un contenu déjà payé.
9. Où se situe KappS
KappS aide les développeurs à maintenir leurs comptes et leurs versions dans un état qui résiste à l'examen des plateformes — en préparant et en soumettant des éléments conformes, jamais en contournant les contrôles. Concrètement, cela signifie :
- Hygiène de publication. Signée avec Play App Signing, téléversée via le canal officiel, codes de version et certificats cohérents avec les enregistrements que Google Play reconnaît — les conditions sans lesquelles
PLAY_RECOGNIZEDest même possible. - Préparation du compte. Vérification du développeur, profil de paiement et informations fiscales alignés sur l’identité juridique derrière le compte, pour qu’un lancement ne soit pas bloqué par un examen sans rapport.
- Revue de l'intégration. Un second regard sur la façon dont le client demande les jetons, sur ce sur quoi le serveur branche, et sur la cohérence entre le niveau d'application des règles et le risque métier.
Nous n'offrons pas, et n'offrirons jamais, de contournement d'intégrité, de falsification de verdict ni d'outils qui cachent une version modifiée à Play. C'est précisément ce que cette API existe pour détecter, cela met le compte en danger et ce n'est pas un service que nous proposons. La seule façon durable de passer un contrôle d'intégrité, c'est d'être le produit authentique.
Sources (documentation officielle Google) : Play Integrity API — Vue d’ensemble ; Configuration ; Effectuer une requête standard ; Effectuer une requête classique ; À propos des verdicts d’intégrité ; Utiliser le rappel d’appareil ; Gérer les codes d’erreur ; Dialogues de remédiation (developer.android.com).
Vous gérez des comptes développeur à grande échelle ? Nous prenons en charge le volet opérationnel.
Nous avons bien reçu votre message et vous répondrons sous 24 heures.
← Retour à la modification