Quickstart — React Native SDK

What the SDK Does (and Doesn’t Do)

The Gu1 SDK runs inside your app and captures what your backend cannot see: device signals, environment integrity, and the screen journey — including everything before login. The events you already send from your backend stay exactly as they are: they just carry an extra sessionId so the Gu1 engine can join both worlds. The SDK is fail-open by design: it never blocks your app, never propagates errors (the only exception is invalid configuration at init), requires no permissions, and does not access user data.


Size	~150 KB
Required permissions	None
Requirements	React Native 0.71+, iOS 13+, Android 6+ (API 23)
Distribution	Private npm (scope `@gu1` — request read access from Gu1)

1. Install

The SDK ships via private npm (scope @gu1, restricted package). The command below returns 404 if your environment lacks read access to the @gu1 scope: contact your Gu1 team for private package access before installing.

npm install @gu1/sdk-react-native@latest react-native-keychain react-native-get-random-values
cd ios && pod install

No changes to AndroidManifest.xml or Info.plist are required. The SDK is backward-compatible: it works on both the New Architecture and the classic React Native architecture (RN 0.71+), with no extra configuration.

2. Initialize (at Your App’s Entry Point)

import 'react-native-get-random-values'
import { createGu1SDK } from '@gu1/sdk-react-native'

const gu1 = await createGu1SDK({
  apiKey: 'gk_xxx',                     // provided by Gu1 (sandbox and production)
  apiUrl: 'https://api.<tenant>.gu1.ai' // your instance URL, provided by Gu1
})

From this moment the SDK generates an anonymous sessionId, collects device signals, and ships them in the background. Nothing else is required in the app for signal capture.

3. Screen Tracking (Recommended — 5 Lines)

With React Navigation, the SDK captures navigation and screen timings automatically:

import { createScreenTracker } from '@gu1/sdk-react-native'

const screenTracker = createScreenTracker(gu1)

<NavigationContainer
  onReady={screenTracker.onReady}
  onStateChange={screenTracker.onStateChange}
>

No per-screen manual instrumentation: this is all of it.

4. The sessionId Towards Your Backend (1 Header)

To link your backend events to the device session, attach the sessionId as a header on the app’s calls to your own backend:

// In your HTTP client (axios/fetch interceptor):
headers['X-Gu1-Session-Id'] = gu1.getSessionId()

Then on your backend:

First authenticated request: send Gu1 an event with the sessionId + the user’s entityExternalId. Gu1 retroactively binds the whole session, including everything before login.
Existing events: add the optional camelCase sessionId field to the events you already send to POST /events/user — events without it keep working unchanged.

POST /events/user
{
  "eventType": "LOGIN_SUCCESS",
  "entityExternalId": "user_123",
  "sessionId": "sess_abc123",
  "metadata": { }
}

5. Transactions (1 Line)

On the transactions you send to Gu1, the sessionId travels in metadata:

POST /transactions
{
  "amount": 50000,
  "metadata": { "sessionId": "sess_abc123" }
}

With this in place, the rules engine evaluates every transaction with full session context: device, integrity, journey, and events.

6. Verify

Launch the app in sandbox → the session appears in your Gu1 dashboard with device signals.
Navigate between screens → automatic NAVIGATION events.
Log in → the session gets bound to the user (retroactive binding).
Run a test transfer → the transaction shows session context in its evaluation.

Integration Summary

Step	Where	Effort
Install + init	App	~15 min
Screen tracking	App	5 lines
`X-Gu1-Session-Id` header	App (HTTP client)	1 line
`sessionId` on events + binding	Backend (middleware)	~1 hour
`sessionId` on transactions	Backend	1 line

Any new signals Gu1 enables in the future are switched on through remote configuration — no app releases, no coordination required.

Getting Started

SDK

Use Cases

Webhooks

Workflows

Monitoring (entities)

Person

Messaging

Company

Transactions

Devices

Events

Know Your Customer (KYC)

Payment Methods

Rules

Custom lists

Risk Matrix

Alerts

Investigations

Data Ingestion

Bulk imports

Documents

Enrichment

Services

Integrations

Interactive Tutorials

Quickstart — React Native SDK

What the SDK Does (and Doesn’t Do)

1. Install

2. Initialize (at Your App’s Entry Point)

3. Screen Tracking (Recommended — 5 Lines)

4. The sessionId Towards Your Backend (1 Header)

5. Transactions (1 Line)

6. Verify

Integration Summary

​What the SDK Does (and Doesn’t Do)

​1. Install

​2. Initialize (at Your App’s Entry Point)

​3. Screen Tracking (Recommended — 5 Lines)

​4. The sessionId Towards Your Backend (1 Header)

​5. Transactions (1 Line)

​6. Verify

​Integration Summary

What the SDK Does (and Doesn’t Do)

1. Install

2. Initialize (at Your App’s Entry Point)

3. Screen Tracking (Recommended — 5 Lines)

4. The sessionId Towards Your Backend (1 Header)

5. Transactions (1 Line)

6. Verify

Integration Summary