> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart — React Native SDK

> Integrate the Gu1 React Native SDK into your mobile app in minutes: device intelligence, session signals, and real-time fraud prevention.

## 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

<Note>
  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.
</Note>

```bash theme={null}
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)

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
// 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.

```json theme={null}
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:

```json theme={null}
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

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