Skip to main content

​
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.
EnvironmentsModern browsers
BuildsESM, CommonJS, and IIFE (window.Gu1Sdk for <script> injection)
DistributionPrivate 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.
With a bundler (ESM / CommonJS): 
npm install @gu1/sdk-web@latest
Without a bundler, via <script> (IIFE build — exposes window.Gu1Sdk). Serve the bundle from your own origin: 
<script src="/assets/gu1-sdk-web.iife.js"></script>

​
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

  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

StepWhereEffort
Install + initWeb app~15 min
X-Gu1-Session-Id headerWeb app (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 web app redeploys, no coordination required.