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

> Integra el SDK de Gu1 para React Native en tu app móvil 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)

El SDK de Gu1 corre dentro de tu app y captura lo que el backend no puede ver: señales del dispositivo, integridad del entorno y el recorrido de pantallas — incluido el tramo **anterior al login**. Los eventos que hoy 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 app, nunca propaga errores (la única excepción es configuración inválida en la inicialización), no requiere ningún permiso y no accede a datos del usuario.

|                     |                                                               |
| ------------------- | ------------------------------------------------------------- |
| Peso                | \~150 KB                                                      |
| Permisos requeridos | Ninguno                                                       |
| Requisitos          | React Native 0.71+, iOS 13+, Android 6+ (API 23)              |
| 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>

```bash theme={null}
npm install @gu1/sdk-react-native@latest react-native-keychain react-native-get-random-values
cd ios && pod install
```

No requiere cambios en `AndroidManifest.xml` ni en `Info.plist`. El SDK es **backward-compatible**: funciona tanto con la New Architecture como con la arquitectura clásica de React Native (RN 0.71+), sin configuración extra.

## 2. Inicialización (en el entry point de la app)

```typescript theme={null}
import 'react-native-get-random-values'
import { createGu1SDK } from '@gu1/sdk-react-native'

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
})
```

Desde este momento el SDK genera un `sessionId` anónimo, colecta señales del dispositivo y las envía en segundo plano. No hay nada más que hacer en la app para la captura de señales.

## 3. Tracking de pantallas (recomendado — 5 líneas)

Con React Navigation, el SDK captura navegación y tiempos de pantalla automáticamente:

```typescript theme={null}
import { createScreenTracker } from '@gu1/sdk-react-native'

const screenTracker = createScreenTracker(gu1)

<NavigationContainer
  onReady={screenTracker.onReady}
  onStateChange={screenTracker.onStateChange}
>
```

No hace falta instrumentar cada pantalla a mano: esto es todo.

## 4. 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 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": { }
}
```

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

## 6. Verificación

1. Inicializá la app en sandbox → en el dashboard de Gu1 aparece la sesión con las señales del dispositivo.
2. Navegá entre pantallas → eventos `NAVIGATION` automáticos.
3. Iniciá sesión → la sesión queda vinculada al usuario (binding retroactivo).
4. Ejecutá una transferencia 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           | App                  | \~15 min |
| Screen tracking                  | App                  | 5 líneas |
| Header `X-Gu1-Session-Id`        | 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 releases de tu app, sin coordinación.