Quickstart — SDK para Web

Qué hace el SDK (y qué no)

@gu1/sdk-web es el canal navegador del SDK de Gu1: corre dentro de tu web app y captura lo que el backend no puede ver — señales del dispositivo (canvas, WebGL, propiedades de navigator), integridad del entorno y el recorrido del usuario, incluido el tramo anterior al login. Comparte el modelo de eventos con el SDK de React Native: los eventos que ya envías desde tu backend siguen exactamente igual, solo se les anexa un sessionId para que el motor de Gu1 cruce ambos mundos. El SDK es fail-open por diseño: nunca bloquea la página, nunca propaga errores (la única excepción es configuración inválida en la inicialización) y no accede a datos del usuario.


Entornos	Navegadores modernos
Builds	ESM, CommonJS e IIFE (`window.Gu1Sdk` para inyección por `<script>`)
Distribución	npm privado (scope `@gu1` — solicitá acceso de lectura a Gu1)

1. Instalación

El SDK se distribuye por npm privado (scope @gu1, paquete restricted), así que npm install devuelve 404 sin acceso de lectura al scope. Pedile a Gu1 un token de lectura y configurá un .npmrc en tu proyecto, pasando el token por variable de entorno (nunca lo commitees). El canal <script> (CDN) no necesita token.

Con bundler (ESM / CommonJS) — creá un .npmrc en tu proyecto:

# .npmrc
@gu1:registry=https://registry.npmjs.org
//registry.npmjs.org/:_authToken=${GU1_NPM_TOKEN}

export GU1_NPM_TOKEN=<token que te da Gu1>
npm install @gu1/sdk-web@latest

Sin bundler, vía <script> (build IIFE — expone window.Gu1Sdk). Cargalo desde la CDN de Gu1 con la versión fijada y el hash SRI (cada release publica su propia URL v<versión>):

<script
  src="https://cdn.gu1.ai/sdk/web/v1.7.0/gu1-sdk.min.js"
  integrity="sha384-ToGjHjLb86+UB0qIH90hcSbT75SNn3dYC/CDCqJmg1bD0P3XC7jByG5e87xJi8u3"
  crossorigin="anonymous"></script>

Content Security Policy: si la página aplica CSP, permití connect-src https://api.<tenant>.gu1.ai (el SDK envía eventos y lee /sdk/config) y — solo para el canal <script> — script-src https://cdn.gu1.ai.

2. Inicialización

Con bundler (ESM):

import { createGu1SDK } from '@gu1/sdk-web'

const gu1 = await createGu1SDK({
  apiKey: 'gk_xxx',                     // la provee Gu1 (sandbox y producción)
  apiUrl: 'https://api.<tenant>.gu1.ai' // la URL de tu instancia, la provee Gu1
})

Vía <script> (IIFE), el SDK queda disponible en window.Gu1Sdk:

<script>
  window.Gu1Sdk.createGu1SDK({
    apiKey: 'gk_xxx',
    apiUrl: 'https://api.<tenant>.gu1.ai'
  }).then((gu1) => {
    // gu1.getSessionId() ya disponible
  })
</script>

Desde este momento el SDK genera un sessionId anónimo, recolecta señales del dispositivo (canvas, WebGL, navigator) e integridad del entorno, y las envía en segundo plano. No hay nada más que hacer en la página para la captura de señales.

3. El sessionId hacia tu backend (1 header)

Para que tus eventos de backend queden vinculados a la sesión del dispositivo, agregá el sessionId como header en las llamadas de la web app a tu propio backend:

// En tu cliente HTTP (interceptor de axios/fetch):
headers['X-Gu1-Session-Id'] = gu1.getSessionId()

Y en tu backend:

Primer request autenticado: enviá a Gu1 un evento con sessionId + el entityExternalId del usuario. Gu1 vincula retroactivamente toda la sesión, incluido lo anterior al login.
Eventos existentes: a los eventos que ya envías a POST /events/user sumales el campo sessionId (camelCase, opcional — los eventos sin él siguen funcionando igual).

POST /events/user
{
  "eventType": "LOGIN_SUCCESS",
  "entityExternalId": "user_123",
  "sessionId": "sess_abc123",
  "metadata": { }
}

4. Transacciones (1 línea)

En las transacciones que envías a Gu1, el sessionId viaja en metadata:

POST /transactions
{
  "amount": 50000,
  "metadata": { "sessionId": "sess_abc123" }
}

Con esto, el motor de reglas evalúa cada transacción con el contexto completo de la sesión: dispositivo, integridad, recorrido y eventos.

5. Verificación

Cargá la página en sandbox → en el dashboard de Gu1 aparece la sesión con las señales del dispositivo.
Iniciá sesión → la sesión queda vinculada al usuario (binding retroactivo).
Ejecutá una transacción de prueba → la transacción muestra el contexto de sesión en su evaluación.

Resumen de la integración

Paso	Dónde	Esfuerzo
Instalar + inicializar	Web app	~15 min
Header `X-Gu1-Session-Id`	Web app (cliente HTTP)	1 línea
`sessionId` en eventos + binding	Backend (middleware)	~1 hora
`sessionId` en transacciones	Backend	1 línea

Las señales nuevas que Gu1 active a futuro se habilitan por configuración remota — sin redeploys de tu web app, sin coordinación.

Comenzando

SDK

Casos de Uso

Webhooks

Workflows

Monitoreo (entidades)

Persona

Mensajería

Empresa

Dispositivos

Eventos

Conozca Su Cliente (KYC)

Transacciones

Métodos de Pago

Reglas

Listas personalizadas

Matriz de Riesgo

Alertas

Investigaciones

Ingesta de Datos

Importaciones masivas

Documentos

Enriquecimiento

AML Crypto

Servicios

Integraciones

Tutoriales Interactivos

Quickstart — SDK para Web

Qué hace el SDK (y qué no)

1. Instalación

2. Inicialización

3. El sessionId hacia tu backend (1 header)

4. Transacciones (1 línea)

5. Verificación

Resumen de la integración

​Qué hace el SDK (y qué no)

​1. Instalación

​2. Inicialización

​3. El sessionId hacia tu backend (1 header)

​4. Transacciones (1 línea)

​5. Verificación

​Resumen de la integración

Qué hace el SDK (y qué no)

1. Instalación

2. Inicialización

3. El sessionId hacia tu backend (1 header)

4. Transacciones (1 línea)

5. Verificación

Resumen de la integración