Integrar o Google Cloud Fraud Defense a apps Android

É possível integrar o Google Cloud Fraud Defense aos apps Android para avaliar a integridade do dispositivo cliente e proteger as interações confidenciais do usuário em dispositivos móveis.

O SDK usa reflexão e código dinâmico para permitir a modificação e o refinamento do sistema de detecção nos aplicativos/SDKs implantados. O conjunto de classes disponíveis no sistema é restrito a uma lista controlada para evitar interferência no aplicativo.

Importante: observe a política de descontinuação e encerramento e planeje o upgrade do SDK regularmente.

Antes de começar

1. Prepare seu ambiente para o Google Cloud Fraud Defense.

2. Crie uma chave de reCAPTCHA para a plataforma de app Android.

   Como alternativa, você pode copiar o ID de uma chave reCAPTCHA para Android seguindo uma destas etapas:

   • Para copiar o ID de uma chave do console doGoogle Cloud , faça o seguinte:

     1. Acesse a página do Google Cloud Fraud Defense.

        Acessar o Google Cloud Fraud Defense

     2. Selecione a guia Chaves.
     3. Na lista de chaves reCAPTCHA, encontre a chave que você quer copiar e clique em .
   • Para copiar o ID de uma chave usando a API REST, use o método projects.keys.list.
   • Para copiar o ID de uma chave usando a CLI gcloud, use o comando gcloud recaptcha keys list.

Preparar o ambiente do Android

Aviso: não migre para o SDK do Android 18.2.0, porque isso pode fazer com que o app não funcione devido a alguns erros internos. Para evitar esses problemas, migre diretamente para o SDK do Android 18.2.1 ou mais recente. Para mais detalhes, consulte o relatório de problemas no GitHub.

Android nativo

1. Prepare seu ambiente de desenvolvimento fazendo o download e instalando a versão mais recente do Android Studio.

2. Verifique se você tem um app com o valor mínimo do SDK do Android definido como API 23: Android 6.0 (Marshmallow).

3. Se você estiver criando um novo app para dispositivos móveis, crie um aplicativo de teste iniciando um novo projeto do Android Studio:

   1. Selecione Empty Activity. Se você quiser usar o Jetpack Compose no seu app, escolha Empty Compose Activity.
   2. Defina a linguagem como kotlin.
   3. Defina o valor mínimo do SDK como API 23: Android 6.0 (Marshmallow).

4. Verifique se o repositório Maven do Google google() está na lista de repositórios no arquivo build.gradle no nível do projeto, conforme mostrado no snippet a seguir:

   allprojects {
       repositories {
           google()
       }
   }
   

   Para mais informações, consulte a seção Repositório Maven do Google.

5. Para adicionar a dependência da API reCAPTCHA, adicione a seguinte regra de build à seção dependencies do arquivo build.gradle no nível do app.

     implementation 'com.google.android.recaptcha:recaptcha:18.9.4'
   

   Para mais informações sobre como adicionar dependências em apps Android, consulte Adicionar dependências de build.

6. Adicione a permissão de Internet entre a primeira tag <manifest> e a primeira tag <application> no manifesto do aplicativo (por exemplo, AndroidManifest.xml). Essa permissão é necessária porque a API reCAPTCHA envolve operações de rede.

   <manifest ...>
   
       <uses-permission android:name="android.permission.INTERNET" />
   
       <application ...>
       ...
     </application>
   </manifest>
   

7. Se você quiser usar bibliotecas AndroidX no seu novo projeto, compile o SDK para o Android 9.0 ou versão mais recente e adicione o seguinte snippet de código ao gradle.properties.

   android.useAndroidX=true
   android.enableJetifier=true
   

   Para mais informações, consulte Como migrar para o AndroidX.

Flutter

Para instruções detalhadas sobre como usar o reCAPTCHA pelo Flutter, consulte a documentação do Flutter.

React Native

Para instruções detalhadas sobre como usar o reCAPTCHA pelo React Native, consulte a documentação do React Native.

Integrar o reCAPTCHA ao seu app Android

1. Instancie um cliente usando a chave reCAPTCHA (KEY_ID) que você criou para o app Android.

   Observação: use o cliente reCAPTCHA apenas uma vez durante o ciclo de vida do app.

   Kotlin com fetchClient

   O método fetchClient retorna um cliente imediatamente e começa a inicializar o SDK em segundo plano. Ele tenta novamente a comunicação com o servidor do reCAPTCHA em caso de falhas de rede.

   class CustomApplication : Application() {
   
       private lateinit var recaptchaClient: RecaptchaClient
       // we recommend initializing in a ViewModel
       private val recaptchaScope = CoroutineScope(Dispatchers.IO)
   
       override fun onCreate() {
         super.onCreate()
         initializeRecaptchaClient()
       }
   
       private fun initializeRecaptchaClient() {
         recaptchaScope.launch {
           try {
             recaptchaClient = Recaptcha.fetchClient(this@CustomApplication, "KEY_ID")
           } catch(e: RecaptchaException) {
             // Handle errors ...
             // See "Handle errors" section
           }
         }
       }
   }
   

   Java com fetchClient

   public final class CustomApplication extends Application {
     @Nullable private RecaptchaTasksClient recaptchaTasksClient = null;
   
     @Override
     public void onCreate() {
       super.onCreate();
       initializeRecaptchaClient();
     }
   
     private void initializeRecaptchaClient() {
       Recaptcha
         .fetchTaskClient(this, "KEY_ID")
         .addOnSuccessListener(
             this,
             new OnSuccessListener<RecaptchaTasksClient>() {
               @Override
               public void onSuccess(RecaptchaTasksClient client) {
                 CustomApplication.this.recaptchaTasksClient = client;
               }
             })
         .addOnFailureListener(
             this,
             new OnFailureListener() {
               @Override
               public void onFailure(@NonNull Exception e) {
                 // Handle errors ...
                 // See "Handle errors" section
               }
             });
     }
   }
   

   A inicialização do SDK pode levar vários segundos para ser concluída. Para reduzir essa latência, inicialize o cliente o mais cedo possível, como durante a chamada onCreate() de uma classe Application personalizada. Não bloqueie elementos da interface no SDK do reCAPTCHA.

   Observação: se a API transmitir uma instância de ApiException para onFailure(), será necessário gerenciar cada código de status possível que pode ser extraído usando getStatusCode(). Para mais informações, consulte Tratar erros.

2. Para cada ação do app protegida pelo reCAPTCHA, chame o método execute transmitindo um RecaptchaAction. A biblioteca do reCAPTCHA oferece um conjunto integrado de ações e, se necessário, você pode criar ações personalizadas.

   O snippet de código abaixo mostra como usar execute para proteger uma ação LOGIN.

   Kotlin

   private fun executeLoginAction() {
     recaptchaScope.launch {
       recaptchaClient
         .execute(RecaptchaAction.LOGIN)
         .onSuccess { token ->
           // Handle success ...
           // See "What's next" section for instructions
           // about handling tokens.
         }
         .onFailure { exception ->
           // Handle errors ...
         }
     }
   }
   

   Java

   private void executeLoginAction(View v) {
     assert recaptchaTasksClient != null;
     recaptchaTasksClient
       .executeTask(RecaptchaAction.LOGIN)
       .addOnSuccessListener(
           this,
           new OnSuccessListener<String>() {
             @Override
             public void onSuccess(String token) {
               // Handle success ...
               // See "What's next" section for instructions
               // about handling tokens.
             }
           })
       .addOnFailureListener(
           this,
           new OnFailureListener() {
             @Override
             public void onFailure(@NonNull Exception e) {
               // Handle errors ...
             }
           });
   }
   

Observação: a Google Play Store exige que você preencha o formulário de Segurança dos dados do Google Play antes de fazer upload do app. Consulte os requisitos de divulgação de dados do Google Play para encontrar as informações necessárias sobre o SDK do Android do reCAPTCHA e preencher o formulário de Segurança dos dados.

Migrar do método getClient para o método fetchClient

O método fetchClient retorna um RecaptchaClient que tenta fazer a inicialização novamente em caso de falhas de rede. Se o app não tiver acesso à rede quando o cliente for criado, ele vai continuar tentando e será inicializado quando uma rede for adquirida.

Se você chamar execute(timeout) e o cliente ainda não estiver pronto, ele vai tentar fazer a inicialização antes de retornar um token ou um RecaptchaErrorCode.

O exemplo a seguir mostra como migrar de getClient para fetchClient.

Kotlin

// Migrate from getClient
private fun initializeWithGetClient() {
  recaptchaScope.launch {
    Recaptcha.getClient(application, "KEY_ID")
      .onSuccess { client ->
        recaptchaClient = client
      }
      .onFailure { exception ->
        // Handle errors ...
      }
  }
}

 // Migrate to fetchClient
private fun initializeWithFetchClient() {
  recaptchaScope.launch {
    try {
      recaptchaClient = Recaptcha.fetchClient(application, "KEY_ID")
    } catch(e: RecaptchaException){
      // Handle errors ...
    }
  }
}

Java

  // Migrate from getTasksClient
  private void initializeWithGetTasksClient() {
    Recaptcha
      .getTasksClient(getApplication(), "KEY_ID")
      .addOnSuccessListener(
          this,
          new OnSuccessListener<RecaptchaTasksClient>() {
            @Override
            public void onSuccess(RecaptchaTasksClient client) {
              recaptchaTasksClient = client;
            }
          })
      .addOnFailureListener(
          this,
          new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception e) {
              // Handle errors ...
            }
          });
  }

  // Migrate to fetchTaskClient
  private void initializeWithFetchTaskClient() {
    Recaptcha
      .fetchTaskClient(getApplication(), "KEY_ID")
      .addOnSuccessListener(
          this,
          new OnSuccessListener<RecaptchaTasksClient>() {
            @Override
            public void onSuccess(RecaptchaTasksClient client) {
              recaptchaTasksClient = client;
            }
          })
      .addOnFailureListener(
          this,
          new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception e) {
              // Handle errors ...
            }
          });
  }

Definir um tempo limite para chamadas de API

É possível especificar um valor de tempo limite para as APIs execute usando a propriedade withTimeout.

Kotlin

• Defina o tempo limite ao chamar execute.

      recaptchaScope.launch {
        recaptchaClient
          .execute(RecaptchaAction.LOGIN, timeout = 10000L)
          .onSuccess { token ->
            // Handle success ...
            // See "What's next" section for instructions
            // about handling tokens.
          }
          .onFailure { exception ->
            // Handle errors ...
            // See "Handle errors" section
          }
      }
  

  Esse snippet de código define o tempo limite de execute como 10 segundos.

Java

• Defina o tempo limite ao chamar execute.

    recaptchaTasksClient
      .executeTask(RecaptchaAction.custom("redeem"), 10000L)
      .addOnSuccessListener(
          this,
          new OnSuccessListener<String>() {
            @Override
            public void onSuccess(String token) {
              // Handle success ...
              // See "What's next" section for instructions
              // about handling tokens.
            }
          })
      .addOnFailureListener(
          this,
          new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception e) {
              // Handle errors ...
              // See "Handle errors" section
            }
          });
  

  Esse snippet de código define o tempo limite de execute como 10 segundos.

Tratar erros

Se o app não conseguir se comunicar com o serviço reCAPTCHA, pode ser porque a API encontrou um erro. Adicione uma lógica ao app para lidar com esses erros de maneira adequada.

Para mais detalhes sobre mitigações de erros comuns da API, consulte RecaptchaErrorCode.

Referência da API

Para uma referência completa da API reCAPTCHA para Android, consulte com.google.android.recaptcha.

A seguir

• Para avaliar o token de resposta do reCAPTCHA, crie uma avaliação.

  Observação: os tokens de resposta do reCAPTCHA são avaliados e anotados no servidor de back-end, não no dispositivo móvel.