Integrar o reCAPTCHA a apps Android

Esta página explica como integrar o reCAPTCHA ao seu app Android.

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.

Antes de começar

1. Prepare seu ambiente para o reCAPTCHA.

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

   Como alternativa, é possível copiar o ID de uma chave do reCAPTCHA para Android seguindo uma destas etapas:

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

     1. Acesse a página do reCAPTCHA.

        Acessar o reCAPTCHA

     2. Na lista de chaves reCAPTCHA, mantenha o ponteiro do mouse sobre a chave que você quer copiar e clique em content_copy .
   • Para copiar o ID de uma chave atual usando a API REST, use o método projects.keys.list.
   • Para copiar o ID de uma chave atual usando a CLI gcloud, use o comando gcloud recaptcha keys list.

Preparar o ambiente Android

Integrar o reCAPTCHA ao seu app Android

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

   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 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(application, "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
     protected void onCreate() {
       super.onCreate();
       initializeRecaptchaClient();
     }
   
     private void initializeRecaptchaClient() {
       Recaptcha
         .fetchTaskClient(getApplication(), "KEY_ID")
         .addOnSuccessListener(
             this,
             new OnSuccessListener<RecaptchaTasksClient>() {
               @Override
               public void onSuccess(RecaptchaTasksClient client) {
                 MainActivity.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 quanto antes, como durante a chamada onCreate() de uma classe Application personalizada. Não faça com que UI elementos da interface bloqueiem o SDK reCAPTCHA.

2. Para cada ação do app protegida com o reCAPTCHA, chame o método execute transmitindo um RecaptchaAction. O reCAPTCHA oferece um conjunto integrado de ações e, se necessário, é possível criar ações personalizadas.

   O snippet de código a seguir 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 ...
             }
           });
   }
   

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

O método fetchClient retorna um RecaptchaClient que tenta 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 tentará inicializar antes de retornar um token ou um RecaptchaErrorCode.

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

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

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

Tratar erros

Se o app não conseguir se comunicar com o serviço reCAPTCHA, talvez seja porque a API encontrou um erro. É necessário adicionar lógica ao app para lidar com esses erros.

Para mais detalhes sobre mitigações de erros comuns de 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 reCAPTCHA, crie uma avaliação.