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

> Integre o SDK da Gu1 para navegador no seu web app 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)

`@gu1/sdk-web` é o canal navegador do SDK da Gu1: roda dentro do seu web app e captura o que o backend não consegue ver — sinais do dispositivo (canvas, WebGL, propriedades de `navigator`), integridade do ambiente e a jornada do usuário, incluindo tudo o que acontece **antes do login**. Ele compartilha o modelo de eventos com o SDK de React Native: os eventos que você já envia do seu backend **continuam exatamente iguais**, apenas carregam um `sessionId` adicional para que o motor da Gu1 cruze os dois mundos.

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

|              |                                                                    |
| ------------ | ------------------------------------------------------------------ |
| Ambientes    | Navegadores modernos                                               |
| Builds       | ESM, CommonJS e IIFE (`window.Gu1Sdk` para injeção via `<script>`) |
| 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>

Com bundler (ESM / CommonJS):

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

Sem bundler, via `<script>` (build IIFE — expõe `window.Gu1Sdk`). Sirva o bundle a partir do seu próprio origin:

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

## 2. Inicialização

Com bundler (ESM):

```typescript theme={null}
import { createGu1SDK } from '@gu1/sdk-web'

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

Via `<script>` (IIFE), o SDK fica disponível em `window.Gu1Sdk`:

```html theme={null}
<script>
  window.Gu1Sdk.createGu1SDK({
    apiKey: 'gk_xxx',
    apiUrl: 'https://api.<tenant>.gu1.ai'
  }).then((gu1) => {
    // gu1.getSessionId() já disponível
  })
</script>
```

A partir desse momento o SDK gera um `sessionId` anônimo, coleta sinais do dispositivo (canvas, WebGL, `navigator`) e integridade do ambiente, e os envia em segundo plano. Nada mais é necessário na página para a captura de sinais.

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

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

## 5. Verificação

1. Carregue a página em sandbox → a sessão aparece no dashboard da Gu1 com os sinais do dispositivo.
2. Faça login → a sessão fica vinculada ao usuário (binding retroativo).
3. Execute uma transação 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            | Web app                | \~15 min |
| Header `X-Gu1-Session-Id`         | Web 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 redeploys do web app, sem coordenação.