Integrar o reCAPTCHA aos apps Android

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

Se você quiser oferecer desafios visuais para tráfego suspeito, use a API SafetyNet reCAPTCHA.

Importante: o SDK usa reflexão e código dinâmico para permitir a modificação e 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ências 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 reCAPTCHA existente para Android executando uma das seguintes etapas:

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

     1. Acesse a página do reCAPTCHA.

        Acessar o reCAPTCHA

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

Preparar o ambiente Android

Aviso: não migre para o SDK do Android 18.2.0, porque ele pode deixar o app não funcional 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 (link em inglês).

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 19: Android 4.4 (KitKat). É possível definir o SDK mínimo do app como a API 19 ou criar um novo app para dispositivos móveis.

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 app, escolha Empty Compose Activity.
   2. Defina o idioma como kotlin.
   3. Defina o valor mínimo do SDK como API 19: Android 4.4 (KitKat).

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

   allprojects {
       repositories {
           google()
       }
   }
   

   Para mais informações, consulte a página 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.5.1'
   

   Para ver 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 saber mais, consulte Como migrar para o AndroidX.

Flutter

Para instruções detalhadas sobre como usar o reCAPTCHA com o Flutter, consulte a documentação do Flutter (link em inglês).

ReactNative

Para instruções detalhadas sobre como usar o reCAPTCHA com o 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) criada para o app Android.

   Observação :use o cliente reCAPTCHA apenas uma vez durante a vida útil do app.

   Kotlin

   class MainActivity : AppCompatActivity() {
   
       private lateinit var recaptchaClient: RecaptchaClient
   
       override fun onCreate(savedInstanceState: Bundle?) {
         super.onCreate(savedInstanceState)
         setContentView(R.layout.activity_main)
         initializeRecaptchaClient()
         // ... rest of onCreate code
       }
   
       private fun initializeRecaptchaClient() {
         lifecycleScope.launch {
           Recaptcha.getClient(application, "KEY_ID")
             .onSuccess { client ->
               recaptchaClient = client
             }
             .onFailure { exception ->
               // Handle communication errors ...
               // See "Handle communication errors" section
             }
         }
       }
   
       // ... rest of activity code.
   }
   

   Java

   public final class MainActivity extends Activity {
     @Nullable private RecaptchaTasksClient recaptchaTasksClient = null;
   
     @Override
     protected void onCreate(Bundle savedInstanceState) {
       super.onCreate(savedInstanceState);
       setContentView(R.layout.activity_main);
       initializeRecaptchaClient();
       // ... rest of onCreate code
     }
   
     private void initializeRecaptchaClient() {
       Recaptcha
         .getTasksClient(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 communication errors ...
                 // See "Handle communication errors" section
               }
             });
     }
   
     // ... rest of activity code.
   }
   

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

2. Para cada ação do app protegida por reCAPTCHA, chame o método execute transmitindo uma RecaptchaAction. O reCAPTCHA fornece 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() {
     lifecycleScope.launch {
       recaptchaClient
         .execute(RecaptchaAction.LOGIN)
         .onSuccess { token ->
           // Handle success ...
           // See "What's next" section for instructions
           // about handling tokens.
         }
         .onFailure { exception ->
           // Handle communication errors ...
           // See "Handle communication errors" section
         }
     }
   }
   

   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 communication errors ...
               // See "Handle communication errors" section
             }
           });
   }
   

O exemplo de snippet de código abaixo mostra uma integração completa dos métodos getClient() e execute() em um único app de atividade:

Kotlin

class MainActivity : AppCompatActivity() {

  private lateinit var recaptchaClient: RecaptchaClient

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)
    initializeRecaptchaClient()
    findViewById<View>(R.id.btn_login).setOnClickListener { executeLoginAction() }
    findViewById<View>(R.id.btn_redeem).setOnClickListener { executeRedeemAction() }
  }

  private fun initializeRecaptchaClient() {
    lifecycleScope.launch {
      Recaptcha.getClient(application, "KEY_ID")
        .onSuccess { client ->
          recaptchaClient = client
        }
        .onFailure { exception ->
          // Handle communication errors ...
          // See "Handle communication errors" section
        }
    }
  }

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

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

Java

public final class MainActivity extends Activity {
  @Nullable private RecaptchaTasksClient recaptchaTasksClient = null;

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);
    initializeRecaptchaClient();
    findViewById(R.id.btn_login).setOnClickListener(this::executeLoginAction);
    findViewById(R.id.btn_redeem).setOnClickListener(this::executeRedeemAction);
  }

  private void initializeRecaptchaClient() {
    Recaptcha
      .getTasksClient(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 communication errors ...
              // See "Handle communication errors" section
            }
          });
  }

  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 communication errors ...
              // See "Handle communication errors" section
            }
          });
  }

  private void executeRedeemAction(View v) {
    assert recaptchaTasksClient != null;
    recaptchaTasksClient
      .executeTask(RecaptchaAction.custom("redeem"))
      .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 communication errors ...
              // See "Handle communication errors" section
            }
          });
  }
}

Cuidado: as etapas getClient() e execute() podem levar vários segundos para serem concluídas em um dispositivo. Portanto, recomendamos que você faça o seguinte:

• Inicialize o cliente quando o app for iniciado. Por exemplo, na chamada onCreate() de uma classe Application personalizada.
• Certifique-se de que as chamadas execute() não bloqueiem um evento UI interface. A integração de execute() no seu app não deve bloquear um evento UI, como o pressionamento de um botão. Por exemplo, você pode chamar execute() de forma assíncrona ao criar uma visualização.

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

Definir um tempo limite para chamadas de API

É possível especificar um valor de tempo limite para as APIs getClient e execute usando a propriedade timeout de cada API.

Um tempo limite padrão de 10 segundos é usado para getClient e de 10 segundos para APIs execute.

Kotlin

• Defina o tempo limite ao chamar getClient.

      lifecycleScope.launch {
        Recaptcha.getClient(application, "KEY_ID", timeout = 20000L)
          .onSuccess { client ->
            recaptchaClient = client
          }
          .onFailure { exception ->
            // Handle communication errors ...
            // See "Handle communication errors" section
          }
      }
  

  Este snippet de código define o tempo limite de getClient como 20 segundos.

• Defina o tempo limite ao chamar execute.

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

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

Java

• Defina o tempo limite ao chamar getClient.

    Recaptcha
      .getTasksClient(getApplication(), "KEY_ID", 20000L)
      .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 communication errors ...
              // See "Handle communication errors" section
            }
          });
  

  Este snippet de código define o tempo limite de getClient como 20 segundos.

• 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 communication errors ...
              // See "Handle communication errors" section
            }
          });
  

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

Lidar com erros de comunicação

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

Para saber mais 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 ao reCAPTCHA, crie uma avaliação.

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