API de reCAPTCHA de SafetyNet

El servicio SafetyNet incluye una API de reCAPTCHA que puedes usar para proteger tu app contra el tráfico malicioso.

reCAPTCHA es un servicio gratuito que utiliza un motor de análisis de riesgos avanzado para proteger tu app contra el spam y otras acciones abusivas. Si el servicio sospecha que el usuario que está interactuando con tu app podría ser un bot y no una persona, mostrará un CAPTCHA que se deberá resolver para seguir ejecutando la app.

En este documento, se explica cómo integrar la API de reCAPTCHA de SafetyNet en tu app.

Condiciones del Servicio adicionales

Cuando accedes a la API de reCAPTCHA o la usas, aceptas las Condiciones del Servicio de las APIs de Google y las siguientes Condiciones del Servicio de reCAPTCHA. Asegúrate de leer y entender todos los términos y las políticas aplicables antes de acceder a las APIs.

Condiciones del Servicio de reCAPTCHA

Reconoces y comprendes que la API de reCAPTCHA funciona mediante la recopilación de información de hardware y software, como datos de dispositivos y apps, y resultados de verificaciones de integridad, y que envía esos datos a Google para su análisis. Según el Artículo 3(d) de las Condiciones del Servicio de las APIs de Google, aceptas que, si utilizas las APIs, eres responsable de brindar avisos o el consentimiento necesario para la recopilación y el uso compartido de estos datos con Google.

Cómo registrar un par de claves de reCAPTCHA

Si quieres registrar un par de claves para usar con la API de reCAPTCHA de SafetyNet, ve al sitio de registro de reCAPTCHA para Android y, luego, completa la siguiente secuencia de pasos:

En el formulario que aparece, proporciona la siguiente información:
- Etiqueta: Una etiqueta única para tu clave. Por lo general, incluye el nombre de tu organización o empresa.
- Tipo de reCAPTCHA: Selecciona reCAPTCHA v2 y, luego, reCAPTCHA para Android.
- Paquetes: Proporciona el nombre del paquete de cada app que use esta clave de API. Para que una app use la API, el nombre del paquete que ingreses debe coincidir exactamente con el nombre del paquete de la app. Ingresa cada nombre en una línea separada.
- Propietarios: Agrega una dirección de correo electrónico para cada persona de tu organización que supervise las evaluaciones de reCAPTCHA de tu app.
Selecciona la casilla de verificación Acepta las Condiciones del Servicio de reCAPTCHA.
Enviar alertas a los propietarios: Selecciona esta casilla de verificación si deseas recibir correos electrónicos sobre la API de reCAPTCHA y, luego, haz clic en Enviar.
En la página que aparece a continuación, tus claves públicas y privadas aparecen en Clave del sitio y Clave secreta, respectivamente. Usa la clave del sitio para enviar la solicitud de verificación y usa la clave secreta para validar el token de respuesta del usuario.

Agrega la dependencia de la API de SafetyNet

Antes de usar la API de reCAPTCHA, agrega la API de SafetyNet a tu proyecto. Si usas Android Studio, agrega esta dependencia a tu archivo Gradle a nivel de la app. Para obtener más información, consulta cómo configurar la API de SafetyNet.

Cómo usar la API de reCAPTCHA

En esta sección, se describe cómo llamar a la API de reCAPTCHA para enviar una solicitud de verificación de CAPTCHA y recibir el token de respuesta del usuario.

Cómo enviar la solicitud de verificación

Para invocar la API de reCAPTCHA de SafetyNet, llama al método verifyWithRecaptcha(). Por lo general, se activa ese método cada vez que el usuario selecciona un elemento de la IU, como un botón, en tu actividad.

Cuando uses el método verifyWithRecaptcha() en tu app, deberás hacer lo siguiente:

Pasa la clave del sitio de la API como parámetro.
Anula los métodos onSuccess() y onFailure() para procesar ambos resultados posibles de la tarea de solicitud de verificación. En particular, si la API pasa una instancia de ApiException a onFailure(), debes procesar cada código de estado posible que puedes obtener con getStatusCode().

En el siguiente fragmento de código, se muestra cómo invocar este 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());
                    }
                }
        });
}

Cómo validar el token de respuesta del usuario

Cuando la API de reCAPTCHA ejecuta el método onSuccess(), significa que el usuario completó correctamente el desafío de CAPTCHA. Sin embargo, este método solo indica que el usuario resolvió el CAPTCHA de forma correcta. Aún debes validar el token de respuesta del usuario desde el servidor de backend.

Para aprender a validar el token de respuesta del usuario, consulta Verifica la respuesta del usuario.