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). 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.
npm install @gu1/sdk-web@latest
<script> (build IIFE — expone window.Gu1Sdk). Serví el bundle desde tu propio origen:
<script src="/assets/gu1-sdk-web.iife.js"></script>
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
})
<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>
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.
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()
- 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" }
}
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 |
