> ## 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 — Web SDK

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

## What the SDK Does (and Doesn't Do)

`@gu1/sdk-web` is the browser channel of the Gu1 SDK: it runs inside your web app and captures what your backend cannot see — device signals (canvas, WebGL, `navigator` properties), environment integrity, and the user journey, including everything **before login**. It shares the event model with the React Native SDK: 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 the page, never propagates errors (the only exception is invalid configuration at init), and does not access user data.

|              |                                                                    |
| ------------ | ------------------------------------------------------------------ |
| Environments | Modern browsers                                                    |
| Builds       | ESM, CommonJS, and IIFE (`window.Gu1Sdk` for `<script>` injection) |
| 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>

With a bundler (ESM / CommonJS):

```bash theme={null}
npm install @gu1/sdk-web@latest
```

Without a bundler, via `<script>` (IIFE build — exposes `window.Gu1Sdk`). Serve the bundle from your own origin:

```html theme={null}
<script src="/assets/gu1-sdk-web.iife.js"></script>
```

## 2. Initialize

With a bundler (ESM):

```typescript theme={null}
import { createGu1SDK } from '@gu1/sdk-web'

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
})
```

Via `<script>` (IIFE), the SDK is available on `window.Gu1Sdk`:

```html theme={null}
<script>
  window.Gu1Sdk.createGu1SDK({
    apiKey: 'gk_xxx',
    apiUrl: 'https://api.<tenant>.gu1.ai'
  }).then((gu1) => {
    // gu1.getSessionId() is now available
  })
</script>
```

From this moment the SDK generates an anonymous `sessionId`, collects device signals (canvas, WebGL, `navigator`) and environment integrity, and ships them in the background. Nothing else is required on the page for signal capture.

## 3. The sessionId Towards Your Backend (1 Header)

To link your backend events to the device session, attach the `sessionId` as a header on the web 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": { }
}
```

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

## 5. Verify

1. Load the page in sandbox → the session appears in your Gu1 dashboard with device signals.
2. Log in → the session gets bound to the user (retroactive binding).
3. Run a test transaction → the transaction shows session context in its evaluation.

## Integration Summary

| Step                            | Where                 | Effort   |
| ------------------------------- | --------------------- | -------- |
| Install + init                  | Web app               | \~15 min |
| `X-Gu1-Session-Id` header       | Web 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 web app redeploys, no coordination required.