@gatekeeperx/cordova-plugin-devicex


Plugin oficial de Cordova para la integración del SDK GatekeeperX Device Intelligence en aplicaciones Android. Proporciona capacidades avanzadas de fingerprinting, detección de fraude (root, emuladores, hooks) y telemetría de seguridad.

---

📋 Requisitos

Para integrar este plugin, asegúrate de cumplir con los siguientes requisitos:

- Cordova Android: Versión 11.0.0 o superior.
- Java: JDK 11 o 17.
- Android SDK: API Level 21+ soportado (API 31+ recomendado).
- GatekeeperX Credentials: Tenant ID y API Key válidos.

---

🔧 Instalación

$3

Asegúrate de tener instalado Node.js y npm en tu máquina. ejecuta este comando para instalar el plugin:

``bash
npm i @gatekeeperx/cordova-plugin-devicex
`

$3

Instala el plugin utilizando el CLI de Cordova o Ionic. Esto configurará automáticamente las dependencias nativas en tu proyecto.

`bash


Usando Ionic CLI (Recomendado)

ionic cordova plugin add @gatekeeperx/cordova-plugin-devicex

Usando Cordova CLI

cordova plugin add @gatekeeperx/cordova-plugin-devicex
`

$3

Asegúrate de tener la plataforma Android configurada correctamente:

`bash
cordova platform add android@11
`

---

📚 API Reference

El plugin expone el objeto global Devicex una vez que el evento deviceready se ha disparado.

$3

Inicializa el SDK con las credenciales de tu proyecto. Debe llamarse antes que cualquier otro método.

Parámetros:
- options (ConfigureOptions):
- tenant (string, requerido): ID de tu tenant.
- apiKey (string, requerido): Tu clave de API.
- environment (string, opcional): 'SANDBOX', o 'PRODUCTION'.
- organizationId (string, opcional): Identificador de organización.

Ejemplo:
`typescript
await Devicex.configure({
tenant: 'mi-tenant',
apiKey: 'tu-api-key',
environment: 'PRODUCTION'
});
`

$3

Envía un evento de telemetría con señales de seguridad adjuntas automáticamente.

Parámetros:
- name (string, requerido): Nombre del evento (ej: 'login', 'checkout').
- properties (object, opcional): Metadatos adicionales del evento.
- headers (object, opcional): Cabeceras HTTP personalizadas.

Ejemplo:
`typescript
const result = await Devicex.sendEvent('login', { user: 'id_123' });
if (result.ok) {
console.log('DeviceX ID:', result.deviceXId);
}
`

$3

Verifica si el SDK ha sido configurado correctamente.

Retorna: Promise

$3

Obtiene la versión del SDK nativo subyacente.

Retorna: Promise

---

🚀 Uso Rápido (Ionic/Angular)

`typescript
// En app.component.ts
async initializeApp() {
await this.platform.ready();

if (this.platform.is('cordova')) {
declare const Devicex: any;

try {
await Devicex.configure({
tenant: 'gatekeeperx', // tu tenant
apiKey: 'YOUR_API_KEY', // tu api key
environment: 'PRODUCTION' // PRODUCTION o SANDBOX
});
console.log('DeviceX Ready');
} catch (err) {
console.error('DeviceX Init Error', err);
}
}
}


async login() {
//,,, logica previo a enviar el login

loading.present();
try {
// Enviar evento de login para obtener deviceXId
const result = await this.deviceX.sendEvent('login', {
username: this.username,
method: 'password',
timestamp: new Date().toISOString(),
screen: 'login'
});
console.log('Evento enviado, deviceXId:', result.deviceXId);


/** EVALUACION DE RIESGO
* Evaluar riesgo con GatekeeperX - debe hacerse back to back, no en el cliente.
* debe ser dentro del proceso del login en el backend
* si la decision es allow, se puede continuar con el login
* si la decision es deny, se debe denegar el acceso
* si la decision es unknown, se debe denegar el acceso
*/

//invocar proceso de login en el backend
const response = await this.http.post(BACKEND_URL, {
username: this.username,
password: this.password,
deviceXId: result.deviceXId
});
console.log('Login response:', JSON.stringify(response, null, 2));

loading.dismiss();


console.log('Login event result:', JSON.stringify(result, null, 2));

} catch (error) {
loading.dismiss();
console.error('Login event error:', error);
this.showAlert('Error', 'No se pudo enviar el evento de login', 'error');
}
}
``