WYA Digital Onboarding - Plugin Cordova

1. Instalación
2. Uso
   2.1 Configuración
   2.2 Onboarding (verificación de identidad)
   2.3 Face Match (reconocimiento facial)
   2.4 Face Enroll (enrolamiento facial)
   2.5 Versión del SDK
3. Manejo de errores

1. Instalación

Requisitos: iOS 14+ (el SDK nativo usa App Attest) y Android minSdk 23. En iOS, configurá el deployment target en tu config.xml, dentro de <platform name="ios">:

<preference name="deployment-target" value="14.0" />

Sin esto, cordova-ios usa 13 por defecto y el build falla al linkear el framework nativo (compilado para iOS 14).

Requisitos de red. Si tu organización restringe el tráfico saliente, estos hosts tienen que estar permitidos:

| Host | Cuándo | Para qué | |---|---|---| | artifacts.wyasolutions.com | build | descarga del SDK nativo iOS | | maven.wyabiometrics.com | build | descarga del SDK nativo Android | | host de la API de WYA | runtime | operación normal del SDK |

En runtime, permití todas las rutas bajo el host de la API, no un conjunto fijo: el SDK incorpora endpoints nuevos entre versiones, y una allowlist por ruta deja de funcionar en la siguiente actualización sin dar un error claro.

1.1. Instalar dependencia con npm

En la raíz del proyecto ejecutar:

npm install --save @wyasolutions/wyadigitalonboardingwrapper

1.2. Agregar plugin

En la raíz del proyecto ejecutar:

cordova plugin add @wyasolutions/wyadigitalonboardingwrapper

Nota iOS: Al instalar el plugin, se descargará automáticamente el SDK nativo iOS desde el CDN de WYA.

2. Uso

2.1. Configuración

Deberás generar la clave pública (publicKey) en https://dash.wyabiometrics.com.

Parámetros comunes:

| Parámetro | Tipo | Requerido | Descripción | |-----------|------|-----------|-------------| | publicKey | string | Sí | Clave pública obtenida del dashboard |

2.2. Onboarding (verificación de identidad)

Captura de documento + biometría facial.

Parámetros:

| Parámetro | Tipo | Requerido | Descripción | |-----------|------|-----------|-------------| | publicKey | string | Sí | Clave pública | | idType | string | Sí | Tipo de documento. Ej: "ARG_3" | | operationId | string | No | ID de operación del backend | | nonce | string | No | Nonce de seguridad |

Ejemplo:

cordova.plugins.WyaDOWrapper.startOnboarding(
  {
    publicKey: 'TU_PUBLIC_KEY',
    idType: 'ARG_3'
  },
  (response) => {
    const data = JSON.parse(response);
    console.log('Aprobado:', data.data.validation.approved);
  },
  (error) => {
    const err = JSON.parse(error);
    console.error('Error:', err.code, err.message);
  }
);

Respuesta exitosa:

{
  "data": {
    "validation": {
      "approved": true,
      "dni": { "success": true, "message": "OK" },
      "faceRecognition": { "success": true, "distance": 0.45 }
    },
    "front": {
      "lastName": "DOE",
      "names": "JOHN",
      "dni": "12345678",
      "dateOfBirth": "07/09/1989",
      "valid": true
    },
    "back": {
      "lastName": "DOE",
      "names": "JOHN",
      "dni": "12345678",
      "valid": true
    },
    "jwt": "eyJhbGciOiJSUzI1NiIs..."
  }
}

2.3. Face Match (reconocimiento facial)

Verifica una cara en vivo contra un template previamente enrolado.

Prerequisito: Obtener operationId y nonce desde el backend llamando a POST /face/init con type "MATCH".

Parámetros:

| Parámetro | Tipo | Requerido | Descripción | |-----------|------|-----------|-------------| | publicKey | string | Sí | Clave pública | | operationId | string | Sí | ID de operación del backend | | nonce | string | Sí | Nonce de seguridad del backend | | showSelfieIntroOnce | boolean | No | Muestra el intro instructivo solo la PRIMERA vez que corre el match en esta instalación; las siguientes autorizaciones van directo a la captura. Solo aplica a match (enroll siempre muestra su intro de calidad). Default: false |

Ejemplo:

cordova.plugins.WyaDOWrapper.startFaceMatch(
  {
    publicKey: 'TU_PUBLIC_KEY',
    operationId: 'op_abc123',
    nonce: 'nonce_xyz'
  },
  (response) => {
    const data = JSON.parse(response);
    console.log('Status:', data.status, 'Decision:', data.decision);
  },
  (error) => {
    const err = JSON.parse(error);
    console.error('Error:', err.code, err.message);
  }
);

2.4. Face Enroll (enrolamiento facial)

Registra un template facial sin verificación de documento.

Prerequisito: Obtener operationId y nonce desde el backend llamando a POST /face/init con type "ENROLL".

Parámetros:

| Parámetro | Tipo | Requerido | Descripción | |-----------|------|-----------|-------------| | publicKey | string | Sí | Clave pública | | operationId | string | Sí | ID de operación del backend | | nonce | string | Sí | Nonce de seguridad del backend |

Ejemplo:

cordova.plugins.WyaDOWrapper.startFaceEnroll(
  {
    publicKey: 'TU_PUBLIC_KEY',
    operationId: 'op_abc123',
    nonce: 'nonce_xyz',
  },
  (response) => {
    const data = JSON.parse(response);
    console.log('Status:', data.status);
  },
  (error) => {
    const err = JSON.parse(error);
    console.error('Error:', err.code, err.message);
  }
);

2.5. Versión del SDK

cordova.plugins.WyaDOWrapper.getVersion(
  (response) => {
    const version = JSON.parse(response);
    console.log('Version:', version);
  },
  (error) => console.error(error)
);

3. Manejo de errores

Los errores se devuelven como JSON string en el error callback:

{ "code": "E_CANCELLED", "message": "Operation cancelled by user" }

Códigos de error:

| Código | Descripción | |--------|-------------| | E_INVALID_PARAMS | Parámetros faltantes o inválidos | | E_CANCELLED | Usuario canceló la operación | | E_NATIVE_FAILURE | Error genérico del SDK nativo | | E_ACTIVITY_MISSING | Sin Activity (Android) o ViewController (iOS) activo | | OPERATION_ALREADY_CONSUMED | El operationId ya fue utilizado | | OPERATION_NOT_FOUND | El operationId no existe | | INTEGRITY_FAILED | Fallo en la verificación de integridad del dispositivo | | INTERNAL_ERROR | Error interno del servidor |