@softcol/biometrics
Version:
Collection of utility methods for eLogic Biometrics
404 lines (328 loc) • 16.1 kB
Markdown
<p align="center">
<a href="https://ebiometricstest.software-colombia.com/">
<img src="https://elogic-biometrics-front.s3.amazonaws.com/images/public/logo.png" width="430" />
</a>
</p>
<p align="center">
<a href="https://ebiometricstest.software-colombia.com/">
<img src="https://img.shields.io/npm/dm/@softcol/biometrics" />
</a>
<a href="https://ebiometricstest.software-colombia.com/">
<img src="https://img.shields.io/npm/v/@softcol/biometrics" />
</a>
<a href="https://ebiometricstest.software-colombia.com/">
<img src="https://img.shields.io/npm/types/@softcol/biometrics" />
</a>
<a href="https://ebiometricstest.software-colombia.com/">
<img src="https://img.shields.io/badge/code_style-prettier-ff69b4.svg" />
</a>
<a href="https://ebiometricstest.software-colombia.com/">
<img src="https://img.shields.io/npms-io/maintenance-score/@softcol/biometrics" />
</a>
<a href="https://ebiometricstest.software-colombia.com/">
<img src="https://img.shields.io/npm/l/@softcol/biometrics" />
</a>
<a href="https://ebiometricstest.software-colombia.com/">
<img src="https://img.shields.io/npm/collaborators/@softcol/biometrics" />
</a>
</p>
<p align="center">
<a href="https://twitter.com/softwarecolombi?t=Q3aK0g3V3-PZ8cpaOTmUUg&s=08">
<img src="https://img.shields.io/twitter/url?style=social&url=https%3A%2F%2Ftwitter.com%2Fsoftwarecolombi%3Ft%3DQ3aK0g3V3-PZ8cpaOTmUUg%26s%3D08" />
</a>
<a href="https://www.youtube.com/channel/UCfHEl_IfBN8qAiRTTQPNkMA">
<img src="https://img.shields.io/youtube/channel/subscribers/UCfHEl_IfBN8qAiRTTQPNkMA?style=social" />
</a>
</p>
<p align="center">
<a href="https://ebiometricstest.software-colombia.com/">eLogic Biometrics</a> es una aplicación que permite la verificación biométrica y documental por medio de reconocimiento y análisis facial.
</p>
Existe un par de opciones para importar o incluir la librería de eLogic Biometrics en su proyecto:
Puede incluir eLogic Biometrics en su proyecto usando npm:
```
npm install --save @softcol/biometrics
```
Si no desea incluir los archivos de eLogic Biometrics en su proyecto, puede importar la librería usando CDN:
```html
<script src="https://ebiometricstest.software-colombia.com/static/public/js/biometrics.js"></script>
```
eLogic Biometrics proporciona la función ```startLivenessFlow``` que inicializa y renderiza el flujo de verificación biométrica para un usuario esepecífico dentro de un elemento HTML en su proyecto.
Para empezar, agregue un elemento HTML acompañado de un identificador en su proyecto:
```html
<div id="ebm" class="wrapper"></div>
```
Adicionalmente, debe agregar los estilos necesarios para ajustar el tamaño deseado del flujo de verificación:
```html
<style>
.wrapper {
width: 400px;
height: 400px;
}
</style>
```
Ahora, debe importar la función ```startLivenessFlow``` desde la librería de eLogic Biometrics en su proyecto:
```js
import { startLivenessFlow } from '@softcol/biometrics';
```
Finalmente, debe inicializar eLogic Biometrics en su proyecto para renderizar el flujo de verificación biométrica:
```js
startLivenessFlow({
environment: 'dev',
target: 'ebm',
account: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
encryptedParams: 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
onError: (err) => console.log(err),
onSuccess: (data) => console.log(data)
});
```
La función ```startLivenessFlow``` recibe los siguientes parámetros de entrada:
| Nombre | Tipo | ¿Requerido? | Descripción |
| :-------------- | :------- | :---------: | :---------------------------------------------------------------------------------------------------- |
| target | string | ✔️ | Identificador del elemento HTML donde se renderizará el flujo de verificación biométrica |
| account | string | ✔️ | Identificador único de la cuenta asociada al cliente dentro de eLogic Biometrics |
| encryptedParams | string | ✔️ | Parámetros cifrados del usuario a quién se le realizará la verificación biométrica |
| environment | string | ❌ | Ambiente de ejecución de eLogic Bioimetrics. Puede ser pruebas o producción |
| onError | function | ❌ | Función de callback que se ejecutará en caso de presentarse un error durante el flujo de verificación |
| onSuccess | function | ❌ | Función de callback que se ejecutará una vez haya finalizado el flujo de verificación sea exitoso |
El parámetro ```account``` corresponde al identificador único de su cuenta que le será sumistrado por <a href="https://software-colombia.com/">Software Colombia</a> al momento de adquirir el servicio. Este identificador es un UUID versión 4, por ejemplo:
```
943a9d71-77b0-4a9c-857d-06007917e12e
```
El parámetro ```encryptedParams``` se debe construir como se especifíca a continuación:
1. Concatenar los parámetros del usuario especificados en la *Tabla parámetros de consulta* utilizando un pipe *"|"* como separador:
```
P-01|P-02|P-03|P-04|P-05|P-06
```
2. Cifrar la cadena de texto construida en el *paso 1* utilizando la llave pública de la cuenta mediante el algoritmo de cifrado RSA-2048 (RSA/ECB/PKCS1Padding). La llave pública al igual que el identificador único de su cuenta le será sumistrada por <a href="https://software-colombia.com/">Software Colombia</a> al momento de adquirir el servicio. Por ejemplo:
```
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAiltIjzjTFXfdrlZ7p1dQGI4fg+CE7xdSiQ2fby97QIrmYDU2FIeGlaKUXgzKXU6BRKycz92D/3pGLjvF3Il1ePPBpg4RB4/Xrdq3ddP1oSctB/th0fLTOD/rebsvYgGxCraiaaGN/TRSCvgQi3YfMxB93hkfoARM+VSUYfT8KSP+8/GeVsV7J5Gir5SxrcZ6pgT7BOlG+5GM3bI2tsZjPzqxQoKWX9/MsKCoXwQ0SGa4D7TmRdgH0S3hGyxLV0qcMM1eBlsmPTQ19/knegsi8SLYFNslg620dcU3UvOHdFPw/JUyPLyK/06k7EVgBI8SbI2nSs6PPvFDszQ08koyPQIDAQAB
-----END PUBLIC KEY-----
```
3. Codificar en Hexadecimal el cripto obtenido en el *paso 2*. Por ejemplo, suponga que se necesita cifrar los siguientes parámetros de usuario concatenados de acuerdo al *paso 1*:
```
Juan David|Trujillo Rodríguez|CC|123456789|2020-01-10|2022-06-22 14:05:30
```
Al aplicar el algoritmo de cifrado RSA-2048 (RSA/ECB/PKCS1Padding) y posteriormente codificar en Hexadecimal el cripto resultante, obtendrá el siguiente parámetro ```encryptedParams```:
```
372fc948c7d6c1c8dc91ed22ae254e994df53076c53917815389afb342c734bc3ce369b1b8164e21e029cd54a04cc0224e3c70678ba994679127cf4d7cd230e80865628d04af099848bf249188bbae2be1fccc3553418df3b91158e058ab790d2b92c53829d0fc0dbca9154618d5181531a4d827f61fa7a4d21b5df991f72e90a861b2487401cb2dd0b0ae9d240d97a938e046bcfb23796cb5f2ec24a1db888d425e7d43bb99b2866512f32eb504400bb41652474f8e13647706c9c1aae0aa3f32eca59d70aebe96777fce7d4c123ca4ede3c0acd7fcbdb53871c70b8c2cfce80566fa9bf517844b148bbc09711d492191fc29a8505f5902fe57a18de289a840
```
| ID | Nombre | Tipo | ¿Requerido? | Descripción |
| :--- | :------------------ | :----- | :---------: | :--------------------------------------------------------------------------------------------------------------------------------- |
| P-01 | Nombres | string | ✔️ | Nombres de la persona a la cual se le va a realizar la verificación biométrica |
| P-02 | Apellidos | string | ✔️ | Apellidos de la persona a la cual se le va a realizar la verificación biométrica |
| P-03 | Tipo documento | string | ✔️ | Tipo de identificación de la persona a la cual se le va a realizar la verificación biométrica. Ver *tabla tipos de identificación* |
| P-04 | Número documento | number | ✔️ | Número de documento de la persona a la cual se le va a realizar la verificación biométrica |
| P-05 | Fecha expedición | string | ✔️ | Fecha de expedición del documento en formato YYYY-MM-DD. Por ejemplo 2020-01-10 |
| P-06 | Fecha y hora actual | string | ✔️ | Fecha y hora actual en formato YYYY-MM-DD HH:mm:ss. Por ejemplo 2022-06-22 14:05:30 |
| Valor | Descripción |
| :-------- | :------------------------------ |
| CC | Cédula de ciudadanía |
| CE | Cédula de extranjería |
| Pasaporte | Pasaporte |
| PEP | Permiso especial de permanencia |
| Otro | Otro tipo de documento |
El parámetro ```environment``` corresponde al ambiente en donde se ejecutará el flujo de verificación de eLogic Biometrics. Se debe especificar *"dev"* para utilizar el ambiente de pruebas o *"prod"* para utilizar el ambiente de producción. En caso de no especificar un ambiente, se utlizará el ambiente de pruebas por defecto.
El parámetro ```onError``` es una función de callback que se invocará en caso de presentarse un error durante el flujo de verificación de eLogic Biometrics. Esta función debe construirse de forma que reciba únicamente un parámetro con la siguiente estructura:
```ts
{
"code": string;
"message": string;
}
```
- El atributo ```code``` identifica al error de acuerdo a la siguiente tabla:
| Código | Descripción |
| :-------------- | :------------------------------------------------------------------------------------------------------ |
| ArgumentsError | Se produce cuando no son enviados todos los parámetros requeridos de la función ```startLivenessFlow``` |
| ConnectionError | Se produce cuando la conexión al servidor de eLogic Biometrics no fue exitosa |
| ValidationError | Se produce cuando el flujo de verificación biométrica no fue satisfactorio |
- El atributo ```message``` contiene la descripción detallada del error.
El parámetro ```onSuccess``` es una función de callback que se invocará una vez se haya finalizado el flujo de verificación de eLogic Biometrics. Esta función debe construirse de forma que reciba únicamente un parámetro con la siguiente estructura:
```ts
{
"faceResult": object;
"textExtractResult": object;
"livenessResult": object;
"comparisonResult": object;
}
```
- El atributo ```faceResult``` hace referencia a los parámetros obtenidos del reconocimiento facial. Por ejemplo:
```JSON
{
"faceResult": {
"AgeRange": {
"High": 33,
"Low": 23
},
"Beard": {
"Confidence": 51.781009674072266,
"Value": false
},
"Confidence": 99.99949645996094,
"Emotions": [{
"Confidence": 96.53080749511719,
"Type": "CALM"
}, {
"Confidence": 6.330127239227295,
"Type": "SURPRISED"
}, {
"Confidence": 5.917669296264648,
"Type": "FEAR"
}, {
"Confidence": 2.780987024307251,
"Type": "SAD"
}, {
"Confidence": 0.9434117078781128,
"Type": "CONFUSED"
}, {
"Confidence": 0.19485926628112793,
"Type": "ANGRY"
}, {
"Confidence": 0.1169237568974495,
"Type": "DISGUSTED"
}, {
"Confidence": 0.08706989884376526,
"Type": "HAPPY"
}],
"Eyeglasses": {
"Confidence": 97.50051879882812,
"Value": false
},
"EyesOpen": {
"Confidence": 89.7717056274414,
"Value": true
},
"Gender": {
"Confidence": 99.78165435791016,
"Value": "Male"
},
"MouthOpen": {
"Confidence": 94.80120849609375,
"Value": false
},
"Mustache": {
"Confidence": 96.97959899902344,
"Value": false
},
"Quality": {
"Brightness": 84.45437622070312,
"Sharpness": 78.64350128173828
},
"Smile": {
"Confidence": 94.97449493408203,
"Value": false
},
"Sunglasses": {
"Confidence": 99.99662017822266,
"Value": false
}
}
}
```
- El atributo ```textExtractResult``` hace referencia a los datos estructurados obtenidos mediante la extracción de información del documento de identidad por ambos costados. Por ejemplo:
```JSON
{
"textExtractResult": {
"name": "JUAN DAVID",
"lastName": "TRUJILLO RODRÍGUEZ",
"documentNumber": "123456789",
"expeditionDate": "2020-01-10",
"expeditionPlace": " BOGOTA D.C.",
"birthDate": "2002-11-18",
"birthPlace": " BOGOTA D.C (CUNDINAMARCA)",
"sex": "M",
"height": "1.71",
}
}
```
- El atributo ```livenessResult``` hace referencia a la información obtenida de la verificación de vida de la persona verificada. Por ejemplo:
```JSON
{
"livenessResult": {
"isLive": true,
"confidenceScore": 96.389745,
"auditImagesBytes": "/9j/4d..",
}
}
```
- El atributo ```comparisonResult``` hace referencia a los parámetros obtenidos de la comparación de rostros entre el documento de identidad y la imágen obtenida en vivo. Pro ejemplo:
```JSON
{
"comparisonResult": {
"similarity": 33.518364,
"face": {
"confidence": 89.38466,
"quality": {
"brightness": 89.364365,
"sharpness": 32.208035
}
}
}
}
```
```js
import { useEffect } from 'react';
import { startLivenessFlow } from '@softcol/biometrics';
const App = () => {
useEffect(() => {
startLivenessFlow({
environment: 'dev',
target: 'ebm',
account: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
encryptedParams: 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
onError: (err) => console.log(err.code, err.message),
onSuccess: (data) => console.log(data.faceResult, data.textExtractResult, data.livenessResult, data.comparisonResult)
});
}, []);
return (
<>
<div id="ebm" style={{ width: 400, height: 400 }}></div>
</>
);
};
export default App;
```
```js
import { Component, OnInit } from '@angular/core';
import { startLivenessFlow } from '@softcol/biometrics';
@Component({
selector: 'app-root',
templateUrl: './app.component.html',
styleUrls: ['./app.component.scss'],
})
export class AppComponent implements OnInit {
constructor() {}
ngOnInit(): void {
startLivenessFlow({
environment: 'dev',
target: 'ebm',
account: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
encryptedParams: 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
onError: (err) => console.log(err.code, err.message),
onSuccess: (data) => console.log(data.faceResult, data.textExtractResult, data.livenessResult, data.comparisonResult)
});
}
}
```
```HTML
<div id="ebm" style="width: 400px; height: 400px"></div>
```
Esto renderizará el siguiente componente:
[](https://ebiometricstest.software-colombia.com/)