Intégrer Play Integrity pour PC à votre application

Play Integrity pour PC vous aide à vérifier que les événements de jeu et les requêtes de serveur proviennent d'une instance authentique de Google Play Jeux pour PC sur un appareil PC authentique. En détectant les appareils potentiellement risqués et les émulateurs inconnus, le serveur backend de votre jeu peut réagir de manière appropriée pour éviter la triche, les accès non autorisés, le trafic frauduleux et les abus.

Conditions préalables

Étape 1 : Déterminez comment utiliser Play Integrity pour PC dans votre jeu

Déterminez quand vous appellerez Play Integrity pour PC afin d'obtenir une évaluation de l'intégrité de l'environnement. Par exemple, vous pouvez demander une évaluation lorsque le jeu est ouvert, lorsqu'un joueur se connecte ou lorsqu'il rejoint un jeu multijoueur. Déterminez ensuite comment vous gérerez les différentes réponses d'intégrité. Vous pouvez par exemple :

  • Collecter la réponse sans aucune mesure d'application et analyser les données en interne pour déterminer s'il s'agit d'un signal d'abus utile.
  • Collecter la réponse et implémenter une logique sur votre serveur backend pour autoriser les appareils qui réussissent les évaluations d'intégrité à jouer normalement à votre jeu, tout en mettant en cause ou en refusant l'accès au trafic provenant d'environnements suspects.
  • Collecter la réponse et implémenter une logique sur votre backend pour faire correspondre les joueurs sur les appareils qui réussissent les contrôles d'intégrité, tout en faisant correspondre le trafic provenant d'environnements suspects.

Étape 2 : Demandez des jetons d'intégrité dans votre jeu

Préparer Play Integrity pour PC

Préparez (ou "échauffez") Play Integrity pour PC, ce qui permet à Google Play de mettre en cache intelligemment les informations d'attestation partielle sur l'appareil afin de réduire la latence sur le chemin critique lorsque vous effectuez une requête d'évaluation de l'intégrité. Vous pouvez le faire de manière asynchrone dès l'ouverture de votre jeu afin de pouvoir effectuer des requêtes d'intégrité à la demande lorsque vous en avez besoin.

void PrepareIntegrityToken(
  const PrepareIntegrityTokenParams & params,
  PrepareIntegrityTokenContinuation continuation
)

En cas de succès, la continuation sera appelée avec une PrepareIntegrityTokenResultValue contenant une RequestTokenData qui doit être utilisée pour demander un jeton d'intégrité. Ces données doivent être mises en cache en mémoire et réutilisées pendant la durée de la session de l'application pour les appels à RequestIntegrityToken.

Un appel à PrepareIntegrityToken ne doit être effectué que si votre application détermine qu'il est nécessaire de réévaluer entièrement l'évaluation de l'intégrité.

Détails
Paramètres params : paramètres contenant un numéro de projet Google Cloud.
continuation: rappel asynchrone pour renvoyer le fournisseur de jetons d'intégrité à.

Un extrait de code montrant comment l'action PrepareIntegrityToken doit être appelée est fourni comme suit :

google::play::integrity::IntegrityClient client_;

google::play::integrity::PrepareIntegrityTokenResult
IntegrityInterface::PrepareIntegrityToken(int64_t cloud_project_number) {
  google::play::integrity::PrepareIntegrityTokenParams params;
  params.cloud_project_number = cloud_project_number;

  auto promise = std::make_shared<
      std::promise<google::play::integrity::PrepareIntegrityTokenResult>>();
  client_.PrepareIntegrityToken(
      params,
      [promise](
          google::play::integrity::PrepareIntegrityTokenResult result) {
        promise->set_value(std::move(result));
      });

  return promise->get_future().get();
}

Demander un jeton d'intégrité

Les jetons d'intégrité permettent à votre jeu de vérifier que l'appareil n'a pas été altéré. Chaque fois que votre jeu effectue une requête de serveur que vous souhaitez vérifier, vous pouvez demander un jeton d'intégrité, puis l'envoyer au serveur backend de votre jeu pour qu'il le déchiffre et le valide.

Lorsque vous vérifiez une action de l'utilisateur dans votre application avec l'API Play Integrity pour PC, vous pouvez utiliser le RequestIntegrityTokenParams::request_hash champ pour limiter les attaques par falsification. Par exemple, vous pouvez vouloir communiquer le score du joueur au serveur backend de votre jeu, et votre serveur veut vérifier que ce score n'a pas été modifié par un serveur proxy. Play Integrity pour PC peut renvoyer la valeur que vous avez définie dans ce champ, dans la réponse d'intégrité signée. Sans le champ requestHash, le jeton d'intégrité ne sera lié qu'à l'appareil, et non à la requête spécifique, ce qui n'exclut pas le risque d'attaque.

void RequestIntegrityToken(
  const RequestIntegrityTokenParams & params,
  RequestIntegrityTokenContinuation continuation
)

Pour limiter le risque d'attaque, lorsque vous demandez une évaluation de l'intégrité, procédez comme suit :

  • Calculez un récapitulatif de tous les paramètres de requête pertinents (par exemple, SHA256 d'une sérialisation de requête stable) à partir de l'action de l'utilisateur ou de la requête de serveur en cours.
  • Définissez le champ RequestIntegrityTokenParams::request_hash sur le récapitulatif.
Détails
Paramètres params : paramètres contenant le hachage de requête RequestTokenData et de vérification d’intégrité préparé.
continuation: rappel asynchrone pour renvoyer les données à.

Un extrait de code montrant comment l'action RequestIntegrityToken peut être appelée est fourni comme suit :

absl::StatusOr<google::play::integrity::RequestIntegrityTokenResult>
IntegrityInterface::RequestIntegrityToken(
    const google::play::integrity::PrepareIntegrityTokenResult&
        prepare_integrity_token_result,
    const std::string& request_hash) {
  // Check if the prepare_integrity_token_result is OK
  if (!prepare_integrity_token_result.ok()) {
    return absl::FailedPreconditionError(
        absl::StrCat("PrepareIntegrityTokenResult is not OK. Error code: ",
                     prepare_integrity_token_result.error_code));
  }

  google::play::integrity::RequestIntegrityTokenParams params{
      .request_token_data =
          prepare_integrity_token_result.request_token_data,
      .request_hash = request_hash};

  auto promise = std::make_shared<std::promise<
      google::play::integrity::RequestIntegrityTokenResult>>();
  client_.RequestIntegrityToken(
      params,
      [promise](google::play::integrity::RequestIntegrityTokenResult result) {
        promise->set_value(std::move(result));
      });

  return promise->get_future().get();
}

Étape 3 : Déchiffrez et validez ensuite les jetons d'intégrité sur le serveur backend de votre jeu

Déchiffrer un jeton d'intégrité

Une fois que vous avez demandé l'évaluation de l'intégrité, l'API Play Integrity fournit un jeton de réponse chiffré. Pour obtenir les évaluations de l'intégrité de l'appareil, vous devez déchiffrer le jeton d'intégrité sur les serveurs de Google :

  1. Créez un compte de service dans le projet Google Cloud associé à votre application.

  2. Sur le serveur de votre application, récupérez le jeton d'accès à partir des identifiants de votre compte de service à l'aide du champ d'application playintegrity, puis exécutez la requête suivante :

    playintegrity.googleapis.com/v1/<var>PACKAGE_NAME</var>:decodePcIntegrityToken -d \
 '{ "integrity_token": "<var>INTEGRITY_TOKEN</var>" }'

  3. Lisez la réponse JSON.

La charge utile résultante est un jeton en texte brut contenant des évaluations et des détails sur l'intégrité, ainsi que des informations fournies par le développeur. Voici à quoi ressemble un jeton d'intégrité déchiffré :

{
  "requestDetails": {
    "requestPackageName": "com.your.package.name",
    "requestTime": "2025-08-29T13:10:37.285Z",
    "requestHash": "your_request_hash_string"
  },
  "deviceIntegrity": {
    "deviceRecognitionVerdict": [
      "MEETS_PC_INTEGRITY"
    ]
  },
  "accountDetails": {
    "appLicensingVerdict": "LICENSED"
  }
}

Valider le jeton d'intégrité

Le champ requestDetails du jeton d'intégrité décodé contient des informations sur la requête, y compris les informations fournies par le développeur dans requestHash.

Les champs requestHash et packageName doivent correspondre à ceux de la requête d'origine. Par conséquent, vérifiez la partie requestDetails de la charge utile JSON en vous assurant que requestPackageName et requestHash correspondent à ce qui a été envoyé dans la requête d'origine, comme dans l'extrait de code suivant :

const auto& request_details = json_payload["requestDetails"];

if (request_details.value("requestPackageName", "") != <YOUR_PACKAGE_NAME>) {
  // Don't trust the verdicts.
}

// Check for the existence of the request_hash.
// If you set a request hash in the request and it's not present, you shouldn't
// trust the verdicts.
if (!request_details.contains("requestHash")) {
    // Don't trust the verdicts.
}


// The requestHash from request_details needs to match the request hash your
// app provided.
if (request_details.value("requestHash", "") != <PROVIDED_REQUEST_HASH>) {
    // Don't trust the verdicts.
}

// You can read the rest of payload's fields.

Étape 4 : Déterminez l'action à entreprendre en fonction de l'évaluation de l'intégrité

Le champ deviceIntegrity peut contenir une seule valeur, deviceRecognitionVerdict. Vous pouvez utiliser cette valeur pour déterminer si votre jeu s'exécute ou non sur un PC qui réussit les contrôles d'intégrité Play (réponse MEETS_PC_INTEGRITY). Le champ accountDetails contient une seule valeur, appLicensingVerdict. Vous pouvez utiliser cette valeur pour déterminer si l'utilisateur a obtenu une licence de Play. Le serveur backend de votre jeu peut collecter ces informations et les utiliser pour déterminer l'action à entreprendre par votre jeu, par exemple autoriser un événement de jeu à se poursuivre ou refuser l'accès au trafic risqué.

"deviceIntegrity": {
  "deviceRecognitionVerdict": ["MEETS_PC_INTEGRITY"]
}
"accountDetails": {
  "appLicensingVerdict": "LICENSED"
}

Évaluations de l'intégrité de l'appareil

deviceRecognitionVerdict peut avoir les valeurs suivantes :

MEETS_PC_INTEGRITY
Le jeu s'exécute dans un environnement PC authentique, où aucune altération sur l'appareil n'a été détectée.
Vide (valeur vide)
Le jeu s'exécute sur un appareil présentant des signes d'attaque (hook d'API, par exemple) ou un piratage du système (appareil exécutant une version altérée des services Google Desktop, par exemple), ou il n'est pas exécuté sur un appareil physique (un émulateur n'ayant pas réussi les contrôles d'intégrité de Google Play, par exemple).

Évaluations des détails du compte

appLicensingVerdict peut avoir les valeurs suivantes :

LICENSED
L'utilisateur est autorisé à accéder à l'application. En d'autres termes, il 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. Cela peut se produire pour plusieurs raisons, y compris les suivantes :
  • L'appareil n'est pas suffisamment fiable.
  • La version de votre application installée sur l'appareil est inconnue de Google Play.
  • L'utilisateur n'est pas connecté à Google Play.

Étape 5 : Gérer les codes d'erreur

Si votre jeu effectue une requête Play Integrity pour PC et que l'appel échoue, il reçoit un code d'erreur. Ces erreurs peuvent se produire pour diverses raisons, telles que des problèmes environnementaux (mauvaise connexion réseau, par exemple), des problèmes liés à l'intégration de votre API, ou des activités malveillantes et des attaques actives.

Codes d'erreur avec possibilité de nouvelles tentatives

La cause de ces erreurs est parfois due à des conditions temporaires. Vous devez donc relancer l'appel avec une stratégie d'intervalle exponentiel entre les tentatives.

IntegrityError Description de l'erreur Code d'erreur
kNetworkError Problème de connectivité réseau sur l'appareil. 5
kTooManyRequests Trop de requêtes effectuées depuis l'appareil. 6
kClientTransientError Problème temporaire avec le client. 7

Pour plus de recommandations sur les stratégies de nouvelles tentatives , cliquez ici.

Codes d'erreur sans possibilité de nouvelles tentatives

Dans ces cas, il est peu probable que les nouvelles tentatives automatiques permettent de remédier à la situation. Toutefois, une nouvelle tentative manuelle peut être utile si l'utilisateur résout la condition à l'origine du problème.

IntegrityError Description de l'erreur Code d'erreur Action recommandée
kError Erreur fatale lors de l'action du SDK. 1 Vérifiez l'implémentation de votre API avant de réessayer.
kCloudProjectNumberIsInvalid Le numéro de projet Cloud n'est pas valide. 2 Vérifiez que votre numéro de projet Cloud est correctement configuré dans Google Cloud Console et que les requêtes sont effectuées avec le bon numéro de projet Cloud.
kRequestHashTooLong Le hachage de requête est trop long. 3 Les hachages de requête générés sont trop longs. Assurez-vous qu'ils contiennent moins de 500 caractères.
kNoValidPreparedTokenFound Aucun jeton préparé n'est disponible avant d'effectuer la requête de jeton. 4 Appelez l'action [PrepareIntegrityToken][prepare-token] avant d'effectuer l'appel [RequestIntegrityToken][request-integrity-token].
kSdkRuntimeUpdateRequired Une mise à jour est nécessaire pour le SDK Play for Native. 8 Assurez-vous que le client des services Google Play sur l'appareil est à jour et que vous utilisez la dernière version du SDK Play for Native PC.

Tester différentes réponses de l'API Play Integrity dans votre application

Vous pouvez créer des tests pour évaluer l'interaction de l'API Play Integrity avec votre application.

  1. Configurez un groupe Google (ou autant que vous le souhaitez) avec les adresses e-mail des utilisateurs. Vous pouvez sélectionner les évaluations d'intégrité ou le code d'erreur que ces utilisateurs doivent recevoir dans votre application à partir des serveurs de Google Play. Cela vous permet de tester la réaction de votre application à toutes les réponses et erreurs possibles.

  2. Créez un ticket ici et indiquez quel groupe Google recevra quelle réponse d'API. Chaque groupe est configuré pour recevoir l'une des options suivantes :

    Évaluation de licence réussie Évaluation de licence échouée Évaluation de licence impossible
    Intégrité de l'appareil réussie ALLOWLIST_CONFIG_MEETS_PC_INTEGRITY_LICENSED ALLOWLIST_CONFIG_MEETS_PC_INTEGRITY_UNLICENSED ALLOWLIST_CONFIG_MEETS_PC_INTEGRITY_LICENSING_UNEVALUATED
    Intégrité de l'appareil échouée N/A N/A ALLOWLIST_CONFIG_NO_PC_INTEGRITY_LICENSING_UNEVALUATED
    Si l'évaluation de l'intégrité de l'appareil échoue, l'évaluation de la licence renvoie toujours UNEVALUATED.

  3. Vous recevrez une notification une fois la requête traitée et les utilisateurs testeurs ajoutés à la liste d'autorisation pour recevoir les évaluations d'intégrité prédéfinies à des fins de test.