Integre o reCAPTCHA com apps Android

Esta página explica como integrar o reCAPTCHA na sua app Android.

O SDK usa a reflexão e o código dinâmico para permitir a modificação e o refinamento do sistema de deteção nas aplicações/SDKs implementados existentes. O conjunto de classes disponíveis no sistema está restrito a uma lista controlada para evitar interferências com a aplicação.

Antes de começar

  1. Prepare o seu ambiente para o reCAPTCHA.

  2. Crie uma chave do reCAPTCHA para a plataforma de apps Android.

    Em alternativa, pode copiar o ID de uma chave do reCAPTCHA existente para Android através de um dos seguintes passos:

    • Para copiar o ID de uma chave existente a partir da Google Cloud consola, faça o seguinte:

      1. Aceda à página reCAPTCHA.

        Aceder ao reCAPTCHA

      2. Na lista de chaves do reCAPTCHA, mantenha o ponteiro sobre a chave que quer copiar e, de seguida, clique em .
    • Para copiar o ID de uma chave existente através da API REST, use o método projects.keys.list.
    • Para copiar o ID de uma chave existente através da CLI gcloud, use o comando gcloud recaptcha keys list.

Prepare o seu ambiente Android

Android nativo

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

  2. Certifique-se de que tem uma app com o valor mínimo do SDK para Android definido como API 23: Android 6.0 (Marshmallow).

  3. Se estiver a criar uma nova app para dispositivos móveis, crie uma aplicação de teste iniciando um novo projeto do Android Studio:

    1. Selecione Atividade vazia. Se quiser usar o Jetpack Compose na sua app escolha Atividade do Compose vazia.
    2. Definir o idioma para kotlin.
    3. Defina o valor mínimo do SDK para API 23: Android 6.0 (Marshmallow).
  4. Certifique-se de que o repositório Maven da Google google() está na lista de repositórios no ficheiro build.gradle ao nível do projeto, conforme mostrado no seguinte fragmento:

    allprojects {
        repositories {
            google()
        }
    }
    

    Para mais informações, consulte o repositório Maven da Google.

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

      implementation 'com.google.android.recaptcha:recaptcha:18.8.0-beta03'
    

    Para mais informações sobre como adicionar dependências em apps Android, consulte o artigo Adicione dependências de compilação.

  6. Adicione a autorização de Internet entre a primeira etiqueta <manifest> e a primeira etiqueta <application> no manifesto da sua aplicação (por exemplo, AndroidManifest.xml). Esta autorizaçã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 quiser usar bibliotecas AndroidX no seu novo projeto, compile o SDK para o Android 9.0 ou superior e adicione o seguinte fragmento de código ao seu gradle.properties.

    android.useAndroidX=true
    android.enableJetifier=true
    

    Para mais informações, consulte o artigo Migrar para o AndroidX.

Flutter

Para ver instruções detalhadas sobre a utilização do reCAPTCHA através do Flutter, consulte a documentação do Flutter.

React Native

Para ver instruções detalhadas sobre a utilização do reCAPTCHA através do React Native, consulte a documentação do React Native.

Integre o reCAPTCHA com a sua app Android

  1. Instancie um cliente através da chave do reCAPTCHA (KEY_ID) que criou para a sua app Android.

    Kotlin com fetchClient

    O método fetchClient devolve um cliente imediatamente e começa a inicializar o SDK em segundo plano. 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 demorar vários segundos a ser concluída. Para mitigar esta latência, inicialize o cliente o mais cedo possível, como durante a chamada onCreate() de uma classe Application personalizada. Não deve fazer com que os elementos da IU bloqueiem no SDK reCAPTCHA.

  2. Para cada ação da sua app que esteja protegida através do reCAPTCHA, chame o método execute transmitindo um RecaptchaAction. O reCAPTCHA fornece um conjunto integrado de ações e, se necessário, pode criar ações personalizadas.

    O fragmento de código seguinte 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 ...
              }
            });
    }
    

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

O método fetchClient devolve um RecaptchaClient que tenta novamente a inicialização em caso de falhas de rede. Se a app não tiver acesso à rede quando o cliente é criado, o cliente continua a tentar e é inicializado com êxito quando é adquirida uma rede.

Se chamar execute(timeout) e o cliente ainda não estiver pronto, tenta inicializar antes de devolver um token ou um RecaptchaErrorCode.

O exemplo seguinte 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 ...
            }
          });
  }

Defina um limite de tempo para chamadas API

Pode especificar um valor de tempo limite para as APIs execute através da propriedade withTimeout.

Kotlin

  • Defina o limite de tempo ao ligar para 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
            }
        }
    

    Este fragmento de código define o limite de tempo de execute para 10 segundos.

Java

  • Defina o limite de tempo ao ligar para 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
              }
            });
    

    Este fragmento de código define o limite de tempo de execute para 10 segundos.

Processar erros

Se a sua app não conseguir comunicar com o serviço reCAPTCHA, tal pode dever-se a um erro da API. Tem de adicionar lógica na sua app para processar estes erros de forma adequada.

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

Referência da API

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

O que se segue?

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