API reCAPTCHA do SafetyNet

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:

  1. 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.
  2. Marque a caixa Aceitar os Termos de Serviço do reCAPTCHA e clique em Registrar.

  3. 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:

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.