Esta página foi traduzida pela API Cloud Translation.

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

Prepare o seu ambiente para o reCAPTCHA.
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

Prepare o seu ambiente de desenvolvimento transferindo e instalando a versão mais recente do Android Studio.
Certifique-se de que tem uma app com o valor mínimo do SDK para Android definido como API 23: Android 6.0 (Marshmallow).
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).
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.
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'
```
Para mais informações sobre como adicionar dependências em apps Android, consulte o artigo Adicione dependências de compilação.
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>
```
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

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.

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.

Nota: os tokens de resposta do reCAPTCHA são avaliados e anotados a partir do servidor de back-end e não do dispositivo móvel.

Integre o reCAPTCHA com apps Android Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Antes de começar

Prepare o seu ambiente Android

Android nativo

Flutter

React Native

Integre o reCAPTCHA com a sua app Android

Kotlin com fetchClient

Java com fetchClient

Kotlin

Java

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

Kotlin

Java

Defina um limite de tempo para chamadas API

Kotlin

Java

Processar erros

Referência da API

O que se segue?

Integre o reCAPTCHA com apps Android

Kotlin com `fetchClient`

Java com `fetchClient`