npm package: @gatekeeperx/cordova-plugin-devicex
Description: GatekeeperX Device Intelligence Cordova plugin (Android)
Author: GatekeeperX
Latest version: 0.1.0

# @gatekeeperx/cordova-plugin-devicex

[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

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


### Prerequisitos

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
```

### Instalación

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
```

### Configuración de Plataforma

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.

### 1. `Devicex.configure(options)`
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'
});
```

### 2. `Devicex.sendEvent(name, properties?, headers?)`
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. `Devicex.isInitialized()`
Verifica si el SDK ha sido configurado correctamente.

**Retorna:** `Promise<boolean>`

### 4. `Devicex.getVersion()`
Obtiene la versión del SDK nativo subyacente.

**Retorna:** `Promise<string>`

---

## 🚀 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');
    }
}
```