Skip to main content

​
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.
AmbientesNavegadores modernos
BuildsESM, CommonJS e IIFE (window.Gu1Sdk para injeção via <script>)
Distribuiçãonpm privado (escopo @gu1 — solicite acesso de leitura à Gu1)

​
1. Instalação

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.
Com bundler (ESM / CommonJS): 
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: 
<script src="/assets/gu1-sdk-web.iife.js"></script>

​
2. Inicialização

Com bundler (ESM): 
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: 
<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: 
// 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.
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: 
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

PassoOndeEsforço
Instalar + inicializarWeb app~15 min
Header X-Gu1-Session-IdWeb app (cliente HTTP)1 linha
sessionId nos eventos + bindingBackend (middleware)~1 hora
sessionId nas transaçõesBackend1 linha
Novos sinais que a Gu1 ativar no futuro são habilitados por configuração remota — sem redeploys do web app, sem coordenação.