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.

​
1. Instalação

O SDK é distribuído por npm privado (escopo @gu1, pacote restricted), então npm install retorna 404 sem acesso de leitura ao escopo. Solicite à Gu1 um token de leitura e configure um .npmrc no seu projeto, passando o token por variável de ambiente (nunca faça commit dele). O canal <script> (CDN) não precisa de token.
Com bundler (ESM / CommonJS) — crie um .npmrc no seu projeto:
Sem bundler, via <script> (build IIFE — expõe window.Gu1Sdk). Carregue a partir da CDN da Gu1 com a versão fixada e o hash SRI (cada release publica sua própria URL v<versão>):
Content Security Policy: se a página aplica CSP, permita connect-src https://api.<tenant>.gu1.ai (o SDK envia eventos e lê /sdk/config) e — apenas para o canal <script> — script-src https://cdn.gu1.ai.

​
2. Inicialização

Com bundler (ESM):
Via <script> (IIFE), o SDK fica disponível em window.Gu1Sdk:
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:
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.

​
4. Transações (1 linha)

Nas transações que você envia à Gu1, o sessionId viaja no metadata:
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

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