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:

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() e onFailure() para processar os dois resultados possíveis da tarefa de solicitação de verificação. Em especial, se a API transmitir uma instância de ApiException para onFailure(), será necessário gerenciar cada código de status possível que pode ser recuperado usando getStatusCode(). 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.