Quickstart — SDK para React Native

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

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.

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)

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

Inicialize o app em sandbox → a sessão aparece no dashboard da Gu1 com os sinais do dispositivo.
Navegue entre telas → eventos NAVIGATION automáticos.
Faça login → a sessão fica vinculada ao usuário (binding retroativo).
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.

Começando

SDK

Casos de Uso

Webhooks

Workflows

Monitoramento (entidades)

Pessoa

Mensagens

Empresa

Dispositivos

Eventos

Conheça Seu Cliente (KYC)

Transações

Métodos de Pagamento

Regras

Listas de dados

Matriz de Risco

Alertas

Investigações

Ingestão de Dados

Importações em lote

Enriquecimento

Serviços

Integrações

Tutoriais Interativos

Quickstart — SDK para React Native

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

1. Instalação

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

3. Rastreamento de telas (recomendado — 5 linhas)

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

5. Transações (1 linha)

6. Verificação

Resumo da integração

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

​1. Instalação

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

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

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

​5. Transações (1 linha)

​6. Verificação

​Resumo da integração

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

1. Instalação

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

3. Rastreamento de telas (recomendado — 5 linhas)

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

5. Transações (1 linha)

6. Verificação

Resumo da integração