API SafetyNet reCAPTCHA

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 vai mostrar um CAPTCHA que um ser humano precisa resolver antes de continuar a execução.

Este documento explica como integrar a API reCAPTCHA do serviço 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 do Google e com os Termos de Serviço do reCAPTCHA abaixo. Leia e entenda todos os termos e políticas aplicáveis antes de acessar as APIs.

Registrar um par de chaves reCAPTCHA

Para registrar um par de chaves para uso com a API SafetyNet reCAPTCHA, navegue até o site de inscrição no reCAPTCHA para Android e siga estas etapas:

1. No formulário mostrado, forneça estas informações:

   • Etiqueta: uma etiqueta exclusiva para sua chave. Normalmente, o nome da sua empresa ou organização é usado.
   • Tipo de reCAPTCHA: selecione reCAPTCHA v2 e depois reCAPTCHA Android.
   • 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 corresponder exatamente ao nome do pacote do app. Insira cada nome de pacote na respectiva linha.
   • Proprietários: adicione um endereço de e-mail para cada indivíduo da organização que monitora os testes reCAPTCHA do seu app.

2. Marque a caixa de seleção Aceitar os Termos de Serviço do reCAPTCHA.

3. Enviar alertas aos proprietários: marque essa caixa de seleção se você quiser receber e-mails sobre a API reCAPTCHA e clique em Enviar.

4. Na página mostrada em seguida, as chaves pública e privada 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 a dependência da API SafetyNet

Antes de usar a API reCAPTCHA, adicione a API SafetyNet ao seu projeto. Se você estiver usando o Android Studio, adicione essa dependência ao arquivo do Gradle no nível do app. Para mais informações, consulte Configuração da API SafetyNet.

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 API reCAPTCHA do SafetyNet, chame o método verifyWithRecaptcha(). Normalmente, esse método corresponde a selecionar um elemento de interface, 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.
• Substitua 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 extraído usando getStatusCode().

O snippet de código abaixo mostra como invocar esse método:

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}")
                }
            })
}

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(), significa que 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 usando seu servidor de back-end.

Para saber como validar o token de resposta do usuário, consulte Como verificar a resposta do usuário.