Finestre di dialogo di correzione

Questa pagina descrive come gestire i problemi relativi agli esiti di integrità.

Dopo aver richiesto un token di integrità, hai la possibilità di mostrare all'utente una finestra di dialogo di Google Play. Puoi mostrare la finestra di dialogo quando si verifica uno o più problemi con l'esito relativo all'integrità o se si è verificata un'eccezione durante una richiesta dell'API Integrity. Una volta chiusa la finestra di dialogo, puoi verificare che il problema sia stato risolto con un'altra richiesta di token di integrità. Se effettui richieste standard, devi eseguire di nuovo il warmup del fornitore di token per ottenere un nuovo esito.

Richiedere una finestra di dialogo di integrità per risolvere un problema relativo all'esito

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

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

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

    Unità

    // 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 tuo server, decripta 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 relativa alla 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;
    }

    Unità

    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) {
       return
    }
    
    // Create dialog request
    val dialogRequest = StandardIntegrityDialogRequest.builder()
            .setActivity(activity)
            .setTypeCode(showDialogType)
            .setStandardIntegrityResponse(StandardIntegrityResponse.TokenResponse(token))
            .build()
    
    // Call showDialog, the dialog will be shown on top of the provided activity
    // and the task will complete when the dialog is closed.
    val result: Task<Int> = standardIntegrityManager.showDialog(dialogRequest)
    
    // Handle response code, call the Integrity API again to confirm that the
    // verdict issue has been resolved. 

    Java

    // Show dialog as indicated by the server
    @Nullable Integer showDialogType = yourServerResponse.integrityDialogTypeCode();
    if (showDialogType == null) {
       return;
    }
    
    // Create dialog request
    StandardIntegrityDialogRequest dialogRequest =
        StandardIntegrityDialogRequest.builder()
            .setActivity(getActivity())
            .setTypeCode(showDialogTypeCode)
            .setStandardIntegrityResponse(new StandardIntegrityResponse.TokenResponse(token))
            .build();
    
    // Call showDialog, the dialog will be shown on top of the provided activity
    // and the task will complete when the dialog is closed.
    Task<Integer> result = standardIntegrityManager.showDialog(dialogRequest);
    
    // Handle response code, call the Integrity API again to confirm that the
    // verdict issue has been resolved.

    Unità

    // Initialize the V2 manager. Requires Play Integrity Unity Plugin v2.0.0 or
    // higher.
    var standardIntegrityManager = new StandardIntegrityManagerV2();
    IEnumerator ShowDialogCoroutine() {
      int showDialogType = yourServerResponse.IntegrityDialogTypeCode();
    
      PlayAsyncOperation<IntegrityDialogResponseCode, StandardIntegrityError> showDialogTask;
    
      using (var activity = UnityPlayerHelper.GetCurrentActivity())
      {
          // Create a dialog request
          var dialogRequest = new StandardIntegrityDialogRequest(tokenResponse, activity, showDialogType);
    
          // Call showDialog with the request, the dialog will be shown on top of the
          // provided activity and complete when the dialog is closed.
          showDialogTask = standardIntegrityManager.ShowDialog(dialogRequest);
      }
    
      // Wait for PlayAsyncOperation to complete.
      yield return showDialogTask;
    
      // Handle response code, call the Integrity API again to confirm that the
      // verdict issue been resolved.
    } 

    Unreal Engine

    // .h
    void MyClass::OnShowDialogCompleted(
      EStandardIntegrityErrorCode Error,
      EIntegrityDialogResponseCode Response)
    {
      // Handle response code, call the Integrity API again to confirm that the
      // verdict issue has 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){
    return;
    }
    
    /// Create dialog request
    StandardIntegrityDialogRequest* dialog_request;
    StandardIntegrityDialogRequest_create(&dialog_request);
    StandardIntegrityDialogRequest_setTypeCode(dialog_request, show_dialog_type);
    StandardIntegrityDialogRequest_setActivity(dialog_request, activity);
    StandardIntegrityDialogRequest_setStandardIntegrityToken(dialog_request,
                                                  token_response);
    
    /// Call showDialog with the dialog request. The dialog will be shown on top
    /// of the provided activity and complete when the dialog is closed by the
    /// user.
    StandardIntegrityDialogResponse* dialog_response;
    StandardIntegrityErrorCode error_code =
      StandardIntegrityManager_showDialog(dialog_request, &dialog_response);
    
    /// Use polling to wait for the async operation to complete. Note, the polling
    /// shouldn't block the thread where the StandardIntegrityManager is running.
    IntegrityDialogResponseCode response_code = INTEGRITY_DIALOG_RESPONSE_UNKNOWN;
    while (error_code == STANDARD_INTEGRITY_NO_ERROR) {
      error_code = StandardIntegrityDialogResponse_getResponseCode(dialog_response, &response_code);
      if(response_code != INTEGRITY_DIALOG_RESPONSE_UNKNOWN){
        break;
      }
    }
    
    /// Free memory
    StandardIntegrityDialogRequest_destroy(dialog_request);
    StandardIntegrityDialogResponse_destroy(dialog_response);
    
    /// Handle response code, call the Integrity API again to confirm that the
    /// verdict issues 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 eseguire di nuovo il warmup del fornitore di token per ottenere un nuovo esito.

Richiedere una finestra di dialogo di integrità per correggere un'eccezione lato client

Se una richiesta dell'API Integrity non va a buon fine con una StandardIntegrityException (API Standard) o IntegrityServiceException (API Classic) e l' eccezione è correggibile, puoi utilizzare le finestre di dialogo GET_INTEGRITY o GET_STRONG_INTEGRITY per correggere l'errore.

I seguenti passaggi descrivono come utilizzare la GET_INTEGRITY finestra di dialogo per correggere un errore lato client correggibile segnalato dall'API Integrity.

  1. Verifica che l'eccezione restituita da una richiesta dell'API Integrity sia correggibile.

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

    Unità

    private bool IsExceptionRemediable(StandardIntegrityError error) {
      // Check if the operation resulted in a remediable error
      if (error != null && error.ErrorCode != StandardIntegrityErrorCode.NoError && error.IsRemediable) {
          return true;
      }
      return false;
    }

    Nativo

    bool IsErrorRemediable(StandardIntegrityToken* token) {
      /// Check if the error associated with the token is remediable
      bool isRemediable = false;
      if(StandardIntegrityToken_getIsRemediable(response, &isRemediable) == STANDARD_INTEGRITY_NO_ERROR){
        return isRemediable;
      }
      return false;
    }
  2. Se l'eccezione è correggibile, richiedi la finestra di dialogo GET_INTEGRITY utilizzando l'eccezione restituita. La finestra di dialogo verrà visualizzata sopra l'attività fornita e l'attività restituita verrà completata con un codice di risposta dopo che l'utente avrà chiuso la finestra di dialogo.

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

    Unità

    // Initialize the V2 manager. Requires Play Integrity Unity Plugin v2.0.0 or
    // higher.
    var standardIntegrityManager = new StandardIntegrityManagerV2();
    IEnumerator ShowDialogToFixError(StandardIntegrityError error) {
      PlayAsyncOperation<IntegrityDialogResponseCode, StandardIntegrityError> showDialogTask;
    
      using (var activity = UnityPlayerHelper.GetCurrentActivity())
      {
          // Create a dialog request using the error
          var dialogRequest = new StandardIntegrityDialogRequest(error, activity, GET_INTEGRITY_DIALOG);
    
          // Request dialog
          showDialogTask = standardIntegrityManager.ShowDialog(dialogRequest);
      }
    
      // Wait for PlayAsyncOperation to complete.
      yield return showDialogTask;
    }

    Nativo

    private void showDialogToFixError(StandardIntegrityToken* token) {
      /// If the token request failed, and the underlying error is not fixable
      /// then return early
      if(isErrorRemediable(token)) {
        return;
      }
    
      /// Create dialog request
      StandardIntegrityDialogRequest* dialog_request;
      StandardIntegrityDialogRequest_create(&dialog_request);
      StandardIntegrityDialogRequest_setTypeCode(dialog_request,
                                         kGetIntegrityDialogTypeCode);
      StandardIntegrityDialogRequest_setActivity(dialog_request, activity);
      StandardIntegrityDialogRequest_setStandardIntegrityToken(dialog_request,
                                                      token_response);
    
      /// Call showDialog with the dialog request. The dialog will be shown on
      /// top of the provided activity and complete when the dialog is closed by
      /// the user.
      StandardIntegrityDialogResponse* dialog_response;
      StandardIntegrityErrorCode error_code =
          StandardIntegrityManager_showDialog(dialog_request, &dialog_response);
    
      /// Use polling to wait for the async operation to complete.
      /// Note, the polling shouldn't block the thread where the
      /// StandardIntegrityManager is running.
      IntegrityDialogResponseCode response_code = INTEGRITY_DIALOG_RESPONSE_UNKNOWN;
      while (error_code == STANDARD_INTEGRITY_NO_ERROR) {
          error_code = StandardIntegrityDialogResponse_getResponseCode(response, &response_code);
          if(response_code != INTEGRITY_DIALOG_RESPONSE_UNKNOWN){
            break;
          }
      }
    
      /// Free memory
      StandardIntegrityDialogRequest_destroy(dialog_request);
      StandardIntegrityDialogResponse_destroy(dialog_response);
    
    }
  3. Se il codice di risposta restituito indica un esito positivo, la successiva richiesta di un token di integrità dovrebbe andare a buon fine senza eccezioni. Se effettui richieste standard, devi eseguire di nuovo il warmup del fornitore di token per ottenere un nuovo esito.

Codici delle finestre di dialogo di integrità

GET_LICENSED (codice tipo 1)

Problema relativo all'esito

Questa finestra di dialogo è appropriata per 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 eseguita 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.

Correzione

Puoi mostrare la finestra di dialogo GET_LICENSED per chiedere all'utente di acquisire l'app originale da Google Play. Questa singola finestra di dialogo risolve 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 manomessa dell'app, 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".

Esempio di UX

Figura 1. Finestra di dialogo di Google Play GET_LICENSED.

CLOSE_UNKNOWN_ACCESS_RISK (codice tipo 2)

Problema relativo all'esito

Quando environmentDetails.appAccessRiskVerdict.appsDetected contiene "UNKNOWN_CAPTURING" o "UNKNOWN_CONTROLLING", significa che sul dispositivo sono in esecuzione altre app (non installate da Google Play o precaricate nella partizione di sistema dal produttore del dispositivo) che potrebbero acquisire lo schermo o controllare il dispositivo.

Correzione

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.

Esempio di UX

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

CLOSE_ALL_ACCESS_RISK (codice tipo 3)

Problema relativo all'esito

Quando environmentDetails.appAccessRiskVerdict.appsDetected contiene uno dei seguenti valori: "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.

Correzione

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.

Esempio di UX

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

GET_INTEGRITY (codice tipo 4)

Problema relativo all'esito

Questa finestra di dialogo è appropriata per uno dei seguenti problemi:

  • Integrità del dispositivo debole: quando deviceRecognitionVerdict non contiene MEETS_DEVICE_INTEGRITY, il dispositivo potrebbe non essere un dispositivo Android originale e certificato. Ciò può accadere, ad esempio, se il bootloader del dispositivo è sbloccato o se il sistema operativo Android caricato non è un'immagine del produttore certificata.

  • 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 eseguita 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.

  • Eccezioni lato client: quando si verifica un'eccezione correggibile durante una richiesta API dell'API Integrity. Le eccezioni correggibili sono eccezioni dell'API Integrity con codici di errore come PLAY_SERVICES_VERSION_OUTDATED, NETWORK_ERROR, PLAY_SERVICES_NOT_FOUND, e così via. Puoi utilizzare il metodo exception.isRemediable() per verificare se una finestra di dialogo può correggere un'eccezione.

Correzione

La finestra di dialogo GET_INTEGRITY è progettata per semplificare l'esperienza dell'utente gestendo più passaggi di correzione in un unico flusso continuo. In questo modo, l'utente non deve interagire con più finestre di dialogo separate per risolvere problemi diversi.

Quando richiedi la finestra di dialogo, questa rileva automaticamente quali problemi relativi all'esito di destinazione sono presenti e fornisce i passaggi di correzione appropriati. Ciò significa che una singola richiesta di finestra di dialogo può risolvere più problemi contemporaneamente, tra cui:

  • Integrità del dispositivo: se viene rilevato un problema di integrità del dispositivo, la finestra di dialogo guiderà l'utente a migliorare lo stato di sicurezza del dispositivo per soddisfare i requisiti per un esito MEETS_DEVICE_INTEGRITY.
  • Integrità dell'app: se vengono rilevati problemi come l'accesso non autorizzato o la manomissione dell'app, la finestra di dialogo indirizzerà gli utenti ad acquisire l'app dal Play Store per risolverli.
  • Eccezioni lato client: la finestra di dialogo verifica e tenta di risolvere eventuali problemi sottostanti che hanno causato un'eccezione dell'API Integrity. Ad esempio, potrebbe chiedere all'utente di aggiornare una versione obsoleta di Google Play Services.

Esempio di UX

Figura 4. Flusso di correzione degli errori di rete della finestra di dialogo GET_INTEGRITY

GET_STRONG_INTEGRITY (codice tipo 5)

Problema relativo all'esito

Questa finestra di dialogo è progettata per risolvere tutti gli stessi problemi di GET_INTEGRITY, con la funzionalità aggiuntiva di risolvere i problemi che impediscono a un dispositivo di ricevere un esito MEETS_STRONG_INTEGRITY e risolvere i problemi relativi all'esito di Play Protect.

Correzione

GET_STRONG_INTEGRITY è progettata per semplificare l'esperienza dell'utente gestendo più passaggi di correzione in un unico flusso continuo. La finestra di dialogo verifica automaticamente la presenza di problemi di integrità applicabili all'indirizzo, tra cui:

  • Integrità del dispositivo: se viene rilevato un problema di integrità del dispositivo, la finestra di dialogo guiderà l'utente a migliorare lo stato di sicurezza del dispositivo per soddisfare i requisiti per un esito MEETS_STRONG_INTEGRITY.
  • Stato di Play Protect: se playProtectVerdict indica un problema, la finestra di dialogo guiderà l'utente a risolverlo:

    • Se Play Protect è disattivato (playProtectVerdict == POSSIBLE_RISK), la finestra di dialogo chiederà all'utente di attivarlo ed eseguire una scansione di tutte le app sul dispositivo.
    • Se vengono rilevate app dannose (playProtectVerdict == MEDIUM_RISK o HIGH_RISK), la finestra di dialogo indirizzerà l'utente a disinstallarle utilizzando Google Play Protect.
  • Integrità dell'app: se vengono rilevati problemi come l'accesso non autorizzato o la manomissione dell'app, la finestra di dialogo chiederà all'utente di acquisire l'app dal Play Store per risolvere il problema.

  • Eccezioni lato client: la finestra di dialogo tenta anche di risolvere eventuali problemi sottostanti che hanno causato un'eccezione dell'API Integrity. Ad esempio, potrebbe chiedere all'utente di attivare Google Play Services se risulta disattivato. Le eccezioni correggibili sono eccezioni dell'API Integrity con codici di errore come PLAY_SERVICES_VERSION_OUTDATED, NETWORK_ERROR o PLAY_SERVICES_NOT_FOUND. Puoi utilizzare il metodo exception.isRemediable() per verificare se una finestra di dialogo può correggere un errore.

Esempio di UX

Figura 5. Finestra di dialogo GET_STRONG_INTEGRITY che aggiorna Play Services.