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
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:
Aceda à página reCAPTCHA.
- 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:
- Selecione Atividade vazia. Se quiser usar o Jetpack Compose na sua app escolha Atividade do Compose vazia.
- Definir o idioma para kotlin.
- 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 ficheirobuild.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 ficheirobuild.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.
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 seugradle.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 classeApplication
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.