Quickstart — Web SDK

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

The SDK ships via private npm (scope @gu1, restricted package), so npm install returns 404 without read access to the scope. Ask Gu1 for a read-only token and configure an .npmrc in your project, passing the token via an environment variable (never commit it). The <script> (CDN) channel needs no token.

With a bundler (ESM / CommonJS) — add an .npmrc to your project:

# .npmrc
@gu1:registry=https://registry.npmjs.org
//registry.npmjs.org/:_authToken=${GU1_NPM_TOKEN}

export GU1_NPM_TOKEN=<token Gu1 gives you>
npm install @gu1/sdk-web@latest

Without a bundler, via <script> (IIFE build — exposes window.Gu1Sdk). Load it from the Gu1 CDN with the version pinned and the SRI hash (each release publishes its own v<version> URL):

<script
  src="https://cdn.gu1.ai/sdk/web/v1.7.0/gu1-sdk.min.js"
  integrity="sha384-ToGjHjLb86+UB0qIH90hcSbT75SNn3dYC/CDCqJmg1bD0P3XC7jByG5e87xJi8u3"
  crossorigin="anonymous"></script>

Content Security Policy: if the page enforces a CSP, allow connect-src https://api.<tenant>.gu1.ai (the SDK sends events and reads /sdk/config) and — only for the <script> channel — script-src https://cdn.gu1.ai.

2. Initialize

With a bundler (ESM):

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:

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

// 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": { }
}

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

5. Verify

Load the page in sandbox → the session appears in your Gu1 dashboard with device signals.
Log in → the session gets bound to the user (retroactive binding).
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.

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

AML Crypto

Services

Integrations

Interactive Tutorials

Quickstart — Web SDK

What the SDK Does (and Doesn’t Do)

1. Install

2. Initialize

3. The sessionId Towards Your Backend (1 Header)

4. Transactions (1 Line)

5. Verify

Integration Summary

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

​1. Install

​2. Initialize

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

​4. Transactions (1 Line)

​5. Verify

​Integration Summary

What the SDK Does (and Doesn’t Do)

1. Install

2. Initialize

3. The sessionId Towards Your Backend (1 Header)

4. Transactions (1 Line)

5. Verify

Integration Summary