O serviço SafetyNet inclui uma API reCAPTCHA que pode ser usada para proteger seu app contra tráfego malicioso.
O reCAPTCHA é um serviço gratuito que usa um mecanismo avançado de análise de risco para proteger seu app contra spam e outras ações abusivas. Se o serviço suspeitar que o usuário que interagiu com o app pode ser um bot em vez de um ser humano, ele exibirá um CAPTCHA que um ser humano precisa resolver antes de continuar a execução.
Este documento explica como integrar a API reCAPTCHA do SafetyNet ao seu app.
Outros Termos de Serviço
Ao acessar ou usar a API reCAPTCHA, você concorda com os Termos de Serviço das APIs Google e com estes Outros Termos. Leia e entenda todos os termos e políticas aplicáveis antes de acessar as APIs.
Termos de Serviço do reCAPTCHA
Você reconhece e entende que a API reCAPTCHA funciona coletando informações de hardware e software, como dados de dispositivos e aplicativos e os resultados das verificações de integridade, e enviando esses dados ao Google para análise. De acordo com a Seção 3(d) dos Termos de Serviço das APIs Google, você concorda que, ao usar as APIs, é sua responsabilidade oferecer os avisos ou consentimentos necessários para a coleta e o compartilhamento desses dados com o Google.Registrar um par de chaves reCAPTCHA
Para registrar um par de chaves para uso com a API reCAPTCHA do SafetyNet, navegue até o site de registro de reCAPTCHA Android e realize a seguinte sequência de etapas:
No formulário exibido, forneça estas informações:
- Etiqueta: uma etiqueta exclusiva para sua chave. Normalmente, o nome da sua empresa ou organização é usado.
- Nomes de pacotes: forneça o nome do pacote de cada app que usa essa chave de API. Para que um app use a API, o nome do pacote inserido precisa ser uma correspondência exata do nome do pacote desse app. Insira o nome de cada pacote na respectiva linha.
- Enviar alertas aos proprietários: marque essa caixa de seleção se você quiser receber e-mails sobre a API reCAPTCHA.
Marque a caixa Aceitar os Termos de Serviço do reCAPTCHA e clique em Registrar.
Na seção Como adicionar reCAPTCHA ao seu aplicativo na página que aparece em seguida, suas chaves públicas e privadas aparecem em Chave do site e Chave secreta, respectivamente. Use a chave do site quando você enviar a solicitação de verificação e a chave secreta quando você validar o token de resposta do usuário.
Adicionar uma dependência da API SafetyNet
Antes de usar a API reCAPTCHA, você precisa adicionar a API SafetyNet ao seu projeto. Se você usa o Android Studio e quer compilar essa API de modo seletivo nas dependências do Gradle, inclua a regra de versão mostrada no snippet de código a seguir.
apply plugin: 'com.android.application' ... dependencies { compile 'com.google.android.gms:play-services-safetynet:17.0.0' }
Para ver mais informações, consulte Configurar o Google Play Services.
Usar a API reCAPTCHA
Esta seção descreve como chamar a API reCAPTCHA para enviar uma solicitação de verificação CAPTCHA e receber o token de resposta do usuário.
Enviar a solicitação de verificação
Para chamar a APIreCAPTCHA do SafetyNet, chame o método verifyWithRecaptcha()
. Normalmente, esse método corresponde a selecionar um elemento de IU, por exemplo, um botão, na sua atividade.
Ao usar o método verifyWithRecaptcha()
no seu app, faça o seguinte:
- Transmita sua chave do site da API como um parâmetro.
- Modifique os métodos
onSuccess()
eonFailure()
para processar os dois resultados possíveis da tarefa de solicitação de verificação. Em especial, se a API transmitir uma instância deApiException
paraonFailure()
, será necessário gerenciar cada código de status possível que pode ser recuperado usandogetStatusCode()
. Para ver mais informações, consulte Como processar erros de comunicação.
O snippet de código a seguir mostra como invocar esse método:
Kotlin
fun onClick(view: View) { SafetyNet.getClient(this).verifyWithRecaptcha(YOUR_API_SITE_KEY) .addOnSuccessListener(this as Executor, OnSuccessListener { response -> // Indicates communication with reCAPTCHA service was // successful. val userResponseToken = response.tokenResult if (response.tokenResult?.isNotEmpty() == true) { // Validate the user response token using the // reCAPTCHA siteverify API. } }) .addOnFailureListener(this as Executor, OnFailureListener { e -> if (e is ApiException) { // An error occurred when communicating with the // reCAPTCHA service. Refer to the status code to // handle the error appropriately. Log.d(TAG, "Error: ${CommonStatusCodes.getStatusCodeString(e.statusCode)}") } else { // A different, unknown type of error occurred. Log.d(TAG, "Error: ${e.message}") } }) }
Java
public void onClick(View v) { SafetyNet.getClient(this).verifyWithRecaptcha(YOUR_API_SITE_KEY) .addOnSuccessListener((Executor) this, new OnSuccessListener<SafetyNetApi.RecaptchaTokenResponse>() { @Override public void onSuccess(SafetyNetApi.RecaptchaTokenResponse response) { // Indicates communication with reCAPTCHA service was // successful. String userResponseToken = response.getTokenResult(); if (!userResponseToken.isEmpty()) { // Validate the user response token using the // reCAPTCHA siteverify API. } } }) .addOnFailureListener((Executor) this, new OnFailureListener() { @Override public void onFailure(@NonNull Exception e) { if (e instanceof ApiException) { // An error occurred when communicating with the // reCAPTCHA service. Refer to the status code to // handle the error appropriately. ApiException apiException = (ApiException) e; int statusCode = apiException.getStatusCode(); Log.d(TAG, "Error: " + CommonStatusCodes .getStatusCodeString(statusCode)); } else { // A different, unknown type of error occurred. Log.d(TAG, "Error: " + e.getMessage()); } } }); }
Validar o token de resposta do usuário
Quando a API reCAPTCHA executa o método onSuccess()
, o usuário completou o desafio CAPTCHA. No entanto, esse método indica apenas que o usuário resolveu o CAPTCHA corretamente. Você ainda precisa validar o token de resposta do usuário a partir do seu servidor de back-end.
Para saber como validar token de resposta do usuário, consulte Como verificar a resposta do usuário.
Solucionar 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. Adicione uma lógica ao seu app para solucionar esse erro. Além disso, quando o erro ocorre, seu app precisa exibir uma mensagem aos usuários explicando por que o aplicativo não pode concluir o processamento da resposta CAPTCHA.
A lista a seguir mostra os códigos de status dos erros mais comuns da API:
RECAPTCHA_INVALID_SITEKEY
-
A chave do site é inválida. Verifique se você registrou uma chave de API e se copiou corretamente a chave do site como um parâmetro ao chamar a API.
Valor constante: 12007
RECAPTCHA_INVALID_KEYTYPE
-
O tipo de chave do site é inválido. Criar uma nova chave do site acessando o site de inscrição no reCAPTCHA Android.
Valor constante: 12008
RECAPTCHA_INVALID_PACKAGE_NAME
-
O nome do pacote do app de chamada não corresponde a nenhum dos nomes que você associou à chave do site. Adicione o nome do pacote do app de chamada à chave site no Admin Console do reCAPTCHA (link em inglês) ou desative a validação do nome do pacote para sua chave de site.
Valor constante: 12013
UNSUPPORTED_SDK_VERSION
-
A API não é compatível com a versão do SDK Android do dispositivo. Faça upgrade para uma nova versão do SDK Android e tente se comunicar com a API novamente.
Valor constante: 12006
TIMEOUT
-
A sessão expirou enquanto a API aguardava uma resposta porque o usuário não interagiu com o CAPTCHA ou porque o próprio processo de carregamento do CAPTCHA atingiu o tempo limite. Espere o usuário invocar a API novamente. Enquanto isso, informe ao usuário que ele precisa concluir o CAPTCHA para continuar usando seu app.
Valor constante: 15
NETWORK_ERROR
-
Não há uma conexão de Internet. Depois de garantir a conectividade, tente se comunicar com a API novamente.
Valor constante: 7
ERROR
-
A operação encontrou uma falha geral.
Valor constante: 13
Para ver mais detalhes sobre os códigos de status que a API reCAPTCHA pode retornar, consulte a referência SafetyNetStatusCodes
.