Skip to main content

​
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 exigidasNenhuma
RequisitosReact Native 0.71+, iOS 13+, Android 6+ (API 23)
Distribuiçãonpm privado (escopo @gu1 — solicite acesso de leitura à Gu1)

​
1. Instalação

npm install @gu1/sdk-react-native react-native-keychain react-native-get-random-values
cd ios && pod install
Não exige alterações no AndroidManifest.xml nem no Info.plist.

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

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: 
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: 
// 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": { }
}

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

​
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

PassoOndeEsforço
Instalar + inicializarApp~15 min
Rastreamento de telasApp5 linhas
Header X-Gu1-Session-IdApp (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 releases do app, sem coordenação.