Liveness para Android

Empezando

Para proceder, es indispensable generar una clave API con un tiempo de expiración definido.

Este proceso puede completarse fácilmente mediante el panel de administrado. Esto garantiza un acceso seguro y gestionado a los recursos necesarios durante el tiempo estipulado.

Para más detalles, consulta la documentación específica de cada método disponible a través de los siguientes enlaces:

Generación de clave API el panel de administrador API Keys Panel de Administrador

Guía Rápida para Usar Liveness

Paso 1: Capturar el Video

Abre la cámara del usuario y graba un video. Asegúrate de que el video cumpla con los siguientes criterios:
Duración: El video debe tener una duración mínima de 3 segundos y máxima de 8 segundos.
Visibilidad: El video debe mostrar claramente el rostro. Si no se detecta ningún rostro, el servicio devolverá un error.
Iluminación y Calidad: Asegura una buena iluminación y una captura de video de alta calidad. El rostro debe estar lo suficientemente cerca de la cámara para permitir una visibilidad y análisis claros.

Paso 2: Enviar el Video

Codifica el video en formato base64 y envíalo al endpoint /api/v1/liveness/verify-and-bestframe. Este proceso analizará el video y devolverá una foto de la persona (bestFrame) junto con una puntuación que indica el nivel de confianza de la detección de liveness. Para mas información sobre que es el formato Base64 ve a Base64.

Para más detalles visita la referencia de la API aquí.

Paso 3: Revisar los Resultados

Examina el bestFrame devuelto y la puntuación de liveness. Esta puntuación ayuda a determinar la probabilidad de que el video haya sido de una persona viva presente en el momento de la grabación en lugar de un video pregrabado o un intento de engaño.

Requisitos

Debes tener un video de un rostro que cumpla con los requisitos de duración, visibilidad, iluminación y calidad en Base64.
Asegúrate de que el video esté disponible en el dispositivo desde el cual se realizará la prueba.
Necesitas una clave API válida de una empresa activa y configurarla como Bearer Token en el encabezado de tu solicitud. Para más información sobre el uso del Bearer Token consulta aquí.

Verify

POST basePath/api/v1/liveness/verify

Este endpoint realiza la validación de vida del video base64.

Descripción de la Solicitud

Petición

@POST("api/v1/liveness/verify")
suspend fun livenessVerify(@Header("Authorization") auth: String,
@Header("Request-Id") requestId: String, @Body request: LivenessVerifyRequest): Response<LivenessVerifyResponse>

data class LivenessVerifyRequest(
@SerializedName("video") val video: String, //base64
)

Agrega localización

Si deseas agregar localización a la ejecución del evento agrega las cabeceras Longitude y Latitude con los valores numericos de la ubicación de la cual se esta ejecutando tu petición.

@POST("api/v1/liveness/verify")
suspend fun livenessVerify(@Header("Authorization") auth: String,@Header("Latitude") latitude: String,
@Header("Longitude") longitude: String,@Header("Request-Id") requestId: String,
@Body request: LivenessVerifyRequest): Response<LivenessVerifyResponse>

Descripción de los parámetros

Parámetro	Descripción
video	Video codificado en Base64 .

Respuesta

{
  "eventId": "string",
  "requestId": "string",
  "processTime": "long",
  "score": "double",
  "state": {
  "isRealPerson": "boolean",
  "message": "string"
}
}

data class LivenessVerifyResponse(
@SerializedName("eventId") val eventId: String,
@SerializedName("requestId") val requestId: String,
@SerializedName("processTime") val processTime: Long,
@SerializedName("score") val score: Double,
@SerializedName("state") val state: LivenessState
)

data class LivenessState(
@SerializedName("isRealPerson") val isRealPerson: Boolean,
@SerializedName("message") val message: String
)

Parámetros de Respuesta

Parámetro	Descripción
eventId	Identificador único del evento de verificación de liveness.
processTime	Tiempo en milisegundos que tomó procesar la solicitud de verificación.
requestId	Identificador único de la solicitud de verificación enviada al servicio de Liveness.
score	Puntuación que indica el nivel de confianza en la detección de liveness. Un valor más alto indica mayor confianza.

Ejemplos de Solicitudes

{
  "video": "GkXfo59ChoEBQveBAULygQRC84EIQoKEd2Vib -- videoBase64"
}

{
  "eventId": "73e8babe-8d41-491a-8b88-a3719522f64f",
  "requestId": "73e8babe-8d41-491a-8b88-a3719522f64f",
  "processTime": 2588,
  "score": 0.73340136,
  "state": {
  "isRealPerson": true,
  "message": ""
}
}

Verify and best frame

POST basePath/api/v1/liveness/verify-and-bestframe

Este endpoint realiza la validación de vida del video base64 y obtiene el mejor fotograma del video para el análisis facial.