Finestre di dialogo di correzione

Questa pagina descrive come gestire i problemi relativi ai verdetti di integrità.

Quando viene richiesto un token di integrità, hai la possibilità di mostrare all'utente una finestra di dialogo di Google Play. Puoi visualizzare la finestra di dialogo quando si verifica uno o più problemi con il verdetto di integrità. La finestra di dialogo viene visualizzata sopra l'app e chiede agli utenti di risolvere la causa del problema. Una volta chiusa la finestra di dialogo, puoi verificare che il problema sia stato risolto con un'altra richiesta all'API Integrity.

Nota: tutti i tipi di finestre di dialogo di integrità possono essere mostrati agli utenti, indipendentemente dal contenuto del token di integrità. Devi controllare i contenuti del token di integrità sul tuo server per determinare quale finestra di dialogo deve essere mostrata.

Richiedere una finestra di dialogo di integrità

Quando il client richiede un token di integrità, puoi utilizzare il metodo offerto in StandardIntegrityToken (API Standard) e IntegrityTokenResponse (API classica): showDialog(Activity activity, int integrityDialogTypeCode).

Nota: per utilizzare le finestre di dialogo di integrità, devi utilizzare la libreria Android dell'API Integrity versione 1.3.0 o successive.

I seguenti passaggi descrivono come utilizzare l'API Play Integrity per mostrare una finestra di dialogo di correzione utilizzando il codice della finestra di dialogo GET_LICENSED. Dopo questa sezione sono elencati altri codici di dialogo che la tua app può richiedere.

1. Richiedi un token di integrità dalla tua app e invialo al tuo server. Puoi utilizzare la richiesta standard o classica.

   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); 

   Nativo

   /// 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. Sul server, decrittografa il token di integrità e controlla il campo appLicensingVerdict. Potrebbe avere un aspetto simile al seguente:

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

3. Se il token contiene appLicensingVerdict: "UNLICENSED", rispondi al client della tua app chiedendogli di mostrare la finestra di dialogo della licenza:

   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;
   } 

   Nativo

   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. Nella tua app, chiama showDialog con il codice richiesto recuperato dal tuo server:

   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);
   }

   Nativo

   // 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 finestra di dialogo viene visualizzata sopra l'attività fornita. Quando l'utente ha chiuso la finestra di dialogo, l'attività viene completata con un codice di risposta.

6. (Facoltativo) Richiedi un altro token per visualizzare altre finestre di dialogo. Se effettui richieste standard, devi riscaldare di nuovo il fornitore di token per ottenere un nuovo verdetto.

Codici di integrità della finestra di dialogo

GET_LICENSED (Type Code 1)

Problema relativo al verdetto

Questa finestra di dialogo è adatta a due problemi:

• Accesso non autorizzato: appLicensingVerdict: "UNLICENSED". Ciò significa che l'account utente non ha diritto alla tua app, il che può accadere se l'utente l'ha installata tramite sideload o l'ha acquisita da un app store diverso da Google Play.
• App manomessa: appRecognitionVerdict: "UNRECOGNIZED_VERSION". Ciò significa che il file binario della tua app è stato modificato o non è una versione riconosciuta da Google Play.

Risoluzione

Puoi mostrare la finestra di dialogo GET_LICENSED per chiedere all'utente di scaricare l'app autentica da Google Play. Questa singola finestra di dialogo riguarda entrambi gli scenari:

• Per un utente senza licenza, gli concede una licenza Play. In questo modo, l'utente può ricevere gli aggiornamenti delle app da Google Play.
• Per un utente con una versione dell'app manomessa, lo guida all'installazione dell'app non modificata da Google Play.

Quando l'utente completa la finestra di dialogo, i controlli di integrità successivi restituiscono appLicensingVerdict: "LICENSED" e appRecognitionVerdict: "PLAY_RECOGNIZED".

UX di esempio

Figura 1. Finestra di dialogo GET_LICENSED di Google Play.

CLOSE_UNKNOWN_ACCESS_RISK (codice tipo 2)

Problema relativo al verdetto

Quando environmentDetails.appAccessRiskVerdict.appsDetected contiene "UNKNOWN_CAPTURING" o "UNKNOWN_CONTROLLING", significa che sul dispositivo sono in esecuzione app sconosciute che potrebbero acquisire la schermata o controllare il dispositivo.

Risoluzione

Puoi mostrare la finestra di dialogo CLOSE_UNKNOWN_ACCESS_RISK per chiedere all'utente di chiudere tutte le app sconosciute che potrebbero acquisire lo schermo o controllare il dispositivo. Se l'utente tocca il pulsante Close all, tutte queste app vengono chiuse.

UX di esempio

Figura 2. Finestra di dialogo per chiudere il rischio di accesso sconosciuto.

CLOSE_ALL_ACCESS_RISK (Type Code 3)

Problema relativo al verdetto

Quando environmentDetails.appAccessRiskVerdict.appsDetected contiene uno dei seguenti elementi: "KNOWN_CAPTURING", "KNOWN_CONTROLLING","UNKNOWN_CAPTURING" o "UNKNOWN_CONTROLLING", significa che sul dispositivo sono in esecuzione app che potrebbero acquisire lo schermo o controllare il dispositivo.

Risoluzione

Puoi mostrare la finestra di dialogo CLOSE_ALL_ACCESS_RISK per chiedere all'utente di chiudere tutte le app che potrebbero acquisire lo schermo o controllare il dispositivo. Se l'utente tocca il pulsante Close all, tutte queste app vengono chiuse sul dispositivo.

UX di esempio

Figura 3. Finestra di dialogo per chiudere tutti i rischi di accesso.