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 façon appropriée pour empêcher la tricherie, les accès non autorisés, le trafic frauduleux et les utilisations abusives.

Conditions préalables

• Terminez la configuration du SDK.
• Consultez les points à noter concernant la sécurité de l'API Integrity.
• Lisez et comprenez les Conditions d'utilisation et les informations sur le traitement des données de l'API Integrity.
• Dans la console Google Cloud, créez un projet Cloud ou sélectionnez un projet Cloud existant que vous souhaitez utiliser avec Play Integrity pour PC. Accédez à API et services, puis activez l'API Google Play Integrity.
• Si vous prévoyez d'envoyer plus de 10 000 requêtes Play Integrity pour PC par jour, vous devez demander à augmenter votre limite quotidienne.

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

Décidez quand appeler 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. Ensuite, décidez comment gérer les différentes réponses d'intégrité. Vous pouvez par exemple :

• Collecter la réponse sans prendre de mesures coercitives et analyser les données en interne pour déterminer si elles constituent un signal utile d'utilisation abusive.
• Collectez la réponse et implémentez une logique sur votre serveur backend pour permettre aux appareils qui obtiennent des verdicts d'intégrité de jouer normalement à votre jeu, tout en contestant ou en refusant l'accès au trafic provenant d'environnements suspects.
• Collectez la réponse et implémentez une logique sur votre backend pour regrouper les joueurs sur les appareils qui réussissent les vérifications d'intégrité, tout en regroupant 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 demandes d'intégrité à la demande lorsque vous en avez besoin.

void PrepareIntegrityToken(
  const PrepareIntegrityTokenParams & params,
  PrepareIntegrityTokenContinuation continuation
)

En cas de réussite, la continuation est 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 toute la durée de la session de l'application pour les appels à RequestIntegrityToken.

L'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é.

Vous trouverez ci-dessous un extrait de code montrant comment appeler l'action PrepareIntegrityToken :

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 votre 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é et 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 champ RequestIntegrityTokenParams::request_hash 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 s'assurer 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 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é :

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

Vous trouverez ci-dessous un extrait de code montrant comment appeler l'action RequestIntegrityToken :

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 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. Un jeton d'intégrité déchiffré se présente comme suit :

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

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 demande 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écidez de 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 est exécuté sur un PC qui réussit les contrôles d'intégrité Play (réponse MEETS_PC_INTEGRITY). Le serveur backend de votre jeu peut collecter ces informations et les utiliser pour déterminer l'action à effectuer par votre jeu, par exemple autoriser un événement de jeu à se produire ou refuser l'accès au trafic à risque.

"deviceIntegrity": {
  "deviceRecognitionVerdict": ["MEETS_PC_INTEGRITY"]
}

deviceRecognitionVerdict peut avoir les valeurs suivantes :

MEETS_PC_INTEGRITY

Le jeu s'exécute dans un environnement PC authentique, où aucune falsification sur l'appareil n'a été détectée.

Vide (valeur vide)

Le jeu est exécuté 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).

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

Si votre jeu envoie 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, comme des problèmes environnementaux (mauvaise connexion réseau, par exemple), des problèmes d'intégration de votre API ou une activité malveillante 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.

Pour obtenir d'autres recommandations sur les stratégies de nouvelle tentative, 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.