Skip to main content

​
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 permissionsNone
RequirementsReact Native 0.71+, iOS 13+, Android 6+ (API 23)
DistributionPrivate npm (scope @gu1 — request read access from Gu1)

​
1. Install

npm install @gu1/sdk-react-native react-native-keychain react-native-get-random-values
cd ios && pod install
No changes to AndroidManifest.xml or Info.plist are required.

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

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

​
Integration summary

StepWhereEffort
Install + initApp~15 min
Screen trackingApp5 lines
X-Gu1-Session-Id headerApp (HTTP client)1 line
sessionId on events + bindingBackend (middleware)~1 hour
sessionId on transactionsBackend1 line
Any new signals Gu1 enables in the future are switched on through remote configuration — no app releases, no coordination required.