@gatekeeperx/device-intelligence-web

Web SDK for GatekeeperX Device Intelligence — browser-native homologue of the Android SDK com.gatekeeperx:devicex (v1.2.9, V_6 fingerprint).

Recolecta ~22 señales del navegador, produce un fingerprint determinista (SHA-256) y envía eventos firmados con HMAC-SHA256 al backend de GatekeeperX. Mismo payload, mismos endpoints y mismas firmas que el SDK Android: el servidor no requiere cambios.

Instalación

npm install @gatekeeperx/device-intelligence-web

Quickstart

import { DeviceIntelligence } from '@gatekeeperx/device-intelligence-web';

DeviceIntelligence.configure({
  apiKey: 'your-api-key',
  tenant: 'your-tenant',
  environment: 'sandbox',
});

const result = await DeviceIntelligence.sendEvent('login', { userId: 'u_123' });
if (result.kind === 'success') {
  console.log('deviceXId:', result.deviceXId);
} else {
  console.warn(result.errorCode, result.errorMessage);
}

DSL completo

DeviceIntelligence.configure({
  apiKey: 'sk_xxx',
  tenant: 'rappi',
  environment: 'production',       // 'production' | 'sandbox' | 'development'
  organizationId: 'rappi-co',      // opcional, default = tenant
  headers: { 'X-App-Version': '1.0.0' },
  fingerprintVersion: 'V_6',       // default
  stabilityLevel: 'OPTIMAL',       // 'STABLE' | 'OPTIMAL' | 'UNIQUE'
  optIns: { location: true, wifi: true },
  timeoutMs: 30_000,
});

API

| Método | Tipo | Descripción | |---|---|---| | configure(opts) | void | Inicializa el singleton. Lanza si ya está configurado. | | sendEvent(name, properties?, headers?) | Promise<EventResult> | Envía evento firmado. Nunca rechaza la promesa. | | sendEventAsync(name, properties?, headers?, callback?) | void | Fire-and-forget con callback opcional. | | getFingerprint(version?, stability?) | Promise<string> | Hash hex de 64 chars. | | getDeviceId() | Promise<DeviceIdResult> | Fingerprint usando solo señales STABLE. | | getRiskAssessment() | Promise<RiskAssessment> | Detección de headless/automation/webdriver. | | isInitialized() | boolean | true solo en browser después de configure. | | getVersion() | string | Versión del SDK. | | shutdown() | void | Resetea el singleton (útil para tests). |

EventResult es discriminated union:

type EventResult =
  | { kind: 'success'; code: number; deviceXId: string; message?: string }
  | { kind: 'failure'; errorCode: ErrorCode; errorMessage: string; httpCode?: number };

Señales recolectadas (V_6)

| Categoría | Señales | |---|---| | UA / Plataforma | userAgentBrandsSignal, platformSignal (UA Client Hints) | | Hardware | hardwareConcurrencySignal, deviceMemorySignal, touchPointsSignal | | Display | screenSignal (width/height/colorDepth/orientation/pixelRatio) | | Locale | timezoneSignal, languagesSignal, localeSignal | | Gráficos | canvasFingerprintSignal, webglRendererSignal | | Audio | audioContextFingerprintSignal | | Fuentes | fontListSignal (~40 fuentes detectadas) | | Privacidad | cookiesEnabledSignal, doNotTrackSignal, gpcSignal | | Storage | storageQuotaSignal | | Red | connectionSignal (effectiveType/downlink/rtt) | | Sensores | sensorsSignal, batterySignal | | Plugins | pluginsSignal | | Location | locationSignals (opt-in) con detección de spoofing | | WiFi | wifiSignals (opt-in, vía WebRTC para IP local) | | VPN | vpnSignals (heurísticas: timezone/locale mismatch, RTT anómalo) | | Risk | riskSignals (webdriver, chrome missing, automation hooks) |

Stability levels

• STABLE — señales no-volátiles (platform, hardware, screen, timezone, languages, webglVendor, touchPoints, cookies). Para identidad longitudinal (≥ días).
• OPTIMAL (default) — STABLE + canvas, webglRenderer, audio, fontList, plugins, storageQuota, connection. Balance estabilidad/unicidad.
• UNIQUE — OPTIMAL + sensors, battery, gpc, dnt. Máxima unicidad pero menos estable.

SSR (Next.js, Remix, Nuxt)

El import es seguro en Server Components. En server:

• isBrowser() → false
• configure() registra config pero no recolecta señales.
• isInitialized() → false.
• sendEvent() → EventResult.failure('SDK_NOT_INITIALIZED').
• getFingerprint() → ''.

Patrón recomendado en Next.js:

'use client';
import { useEffect } from 'react';
import { DeviceIntelligence } from '@gatekeeperx/device-intelligence-web';

export function DeviceIntelligenceBoot({ apiKey, tenant }: { apiKey: string; tenant: string }) {
  useEffect(() => {
    if (!DeviceIntelligence.isInitialized()) {
      DeviceIntelligence.configure({ apiKey, tenant, environment: 'sandbox' });
    }
  }, [apiKey, tenant]);
  return null;
}

Permisos opt-in

Location y WiFi requieren prompt al usuario. Si optIns.location = false (default), locationSignals se envía como {} y meta.locationStatus = 'not_requested'. Lo mismo para WiFi.

Compatibilidad

• Navegadores: Chrome/Edge ≥ 80, Firefox ≥ 88, Safari ≥ 14.
• Node: ≥ 18 (para SSR y tests).
• Bundlers: webpack, vite, parcel, esbuild, rollup, Next.js, Remix, Nuxt, Angular CLI, Vue CLI.
• JavaScript puro: sí, ignora los .d.ts.

Privacidad

• ❌ No envía MAC, IMEI, IP pública, biometría, contactos.
• ✅ Location se redondea a 2 decimales (~1km).
• ✅ Permisos opt-in para Location y WiFi.
• ✅ Compatible con GPC (Global Privacy Control).

Licencia

MIT © GatekeeperX