Questa pagina è stata tradotta dall'API Cloud Translation.

Finestre di dialogo di correzione

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

Dopo aver 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 verificano uno o più problemi con il verdetto di 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 riattivare il fornitore di token per ottenere un nuovo verdetto.

Richiedere una finestra di dialogo sull'integrità per risolvere un problema relativo al verdetto

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

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.

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

Sul server, decrittografa il token di integrità e controlla il campo appLicensingVerdict. Potrebbe avere un aspetto simile al seguente:
```
// Licensing issue
{
  ...
  "accountDetails": {
      "appLicensingVerdict": "UNLICENSED"
  }
}
```

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

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

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.
(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.

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

Se una richiesta API Integrity non va a buon fine e viene visualizzato un messaggio di errore StandardIntegrityException (API Standard) o IntegrityServiceException (API classica) e l'eccezione è correggibile, puoi utilizzare le finestre di dialogo GET_INTEGRITY o GET_STRONG_INTEGRITY per risolvere l'errore.

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

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

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 viene completata con un codice di risposta dopo che l'utente chiude 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);
}

Se il codice di risposta restituito indica un esito positivo, la richiesta successiva di un token di integrità dovrebbe riuscire senza eccezioni. Se effettui richieste standard, devi riattivare 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 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.

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.

GET_INTEGRITY (codice tipo 4)

Problema relativo al verdetto

Questa finestra di dialogo è adatta 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 con certificazione Play Protect. Ciò può accadere, ad esempio, se il bootloader del dispositivo è sbloccato o se il sistema operativo Android caricato non è un'immagine certificata del produttore.
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 caricata lateralmente 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 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, ecc. Puoi utilizzare il metodo exception.isRemediable() per verificare se un'eccezione è correggibile dalla finestra di dialogo.

Risoluzione

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, rileva automaticamente quali problemi di verdetto sono presenti e fornisce i passaggi di correzione appropriati. Ciò significa che una singola richiesta 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 verdetto MEETS_DEVICE_INTEGRITY.
Integrità dell'app: se vengono rilevati problemi come accesso non autorizzato o 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.

UX di esempio

**Figura 4.** Flusso di correzione dell'errore di rete della finestra di dialogo GET_INTEGRITY

GET_STRONG_INTEGRITY (codice tipo 5)

Problema relativo al verdetto

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

Risoluzione

GET_STRONG_INTEGRITY è progettato per semplificare l'esperienza dell'utente gestendo più passaggi di correzione in un unico flusso continuo. La finestra di dialogo controlla automaticamente la presenza di problemi di integrità applicabili a un 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 verdetto 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 alla disinstallazione tramite Google Play Protect.
Integrità dell'app: se vengono rilevati problemi come accesso non autorizzato o manomissione dell'app, la finestra di dialogo chiederà all'utente di scaricare 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 un errore è corregibile dalla finestra di dialogo.

UX di esempio

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

Indietro

Gestire i codici di errore

Avanti

Strumenti aggiuntivi e assistenza

Finestre di dialogo di correzione Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Richiedere una finestra di dialogo sull'integrità per risolvere un problema relativo al verdetto

Kotlin

Java

Unity

Unreal Engine

Nativo

Kotlin

Java

Unity

Unreal Engine

Nativo

Kotlin

Java

Unity

Unreal Engine

Nativo

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

Kotlin

Java

Kotlin

Java

Codici di integrità della finestra di dialogo

GET_LICENSED (Type Code 1)

Problema relativo al verdetto

Risoluzione

UX di esempio

CLOSE_UNKNOWN_ACCESS_RISK (codice tipo 2)

Problema relativo al verdetto

Risoluzione

UX di esempio

CLOSE_ALL_ACCESS_RISK (Type Code 3)

Problema relativo al verdetto

Risoluzione

UX di esempio

GET_INTEGRITY (codice tipo 4)

Problema relativo al verdetto

Risoluzione

UX di esempio

GET_STRONG_INTEGRITY (codice tipo 5)

Problema relativo al verdetto

Risoluzione

UX di esempio

Finestre di dialogo di correzione