@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

Prerequisitos

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

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.

# 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:

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:

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:

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)

// 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');
    }
}