> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart — SDK para Web

> Integra el SDK de Gu1 para navegador en tu web app en minutos: inteligencia de dispositivo, señales de sesión y prevención de fraude en tiempo real.

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

<Note>
  El SDK se distribuye por **npm privado** (scope `@gu1`, paquete `restricted`). El comando de abajo devuelve `404` si tu entorno no tiene acceso de lectura al scope `@gu1`: **contactá a tu equipo de Gu1 para el acceso al paquete privado** antes de instalar.
</Note>

Con bundler (ESM / CommonJS):

```bash theme={null}
npm install @gu1/sdk-web@latest
```

Sin bundler, vía `<script>` (build IIFE — expone `window.Gu1Sdk`). Serví el bundle desde tu propio origen:

```html theme={null}
<script src="/assets/gu1-sdk-web.iife.js"></script>
```

## 2. Inicialización

Con bundler (ESM):

```typescript theme={null}
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`:

```html theme={null}
<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:

```typescript theme={null}
// 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).

```json theme={null}
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:

```json theme={null}
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

1. Cargá la página en sandbox → en el dashboard de Gu1 aparece la sesión con las señales del dispositivo.
2. Iniciá sesión → la sesión queda vinculada al usuario (binding retroactivo).
3. 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.