Boîtes de dialogue de correction

Cette page explique comment gérer les problèmes liés aux évaluations de l'intégrité.

Lorsqu'un jeton d'intégrité est demandé, vous avez la possibilité d'afficher une boîte de dialogue Google Play. Vous pouvez afficher la boîte de dialogue en cas de problème lié à l'évaluation de l'intégrité ou si une exception s'est produite lors d'une requête API Integrity. Une fois la boîte de dialogue fermée, vous pouvez vérifier que le problème est résolu en envoyant une autre requête de jeton d'intégrité. Si vous effectuez des requêtes standards, vous devez rafraîchir le fournisseur de jetons pour obtenir une nouvelle évaluation.

Remarque : Tous les types de boîtes de dialogue d'intégrité peuvent être présentés aux utilisateurs, quel que soit le contenu du jeton d'intégrité. Vous devez vérifier le contenu du jeton d'intégrité sur votre serveur pour déterminer la boîte de dialogue à afficher.

Demander une boîte de dialogue d'intégrité pour résoudre un problème d'évaluation

Lorsque le client demande un jeton d'intégrité, vous pouvez utiliser la méthode proposée dans StandardIntegrityToken (API standard) et IntegrityTokenResponse (API classique) : showDialog(Activity activity, int integrityDialogTypeCode).

Remarque : Pour utiliser les boîtes de dialogue d'intégrité, vous devez utiliser la version 1.3.0 ou ultérieure de la bibliothèque Android de l'API Integrity.

Pour afficher une boîte de dialogue de correction à l'aide de l'API Play Integrity et du code de boîte de dialogue GET_LICENSED, procédez comme suit : D'autres codes de boîte de dialogue que votre application peut demander sont listés après cette section.

1. Demandez un jeton d'intégrité à votre application et envoyez-le à votre serveur. Vous pouvez utiliser la requête standard ou classique.

   Kotlin

   // Request an integrity token
   val tokenResponse: StandardIntegrityToken = requestIntegrityToken()
   // Send token to app server and get response on what to do next
   val yourServerResponse: YourServerResponse = sendToServer(tokenResponse.token())  

   Java

   // Request an integrity token
   StandardIntegrityToken tokenResponse = requestIntegrityToken();
   // Send token to app server and get response on what to do next
   YourServerResponse yourServerResponse = sendToServer(tokenResponse.token());  

   Unity

   // Request an integrity token
   StandardIntegrityToken tokenResponse = RequestIntegrityToken();
   // Send token to app server and get response on what to do next
   YourServerResponse yourServerResponse = sendToServer(tokenResponse.Token); 

   Unreal Engine

   // Request an integrity token
   StandardIntegrityToken* Response = RequestIntegrityToken();
   // Send token to app server and get response on what to do next
   YourServerResponse YourServerResponse = SendToServer(Response->Token); 

   Natif

   /// Request an integrity token
   StandardIntegrityToken* response = requestIntegrityToken();
   /// Send token to app server and get response on what to do next
   YourServerResponse yourServerResponse = sendToServer(StandardIntegrityToken_getToken(response));

2. Sur votre serveur, déchiffrez le jeton d'intégrité et vérifiez le champ appLicensingVerdict. Voici ce que vous pourriez voir s'afficher :

   // Licensing issue
   {
     ...
     "accountDetails": {
         "appLicensingVerdict": "UNLICENSED"
     }
   }

3. Si le jeton contient appLicensingVerdict: "UNLICENSED", répondez au client de votre application en lui demandant d'afficher la boîte de dialogue d'attribution de licences :

   Kotlin

   private fun getDialogTypeCode(integrityToken: String): Int{
     // Get licensing verdict from decrypted and verified integritytoken
     val licensingVerdict: String = getLicensingVerdictFromDecryptedToken(integrityToken)
   
     return if (licensingVerdict == "UNLICENSED") {
             1 // GET_LICENSED
         } else 0
   }

   Java

   private int getDialogTypeCode(String integrityToken) {
     // Get licensing verdict from decrypted and verified integrityToken
     String licensingVerdict = getLicensingVerdictFromDecryptedToken(integrityToken);
   
     if (licensingVerdict.equals("UNLICENSED")) {
       return 1; // GET_LICENSED
     }
     return 0;
   }

   Unity

   private int GetDialogTypeCode(string IntegrityToken) {
     // Get licensing verdict from decrypted and verified integrityToken
     string licensingVerdict = GetLicensingVerdictFromDecryptedToken(IntegrityToken);
   
     if (licensingVerdict == "UNLICENSED") {
       return 1; // GET_LICENSED
     }
     return 0;
   } 

   Unreal Engine

   private int GetDialogTypeCode(FString IntegrityToken) {
     // Get licensing verdict from decrypted and verified integrityToken
     FString LicensingVerdict = GetLicensingVerdictFromDecryptedToken(IntegrityToken);
   
     if (LicensingVerdict == "UNLICENSED") {
       return 1; // GET_LICENSED
     }
     return 0;
   } 

   Natif

   private int getDialogTypeCode(string integrity_token) {
     /// Get licensing verdict from decrypted and verified integrityToken
     string licensing_verdict = getLicensingVerdictFromDecryptedToken(integrity_token);
   
     if (licensing_verdict == "UNLICENSED") {
       return 1; // GET_LICENSED
     }
     return 0;
   }

4. Dans votre application, appelez showDialog avec le code demandé récupéré à partir de votre serveur :

   Kotlin

   // Show dialog as indicated by the server
   val showDialogType: Int? = yourServerResponse.integrityDialogTypeCode()
   if (showDialogType != null) {
     // Call showDialog with type code, the dialog will be shown on top of the
     // provided activity and complete when the dialog is closed.
     val integrityDialogResponseCode: Task<Int> =
     tokenResponse.showDialog(activity, showDialogType)
     // Handle response code, call the Integrity API again to confirm that
     // verdicts have been resolved.
   } 

   Java

   // Show dialog as indicated by the server
   @Nullable Integer showDialogType = yourServerResponse.integrityDialogTypeCode();
   if (showDialogType != null) {
     // Call showDialog with type code, the dialog will be shown on top of the
     // provided activity and complete when the dialog is closed.
     Task<Integer> integrityDialogResponseCode =
         tokenResponse.showDialog(activity, showDialogType);
     // Handle response code, call the Integrity API again to confirm that
     // verdicts have been resolved.
   }

   Unity

   IEnumerator ShowDialogCoroutine() {
     int showDialogType = yourServerResponse.IntegrityDialogTypeCode();
   
     // Call showDialog with type code, the dialog will be shown on top of the
     // provided activity and complete when the dialog is closed.
     var showDialogTask = tokenResponse.ShowDialog(showDialogType);
   
     // Wait for PlayAsyncOperation to complete.
     yield return showDialogTask;
   
     // Handle response code, call the Integrity API again to confirm that
     // verdicts have been resolved.
   } 

   Unreal Engine

   // .h
   void MyClass::OnShowDialogCompleted(
     EStandardIntegrityErrorCode Error,
     EIntegrityDialogResponseCode Response)
   {
     // Handle response code, call the Integrity API again to confirm that
     // verdicts have been resolved.
   }
   
   // .cpp
   void MyClass::RequestIntegrityToken()
   {
     UStandardIntegrityToken* Response = ...
     int TypeCode = YourServerResponse.integrityDialogTypeCode();
   
     // Create a delegate to bind the callback function.
     FShowDialogStandardOperationCompletedDelegate Delegate;
   
     // Bind the completion handler (OnShowDialogCompleted) to the delegate.
     Delegate.BindDynamic(this, &MyClass::OnShowDialogCompleted);
   
     // Call ShowDialog with TypeCode which completes when the dialog is closed.
     Response->ShowDialog(TypeCode, Delegate);
   }

   Natif

   // Show dialog as indicated by the server
   int show_dialog_type = yourServerResponse.integrityDialogTypeCode();
   if (show_dialog_type != 0) {
     /// Call showDialog with type code, the dialog will be shown on top of the
     /// provided activity and complete when the dialog is closed.
     StandardIntegrityErrorCode error_code =
         IntegrityTokenResponse_showDialog(response, activity, show_dialog_type);
   
     /// Proceed to polling iff error_code == STANDARD_INTEGRITY_NO_ERROR
     if (error_code != STANDARD_INTEGRITY_NO_ERROR)
     {
         /// Remember to call the *_destroy() functions.
         return;
     }
   
     /// Use polling to wait for the async operation to complete.
     /// Note, the polling shouldn't block the thread where the IntegrityManager
     /// is running.
   
     IntegrityDialogResponseCode* response_code;
     error_code = StandardIntegrityToken_getDialogResponseCode(response, response_code);
   
     if (error_code != STANDARD_INTEGRITY_NO_ERROR)
     {
         /// Remember to call the *_destroy() functions.
         return;
     }
   
     /// Handle response code, call the Integrity API again to confirm that
     /// verdicts have been resolved.
   }

5. La boîte de dialogue s'affiche au-dessus de l'activité fournie. Lorsque l'utilisateur a fermé la boîte de dialogue, la tâche se termine avec un code de réponse.

6. (Facultatif) Demandez un autre jeton pour afficher d'autres boîtes de dialogue. Si vous effectuez des requêtes standards, vous devez rafraîchir le fournisseur de jetons pour obtenir une nouvelle évaluation.

Demander une boîte de dialogue d'intégrité pour corriger une exception côté client

Si une requête de l'API Integrity échoue avec un code d'erreur StandardIntegrityException (API Standard) ou IntegrityServiceException (API Classic) et que l'exception peut être corrigée, vous pouvez utiliser les boîtes de dialogue GET_INTEGRITY ou GET_STRONG_INTEGRITY pour résoudre le problème.

Remarque : Pour utiliser les nouvelles boîtes de dialogue GET_INTEGRITY ou GET_STRONG_INTEGRITY, vous devez utiliser la version 1.5.0 ou ultérieure de la bibliothèque Android de l'API Integrity. Cette mise à jour permet d'accéder à la nouvelle méthode showDialog dans IntegrityManager (API classique) ou StandardIntegrityManager (API standard) pour résoudre les exceptions côté client.

Pour corriger une erreur côté client réparable signalée par l'API Integrity à l'aide de la boîte de dialogue GET_INTEGRITY, procédez comme suit :

1. Vérifiez que l'exception renvoyée par une requête de l'API Integrity peut être corrigée.

   Kotlin

   private fun isExceptionRemediable(exception: ExecutionException): Boolean {
     val cause = exception.cause
     if (cause is StandardIntegrityException && cause.isRemediable) {
         return true
     }
     return false
   }
    

   Java

   private boolean isExceptionRemediable(ExecutionException exception) {
     Throwable cause = exception.getCause();
     if (cause instanceof StandardIntegrityException integrityException
   && integrityException.isRemediable()) {
         return true;
     }
     return false;
   }
    

2. Si l'exception peut être corrigée, demandez la boîte de dialogue GET_INTEGRITY à l'aide de l'exception renvoyée. La boîte de dialogue s'affiche au-dessus de l'activité fournie, et la tâche renvoyée se termine avec un code de réponse une fois que l'utilisateur a fermé la boîte de dialogue.

   Kotlin

   private fun showDialog(exception: StandardIntegrityException) {
     // Create a dialog request
     val standardIntegrityDialogRequest =
         StandardIntegrityDialogRequest.builder()
             .setActivity(activity)
             .setType(IntegrityDialogTypeCode.GET_INTEGRITY)
             .setStandardIntegrityResponse(ExceptionDetails(exception))
             .build()
   
     // Request dialog
     val responseCode: Task<Int> =
           standardIntegrityManager.showDialog(standardIntegrityDialogRequest)
   }
    

   Java

   private void showDialog(StandardIntegrityException exception) {
     // Create a dialog request
     StandardIntegrityDialogRequest standardIntegrityDialogRequest =
         StandardIntegrityDialogRequest.builder()
             .setActivity(this.activity)
             .setType(IntegrityDialogTypeCode.GET_INTEGRITY)
             .setStandardIntegrityResponse(new ExceptionDetails(exception))
             .build();
   
     // Request dialog
     Task<Integer> responseCode =
           standardIntegrityManager.showDialog(standardIntegrityDialogRequest);
   }  

3. Si le code de réponse renvoyé indique une réussite, la prochaine demande de jeton d'intégrité devrait aboutir sans aucune exception. Si vous effectuez des requêtes standards, vous devez rafraîchir le fournisseur de jetons pour obtenir une nouvelle évaluation.

Codes des boîtes de dialogue sur l'intégrité

GET_LICENSED (code de type 1)

Problème d'évaluation

Cette boîte de dialogue convient pour deux problèmes :

• Accès non autorisé : appLicensingVerdict: "UNLICENSED". Cela signifie que le compte utilisateur ne dispose pas d'un droit d'accès à votre application, ce qui peut se produire si l'utilisateur l'a téléchargée indépendamment ou l'a acquise sur une autre plate-forme de téléchargement que Google Play.
• Application falsifiée : appRecognitionVerdict: "UNRECOGNIZED_VERSION". Cela signifie que le binaire de votre application a été modifié ou qu'il ne s'agit pas d'une version reconnue par Google Play.

Correction

Vous pouvez afficher la boîte de dialogue GET_LICENSED pour inviter l'utilisateur à télécharger l'application authentique depuis Google Play. Cette boîte de dialogue unique s'applique aux deux scénarios :

• Pour un utilisateur sans licence, elle lui accorde une licence Play. Cela permet à l'utilisateur de recevoir les mises à jour de l'application depuis Google Play.
• Pour un utilisateur disposant d'une version frelatée de l'application, il l'invite à installer la version non modifiée depuis Google Play.

Lorsque l'utilisateur termine la boîte de dialogue, les vérifications de l'intégrité suivantes renvoient appLicensingVerdict: "LICENSED" et appRecognitionVerdict: "PLAY_RECOGNIZED".

Exemple d'expérience utilisateur

Figure 1 : Boîte de dialogue Google Play GET_LICENSED.

CLOSE_UNKNOWN_ACCESS_RISK (code de type 2)

Problème d'évaluation

Lorsque environmentDetails.appAccessRiskVerdict.appsDetected contient "UNKNOWN_CAPTURING" ou "UNKNOWN_CONTROLLING", cela signifie que d'autres applications (non installées par Google Play ni préchargées sur la partition système par le fabricant de l'appareil) sont en cours d'exécution sur l'appareil et peuvent capturer l'écran ou contrôler l'appareil.

Correction

Vous pouvez afficher la boîte de dialogue CLOSE_UNKNOWN_ACCESS_RISK pour inviter l'utilisateur à fermer toutes les applications inconnues susceptibles de capturer l'écran ou de contrôler l'appareil. Si l'utilisateur appuie sur le bouton Close all, toutes ces applications sont fermées.

Exemple d'expérience utilisateur

Figure 2 : Boîte de dialogue permettant de fermer le risque d'accès inconnu.

CLOSE_ALL_ACCESS_RISK (code de type 3)

Problème d'évaluation

Lorsque environmentDetails.appAccessRiskVerdict.appsDetected contient l'un des éléments suivants : "KNOWN_CAPTURING", "KNOWN_CONTROLLING","UNKNOWN_CAPTURING" ou "UNKNOWN_CONTROLLING", cela signifie que des applications s'exécutent sur l'appareil et peuvent capturer l'écran ou contrôler l'appareil.

Correction

Vous pouvez afficher la boîte de dialogue CLOSE_ALL_ACCESS_RISK pour inviter l'utilisateur à fermer toutes les applications susceptibles de capturer l'écran ou de contrôler l'appareil. Si l'utilisateur appuie sur le bouton Close all, toutes ces applications sont fermées sur l'appareil.

Exemple d'expérience utilisateur

Figure 3 : Boîte de dialogue pour fermer tous les risques d'accès.

GET_INTEGRITY (code de type 4)

Problème d'évaluation

Cette boîte de dialogue convient aux problèmes suivants :

• Intégrité de l'appareil faible : lorsque deviceRecognitionVerdict ne contient pas MEETS_DEVICE_INTEGRITY, il est possible que l'appareil ne soit pas un appareil Android authentique certifié Play Protect. Cela peut se produire, par exemple, si le bootloader de l'appareil est déverrouillé ou si l'OS Android chargé n'est pas une image certifiée du fabricant.

• Accès non autorisé : appLicensingVerdict: "UNLICENSED". Cela signifie que le compte utilisateur ne dispose pas d'un droit d'accès à votre application, ce qui peut se produire si l'utilisateur l'a installée manuellement ou l'a acquise sur un autre app store que Google Play.

• Application falsifiée : appRecognitionVerdict: "UNRECOGNIZED_VERSION". Cela signifie que le binaire de votre application a été modifié ou qu'il ne s'agit pas d'une version reconnue par Google Play.

• Exceptions côté client : lorsqu'une exception remédiable se produit lors d'une requête Integrity API. Les exceptions pouvant être corrigées sont des exceptions de l'API Integrity avec des codes d'erreur tels que PLAY_SERVICES_VERSION_OUTDATED, NETWORK_ERROR, PLAY_SERVICES_NOT_FOUND, etc. Vous pouvez utiliser la méthode exception.isRemediable() pour vérifier si une exception peut être corrigée par la boîte de dialogue.

Correction

La boîte de dialogue GET_INTEGRITY est conçue pour simplifier l'expérience utilisateur en gérant plusieurs étapes de correction dans un seul flux continu. Cela évite à l'utilisateur d'avoir à interagir avec plusieurs boîtes de dialogue distinctes pour résoudre différents problèmes.

Lorsque vous demandez la boîte de dialogue, elle détecte automatiquement les problèmes de verdict ciblés qui sont présents et fournit les étapes de correction appropriées. Cela signifie qu'une seule demande de boîte de dialogue peut résoudre plusieurs problèmes à la fois, y compris :

• Intégrité de l'appareil : si un problème d'intégrité de l'appareil est détecté, la boîte de dialogue guidera l'utilisateur pour améliorer l'état de sécurité de l'appareil afin de répondre aux exigences d'une évaluation MEETS_DEVICE_INTEGRITY.
• Intégrité de l'application : si des problèmes tels qu'un accès non autorisé ou une falsification de l'application sont détectés, la boîte de dialogue invitera les utilisateurs à télécharger l'application depuis le Play Store pour les résoudre.

Remarque : La boîte de dialogue GET_INTEGRITY détecte et tente de résoudre automatiquement plusieurs problèmes de verdict sur demande. Pour résoudre uniquement les problèmes liés aux licences de compte ou à l'intégrité des applications, nous vous recommandons d'utiliser la boîte de dialogue GET_LICENSED.

• Exceptions côté client : la boîte de dialogue recherche et tente de résoudre les problèmes sous-jacents qui ont provoqué une exception de l'API Integrity. Par exemple, il peut inviter l'utilisateur à mettre à jour une version obsolète des services Google Play.

Exemple d'expérience utilisateur

Figure 4 : Flux de correction des erreurs réseau de la boîte de dialogue GET_INTEGRITY

GET_STRONG_INTEGRITY (code de type 5)

Problème d'évaluation

Cette boîte de dialogue est conçue pour résoudre tous les problèmes traités par GET_INTEGRITY, avec en plus la possibilité de résoudre les problèmes qui empêchent un appareil de recevoir un verdict MEETS_STRONG_INTEGRITY et de résoudre les problèmes de verdict Play Protect.

Remarque : MEETS_STRONG_INTEGRITY et playProtectVerdict sont des verdicts facultatifs. Vous ne devez les vérifier que si vous avez choisi de recevoir des libellés supplémentaires.

Correction

GET_STRONG_INTEGRITY est conçu pour simplifier l'expérience utilisateur en gérant plusieurs étapes de correction dans un seul flux continu. La boîte de dialogue recherche automatiquement les problèmes d'intégrité applicables à une adresse, y compris :

• Intégrité de l'appareil : si un problème d'intégrité de l'appareil est détecté, la boîte de dialogue guidera l'utilisateur pour améliorer l'état de sécurité de l'appareil afin de répondre aux exigences d'une évaluation MEETS_STRONG_INTEGRITY.

• État Play Protect : si l'icône playProtectVerdict indique un problème, la boîte de dialogue guide l'utilisateur pour le résoudre :

  • Si Play Protect est désactivé (playProtectVerdict == POSSIBLE_RISK), la boîte de dialogue invite l'utilisateur à l'activer et à analyser toutes les applications sur l'appareil.
  • Si des applications dangereuses sont détectées (playProtectVerdict == MEDIUM_RISK ou HIGH_RISK), la boîte de dialogue invite l'utilisateur à les désinstaller à l'aide de Google Play Protect.

• Intégrité de l'application : si des problèmes tels qu'un accès non autorisé ou une falsification de l'application sont détectés, la boîte de dialogue invite l'utilisateur à acquérir l'application sur le Play Store pour résoudre le problème.

• Exceptions côté client : la boîte de dialogue tente également de résoudre les problèmes sous-jacents qui ont provoqué une exception de l'API Integrity. Par exemple, il peut inviter l'utilisateur à activer les services Google Play s'ils sont désactivés. Les exceptions pouvant être corrigées sont des exceptions de l'API Integrity avec des codes d'erreur tels que PLAY_SERVICES_VERSION_OUTDATED, NETWORK_ERROR ou PLAY_SERVICES_NOT_FOUND. Vous pouvez utiliser la méthode exception.isRemediable() pour vérifier si une erreur peut être corrigée par la boîte de dialogue.

Exemple d'expérience utilisateur

Figure 5 : Boîte de dialogue GET_STRONG_INTEGRITY indiquant la mise à jour des services Play.