Esta página foi traduzida pela API Cloud Translation.

Caixas de diálogo de correção

Nesta página, descrevemos como lidar com problemas com vereditos de integridade.

Depois que um token de integridade é solicitado, você pode mostrar uma caixa de diálogo do Google Play para o usuário. Você pode mostrar a caixa de diálogo quando houver um ou mais problemas com o veredito de integridade ou se uma exceção ocorrer durante uma solicitação da API Integrity. Depois que a caixa de diálogo for fechada, confira se o problema foi corrigido fazendo outra solicitação de token de integridade. Se você fizer solicitações padrão, será necessário ativar o provedor de token novamente para receber um novo veredito.

Solicitar uma caixa de diálogo de integridade para corrigir um problema de veredito

Quando o cliente solicita um token de integridade, é possível usar o método oferecido no StandardIntegrityToken (API padrão) e no IntegrityTokenResponse (API clássica): showDialog(Activity activity, int integrityDialogTypeCode).

As etapas abaixo descrevem como usar a API Play Integrity para mostrar uma caixa de diálogo de correção usando o código da caixa de diálogo GET_LICENSED. Outros códigos de caixa de diálogo que seu app pode solicitar estão listados após esta seção.

Solicite um token de integridade do app e o envie ao servidor. Você pode usar a solicitação padrão ou clássica.

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

No servidor, descriptografe o token de integridade e confira o campo appLicensingVerdict. Ele poderia ficar assim:

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

Se o token contiver appLicensingVerdict: "UNLICENSED", responda ao cliente do app, solicitando que ele mostre a caixa de diálogo de licenciamento:

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

No seu app, chame showDialog com o código solicitado extraído do seu servidor:

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

A caixa de diálogo aparece na parte de cima da atividade fornecida. Quando o usuário fecha a caixa de diálogo, a tarefa é concluída com um código de resposta.
(Opcional) Solicite outro token para mostrar outras caixas de diálogo. Se você fizer solicitações padrão, será necessário ativar o provedor de token novamente para receber um novo veredito.

Solicitar uma caixa de diálogo de integridade para corrigir uma exceção do lado do cliente

Se uma solicitação da API Integrity falhar com um StandardIntegrityException (API padrão) ou IntegrityServiceException (API clássica) e a exceção puder ser corrigida, use as caixas de diálogo GET_INTEGRITY ou GET_STRONG_INTEGRITY para corrigir o erro.

As etapas a seguir descrevem como usar a caixa de diálogo GET_INTEGRITY para corrigir um erro remediável do lado do cliente informado pela API Integrity.

Verifique se a exceção retornada de uma solicitação da API Integrity pode ser corrigida.

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 a exceção puder ser corrigida, solicite a caixa de diálogo GET_INTEGRITY usando a exceção retornada. A caixa de diálogo será exibida sobre a atividade fornecida, e a tarefa retornada será concluída com um código de resposta depois que o usuário fechar a caixa de diálogo.

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 o código de resposta retornado indicar sucesso, a próxima solicitação de um token de integridade será bem-sucedida sem exceções. Se você fizer solicitações padrão, será necessário ativar o provedor de token novamente para receber um novo veredito.

Códigos de caixa de diálogo de integridade

GET_LICENSED (código de tipo 1)

Problema de veredito

Essa caixa de diálogo é adequada para dois problemas:

Acesso não autorizado: appLicensingVerdict: "UNLICENSED". Isso significa que a conta de usuário não tem direito de acesso ao app, o que pode acontecer se o usuário fez sideload ou adquiriu o app em uma loja diferente do Google Play.
App adulterado: appRecognitionVerdict: "UNRECOGNIZED_VERSION". Isso significa que o binário do app foi modificado ou não é uma versão reconhecida pelo Google Play.

Correção

Você pode mostrar a caixa de diálogo GET_LICENSED para pedir que o usuário adquira o app original no Google Play. Essa única caixa de diálogo aborda os dois cenários:

Para um usuário sem licença, ela concede uma licença do Google Play. Isso permite que o usuário receba atualizações de apps do Google Play.
Para um usuário com uma versão adulterada do app, ele orienta a instalação do app não modificado no Google Play.

Quando o usuário conclui a caixa de diálogo, as verificações de integridade subsequentes retornam appLicensingVerdict: "LICENSED" e appRecognitionVerdict: "PLAY_RECOGNIZED".

Exemplo de UX

**Figura 1**. Caixa de diálogo GET_LICENSED do Google Play.

CLOSE_UNKNOWN_ACCESS_RISK (código de tipo 2)

Problema de veredito

Quando environmentDetails.appAccessRiskVerdict.appsDetected contém "UNKNOWN_CAPTURING" ou "UNKNOWN_CONTROLLING", significa que há outros apps (não instalados pelo Google Play ou pré-carregados na partição do sistema pelo fabricante do dispositivo) em execução no dispositivo que podem estar capturando a tela ou controlando o dispositivo.

Correção

Você pode mostrar a caixa de diálogo CLOSE_UNKNOWN_ACCESS_RISK para pedir que o usuário feche todos os apps desconhecidos que podem estar capturando a tela ou controlando o dispositivo. Se o usuário tocar no botão Close all, todos esses apps serão fechados.

Exemplo de UX

**Figura 2**. Caixa de diálogo para fechar o risco de acesso desconhecido.

CLOSE_ALL_ACCESS_RISK (código de tipo 3)

Problema de veredito

Quando environmentDetails.appAccessRiskVerdict.appsDetected contém "KNOWN_CAPTURING", "KNOWN_CONTROLLING","UNKNOWN_CAPTURING" ou "UNKNOWN_CONTROLLING", significa que há apps em execução no dispositivo que podem estar capturando a tela ou controlando o dispositivo.

Correção

Você pode mostrar a caixa de diálogo CLOSE_ALL_ACCESS_RISK para pedir que o usuário feche todos os apps que podem estar capturando a tela ou controlando o dispositivo. Se o usuário tocar no botão Close all, todos esses apps serão fechados no dispositivo.

Exemplo de UX

**Figura 3**. Caixa de diálogo para fechar todos os riscos de acesso.

GET_INTEGRITY (código de tipo 4)

Problema de veredito

Essa caixa de diálogo é adequada para qualquer um dos seguintes problemas:

Integridade fraca do dispositivo: quando o deviceRecognitionVerdict não contém MEETS_DEVICE_INTEGRITY, o dispositivo pode não ser um dispositivo genuíno com tecnologia Android certificado pelo Play Protect. Isso pode acontecer, por exemplo, se o carregador de inicialização do dispositivo estiver desbloqueado ou se o SO Android carregado não for uma imagem de fabricante certificada.
Acesso não autorizado: appLicensingVerdict: "UNLICENSED". Isso significa que a conta de usuário não tem direito de acesso ao seu app, o que pode acontecer se o usuário fez sideload ou adquiriu o app em uma loja diferente do Google Play.
App adulterado: appRecognitionVerdict: "UNRECOGNIZED_VERSION". Isso significa que o binário do app foi modificado ou não é uma versão reconhecida pelo Google Play.
Exceções do lado do cliente: quando uma exceção remediável ocorre durante uma solicitação da API Integrity. As exceções corrigíveis são exceções da API Integrity com códigos de erro como PLAY_SERVICES_VERSION_OUTDATED, NETWORK_ERROR, PLAY_SERVICES_NOT_FOUND, etc. Use o método exception.isRemediable() para verificar se uma exceção pode ser corrigida pela caixa de diálogo.

Correção

A caixa de diálogo GET_INTEGRITY foi projetada para simplificar a experiência do usuário ao processar várias etapas de correção em um único fluxo contínuo. Isso evita que o usuário precise interagir com várias caixas de diálogo separadas para corrigir problemas diferentes.

Quando você solicita a caixa de diálogo, ela detecta automaticamente quais dos problemas de veredicto segmentados estão presentes e fornece as etapas de correção adequadas. Isso significa que uma única solicitação de diálogo pode resolver vários problemas de uma só vez, incluindo:

Integridade do dispositivo: se um problema de integridade do dispositivo for detectado, a caixa de diálogo vai orientar o usuário a melhorar o status de segurança do dispositivo para atender aos requisitos de um veredito MEETS_DEVICE_INTEGRITY.
Integridade do app: se forem detectados problemas como acesso não autorizado ou violação do app, a caixa de diálogo vai direcionar os usuários para adquirir o app na Play Store e corrigir os problemas.

Exceções do lado do cliente: a caixa de diálogo verifica e tenta resolver problemas subjacentes que causaram uma exceção da API Integrity. Por exemplo, ele pode pedir que o usuário atualize uma versão desatualizada do Google Play Services.

Exemplo de UX

**Figura 4**. Fluxo de correção de erros de rede da caixa de diálogo GET_INTEGRITY

GET_STRONG_INTEGRITY (código de tipo 5)

Problema de veredito

Essa caixa de diálogo foi projetada para corrigir todos os mesmos problemas que o GET_INTEGRITY resolve, com a capacidade adicional de corrigir problemas que impedem um dispositivo de receber um veredito MEETS_STRONG_INTEGRITY e corrigir problemas de veredito do Play Protect.

Correção

O GET_STRONG_INTEGRITY foi criado para simplificar a experiência do usuário ao processar várias etapas de correção em um único fluxo contínuo. A caixa de diálogo verifica automaticamente problemas de integridade aplicáveis a um endereço, incluindo:

Integridade do dispositivo: se um problema de integridade do dispositivo for detectado, a caixa de diálogo vai orientar o usuário a melhorar o status de segurança do dispositivo para atender aos requisitos de um veredito MEETS_STRONG_INTEGRITY.
Status do Play Protect: se o playProtectVerdict indicar um problema, a caixa de diálogo vai orientar o usuário a corrigir:
- Se o Play Protect estiver desativado (playProtectVerdict == POSSIBLE_RISK), a caixa de diálogo vai pedir que o usuário ative o recurso e faça uma verificação de todos os apps no dispositivo.
- Se apps nocivos forem detectados (playProtectVerdict == MEDIUM_RISK ou HIGH_RISK), a caixa de diálogo vai orientar o usuário a desinstalá-los usando o Google Play Protect.
Integridade do app: se forem detectados problemas como acesso não autorizado ou adulteração do app, a caixa de diálogo vai pedir que o usuário adquira o app na Play Store para corrigir o problema.
Exceções do lado do cliente: a caixa de diálogo também tenta resolver problemas que causaram uma exceção da API Integrity. Por exemplo, ele pode pedir que o usuário ative o Google Play Services se ele estiver desativado. Exceções corrigíveis são exceções da API Integrity com códigos de erro como PLAY_SERVICES_VERSION_OUTDATED, NETWORK_ERROR ou PLAY_SERVICES_NOT_FOUND. Você pode usar o método exception.isRemediable() para verificar se um erro pode ser corrigido pela caixa de diálogo.

Exemplo de UX

**Figura 5**. Caixa de diálogo GET_STRONG_INTEGRITY atualizando o Google Play Services.

Gerenciar códigos de erro

Avançar

Mais ferramentas e suporte

Caixas de diálogo de correção Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Solicitar uma caixa de diálogo de integridade para corrigir um problema de veredito

Kotlin

Java

Unity

Unreal Engine

Nativo

Kotlin

Java

Unity

Unreal Engine

Nativo

Kotlin

Java

Unity

Unreal Engine

Nativo

Solicitar uma caixa de diálogo de integridade para corrigir uma exceção do lado do cliente

Kotlin

Java

Kotlin

Java

Códigos de caixa de diálogo de integridade

GET_LICENSED (código de tipo 1)

Problema de veredito

Correção

Exemplo de UX

CLOSE_UNKNOWN_ACCESS_RISK (código de tipo 2)

Problema de veredito

Correção

Exemplo de UX

CLOSE_ALL_ACCESS_RISK (código de tipo 3)

Problema de veredito

Correção

Exemplo de UX

GET_INTEGRITY (código de tipo 4)

Problema de veredito

Correção

Exemplo de UX

GET_STRONG_INTEGRITY (código de tipo 5)

Problema de veredito

Correção

Exemplo de UX

Caixas de diálogo de correção