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

> Integre o SDK da Gu1 para React Native no seu app mobile em minutos: inteligência de dispositivo, sinais de sessão e prevenção de fraude em tempo real.

## O que o SDK faz (e o que não faz)

O SDK da Gu1 roda dentro do seu app e captura o que o backend não consegue ver: sinais do dispositivo, integridade do ambiente e a jornada de telas — incluindo tudo o que acontece **antes do login**. Os eventos que você já envia do seu backend **continuam exatamente iguais**: eles apenas carregam um `sessionId` adicional para que o motor da Gu1 cruze os dois mundos.

O SDK é **fail-open por design**: nunca bloqueia o app, nunca propaga erros (a única exceção é configuração inválida na inicialização), não exige nenhuma permissão e não acessa dados do usuário.

|                     |                                                                |
| ------------------- | -------------------------------------------------------------- |
| Tamanho             | \~150 KB                                                       |
| Permissões exigidas | Nenhuma                                                        |
| Requisitos          | React Native 0.71+, iOS 13+, Android 6+ (API 23)               |
| Distribuição        | npm privado (escopo `@gu1` — solicite acesso de leitura à Gu1) |

## 1. Instalação

<Note>
  O SDK é distribuído por **npm privado** (escopo `@gu1`, pacote `restricted`). O comando abaixo retorna `404` se o seu ambiente não tiver acesso de leitura ao escopo `@gu1`: **entre em contato com o seu time da Gu1 para o acesso ao pacote 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
```

Não exige alterações no `AndroidManifest.xml` nem no `Info.plist`. O SDK é **backward-compatible**: funciona tanto com a New Architecture quanto com a arquitetura clássica do React Native (RN 0.71+), sem configuração extra.

## 2. Inicialização (no entry point do app)

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

const gu1 = await createGu1SDK({
  apiKey: 'gk_xxx',                     // fornecida pela Gu1 (sandbox e produção)
  apiUrl: 'https://api.<tenant>.gu1.ai' // a URL da sua instância, fornecida pela Gu1
})
```

A partir desse momento o SDK gera um `sessionId` anônimo, coleta sinais do dispositivo e os envia em segundo plano. Nada mais é necessário no app para a captura de sinais.

## 3. Rastreamento de telas (recomendado — 5 linhas)

Com React Navigation, o SDK captura navegação e tempos de tela automaticamente:

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

const screenTracker = createScreenTracker(gu1)

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

Sem instrumentação manual por tela: isso é tudo.

## 4. O sessionId até o seu backend (1 header)

Para vincular os eventos do seu backend à sessão do dispositivo, adicione o `sessionId` como header nas chamadas do app ao seu próprio backend:

```typescript theme={null}
// No seu cliente HTTP (interceptor de axios/fetch):
headers['X-Gu1-Session-Id'] = gu1.getSessionId()
```

E no seu backend:

* **Primeira requisição autenticada:** envie à Gu1 um evento com o `sessionId` + o `entityExternalId` do usuário. A Gu1 vincula retroativamente toda a sessão, incluindo o que aconteceu antes do login.
* **Eventos existentes:** adicione o campo opcional `sessionId` (camelCase) aos eventos que você já envia para `POST /events/user` — eventos sem ele continuam funcionando normalmente.

```json theme={null}
POST /events/user
{
  "eventType": "LOGIN_SUCCESS",
  "entityExternalId": "user_123",
  "sessionId": "sess_abc123",
  "metadata": { }
}
```

## 5. Transações (1 linha)

Nas transações que você envia à Gu1, o `sessionId` viaja no metadata:

```json theme={null}
POST /transactions
{
  "amount": 50000,
  "metadata": { "sessionId": "sess_abc123" }
}
```

Com isso, o motor de regras avalia cada transação com o contexto completo da sessão: dispositivo, integridade, jornada e eventos.

## 6. Verificação

1. Inicialize o app em sandbox → a sessão aparece no dashboard da Gu1 com os sinais do dispositivo.
2. Navegue entre telas → eventos `NAVIGATION` automáticos.
3. Faça login → a sessão fica vinculada ao usuário (binding retroativo).
4. Execute uma transferência de teste → a transação mostra o contexto da sessão na sua avaliação.

## Resumo da integração

| Passo                             | Onde                 | Esforço  |
| --------------------------------- | -------------------- | -------- |
| Instalar + inicializar            | App                  | \~15 min |
| Rastreamento de telas             | App                  | 5 linhas |
| Header `X-Gu1-Session-Id`         | App (cliente HTTP)   | 1 linha  |
| `sessionId` nos eventos + binding | Backend (middleware) | \~1 hora |
| `sessionId` nas transações        | Backend              | 1 linha  |

Novos sinais que a Gu1 ativar no futuro são habilitados por configuração remota — sem releases do app, sem coordenação.