Web SDK

The Web SDK is currently in alpha. APIs and behavior may change between releases.

Who is this for? Web developers building web games, marketing sites, or SPAs who need explicit event tracking, user identity, or SPA support. Works with any framework (React, Next.js, Svelte, vanilla JS).

The Immutable Web SDK is a typed package for tracking player behavior as part of the Immutable attribution system. UTM parameters, click IDs, and referrer data are captured automatically, connecting ad campaigns to the players they drove. Page views are tracked by calling page() on each route change, and in-game moments like progressions, purchases, and sign-ups are triggered by your code. All events flow to the same pipeline as the Unity SDK and REST API.

What You Need

An Immutable Hub account with a project (get started here)
A publishable key from your project settings (API keys guide)

Installation

npm
yarn
pnpm
CDN

npm install @imtbl/audience

yarn add @imtbl/audience

pnpm add @imtbl/audience

<script src="https://cdn.immutable.com/audience/v1/imtbl.js"></script>

The CDN bundle attaches ImmutableAudience to window with the same API surface: init, AudienceEvents, IdentityType, canTrack, canIdentify, and version.

If your site uses a Content Security Policy, see Content Security Policy for the directives CDN users need to allow.

Quick Start

Initialize the SDK

import { Audience, AudienceEvents, IdentityType } from '@imtbl/audience';

const audience = Audience.init({
  publishableKey: 'YOUR_PUBLISHABLE_KEY',
});

<script src="https://cdn.immutable.com/audience/v1/imtbl.js"></script>
<script>
  var audience = ImmutableAudience.init({
    publishableKey: 'YOUR_PUBLISHABLE_KEY',
  });
</script>

Subsequent steps call methods on the audience variable. AudienceEvents and IdentityType are available as ImmutableAudience.AudienceEvents and ImmutableAudience.IdentityType.

Consent defaults to 'none'. The SDK won’t track anything until you explicitly set a consent level.

Set consent

The SDK uses a three-tier consent model ('none', 'anonymous', 'full'). The SDK does not provide a consent UI. Build your own cookie banner or privacy prompt, then call setConsent with the appropriate level when the user responds.

// User accepts anonymous tracking
audience.setConsent('anonymous');

// User logs in and accepts full tracking
audience.setConsent('full');

At 'anonymous', page views and events are tracked but identify() and alias() calls are dropped. At 'full', all methods are available. See the Data Dictionary for what is collected at each level.

Track page views

Call page() on each route change. The first call in each session includes attribution parameters.

audience.page();

Track events

Log player actions with track(). The SDK ships with predefined events for common player actions (purchases, sign-ups, progression, wishlist actions, and more) that give you typed properties and autocomplete. You can also pass any custom event string.

// Predefined event — typed properties
audience.track(AudienceEvents.SIGN_UP, { method: 'email' });
audience.track(AudienceEvents.PURCHASE, { currency: 'USD', value: '9.99' });

// Custom event — any properties
audience.track('tutorial_complete', { stepCount: 5 });

// Predefined event — typed properties
audience.track(ImmutableAudience.AudienceEvents.SIGN_UP, { method: 'email' });
audience.track(ImmutableAudience.AudienceEvents.PURCHASE, { currency: 'USD', value: '9.99' });

// Custom event — any properties
audience.track('tutorial_complete', { stepCount: 5 });

Identify users

Identifies the player by associating their userId with their activity and traits. Call at login or account connection. Requires 'full' consent.

audience.identify('player-123', IdentityType.Passport, {
  email: 'user@example.com',
});

audience.identify('player-123', ImmutableAudience.IdentityType.Passport, {
  email: 'user@example.com',
});

Clean up on exit

Flushes the queue and shuts down the SDK.

audience.shutdown();

Complete Example

import { Audience, AudienceEvents, IdentityType } from '@imtbl/audience';

// 1. Initialize
const audience = Audience.init({
  publishableKey: 'YOUR_PUBLISHABLE_KEY',
});

// 2. Set consent after cookie banner
audience.setConsent('anonymous');

// 3. Track page views on route changes
audience.page();

// 4. Track player actions
audience.track(AudienceEvents.PURCHASE, { currency: 'USD', value: '9.99' });

// 5. Identify after login (requires 'full' consent)
audience.setConsent('full');
audience.identify('player-123', IdentityType.Passport, { email: 'user@example.com' });

// 6. Clean up on exit
audience.shutdown();

<script src="https://cdn.immutable.com/audience/v1/imtbl.js"></script>
<script>
  // 1. Initialize
  var audience = ImmutableAudience.init({
    publishableKey: 'YOUR_PUBLISHABLE_KEY',
  });

  // 2. Set consent after cookie banner
  audience.setConsent('anonymous');

  // 3. Track page views on route changes
  audience.page();

  // 4. Track player actions
  audience.track(ImmutableAudience.AudienceEvents.PURCHASE, {
    currency: 'USD',
    value: '9.99',
  });

  // 5. Identify after login (requires 'full' consent)
  audience.setConsent('full');
  audience.identify('player-123', ImmutableAudience.IdentityType.Passport, {
    email: 'user@example.com',
  });

  // 6. Clean up on exit
  audience.shutdown();
</script>

Auto-Capture

The SDK captures form submissions, outbound link clicks, and scroll depth by default. Internal link clicks and button clicks are off by default, since they can be noisy on interactive pages. Turn them on where the extra signal is useful, such as measuring whether players open a #trailer modal or click a call-to-action. Use the autocapture option to control what’s collected:

const audience = Audience.init({
  publishableKey: 'YOUR_PUBLISHABLE_KEY',
  consent: 'anonymous',
  autocapture: {
    internalClicks: true,
    buttons: true,
    forms: false,
  },
});

Omit an option to keep its default. Set forms, clicks, and scroll to false to disable auto-capture entirely and rely only on your manual page() and track() calls. See form_submitted and scroll_depth for exact property shapes. link_clicked shares its schema with the predefined event of the same name: a manual track('link_clicked', ...) call for a link auto-capture can’t see looks identical on the wire.

Verify the Integration

Initialize with debug: true to see SDK activity in the browser console:

const audience = Audience.init({
  publishableKey: 'YOUR_PUBLISHABLE_KEY',
  debug: true,
});

Console: Look for log entries showing page and any track() calls
Network tab: Look for POST requests to https://api.immutable.com. Events flush every 5 seconds or when 20 events accumulate

Remove debug: true before deploying to production.

Content Security Policy

If your site enforces a Content-Security-Policy header, add the event endpoint so the SDK can deliver events:

connect-src: https://api.immutable.com

If you load the SDK from Immutable’s CDN, also add the script host:

script-src: https://cdn.immutable.com

If you install the SDK as a package dependency (npm/yarn/pnpm), only connect-src is required. The CDN directive is only needed for the <script>-tag installation.

For nonce-based CSP (CDN install only), add the nonce attribute to your inline <script> tag. The nonce covers the inline code only. The CDN-loaded script is authorized by the script-src directive above.

<script src="https://cdn.immutable.com/audience/v1/imtbl.js"></script>
<script nonce="YOUR_NONCE">
  var audience = ImmutableAudience.init({ publishableKey: 'YOUR_PUBLISHABLE_KEY' });
  audience.setConsent('anonymous');
  audience.page();
</script>

API Reference

Audience.init(config)

Creates and returns an Audience instance. Call once when your app loads to set up tracking.

Parameter	Type	Required	Default	Description
`publishableKey`	`string`	Yes	—	API key from Hub
`consent`	`'none' \| 'anonymous' \| 'full'`	No	`'none'`	Initial consent level
`debug`	`boolean`	No	`false`	Log SDK activity to the browser console
`testMode`	`boolean`	No	`false`	When `true`, stamps all events with `test: true` so they can be filtered from production analytics.
`cookieDomain`	`string`	No	Current domain	Share cookies across subdomains (e.g. `'.studio.com'`).
`flushInterval`	`number`	No	`5000`	How often the queue flushes, in milliseconds
`flushSize`	`number`	No	`20`	Number of queued messages that triggers a flush
`baseUrl`	`string`	No	Immutable API	Override the default API base URL
`onError`	`(err: AudienceError) => void`	No	`undefined`	Callback for failures. `err.code` is one of `'FLUSH_FAILED'`, `'CONSENT_SYNC_FAILED'`, `'DATA_DELETE_FAILED'`, `'NETWORK_ERROR'`, `'VALIDATION_REJECTED'`, `'RATE_LIMITED'`
`autocapture.forms`	`boolean`	No	`true`	Auto-capture HTML form submissions
`autocapture.clicks`	`boolean`	No	`true`	Auto-capture clicks on links to external domains
`autocapture.internalClicks`	`boolean`	No	`false`	Auto-capture clicks on same-domain links, including `#hash` links
`autocapture.buttons`	`boolean`	No	`false`	Auto-capture button clicks. Form submit buttons are already captured by `form_submitted`, so they’re excluded.
`autocapture.scroll`	`boolean`	No	`true`	Auto-capture scroll depth milestones

const audience = Audience.init({
  publishableKey: 'YOUR_PUBLISHABLE_KEY',
  consent: 'none',
  debug: true,
  cookieDomain: '.studio.com',
  onError: (err) => console.error(err.code, err.message),
});

setConsent(level)

Controls what the SDK is allowed to collect. Call when the user accepts or changes their cookie preferences. Takes effect immediately, no page reload needed. See the Data Dictionary for consent levels and downgrade behavior.

// Upgrade after cookie banner
audience.setConsent('anonymous');

// Downgrade — stops tracking, clears cookies
audience.setConsent('none');

canTrack(level)

Checks whether a consent level allows tracking. Returns true when level is 'anonymous' or 'full'. Use before calling track() or page() when you need to guard behavior based on the current consent level, for example when conditionally showing a tracking-dependent UI element.

Parameter	Type	Description
`level`	`'none' \| 'anonymous' \| 'full'`	The consent level to check

import { canTrack } from '@imtbl/audience';

if (canTrack(currentConsentLevel)) {
  // safe to call track() and page()
}

canIdentify(level)

Checks whether a consent level allows player identification. Returns true when level is 'full'. Use before calling identify() or alias() when you need to guard identity-dependent logic, for example to only prompt a player to link accounts when consent allows it.

Parameter	Type	Description
`level`	`'none' \| 'anonymous' \| 'full'`	The consent level to check

import { canIdentify } from '@imtbl/audience';

if (canIdentify(currentConsentLevel)) {
  // safe to call identify() and alias()
}

page(properties?)

Records a page view. Call on every route change to track which pages players visit and in what order. The first call in each session includes attribution parameters.

Parameter	Type	Description
`properties`	`Record<string, unknown>`	Optional custom properties

Requires: 'anonymous' or 'full' consent. Calls at 'none' are silently dropped.

track(event, properties?)

Records a player action. Call when a player does something you want to measure, such as a purchase, sign-up, level completion, or any custom action. Predefined events give you typed properties with autocomplete.

Parameter	Type	Description
`event`	`string`	An `AudienceEvents` value (e.g. `AudienceEvents.PURCHASE`) or any custom string
`properties`	`Record<string, unknown>`	Event properties. Required for predefined events that have required fields (e.g. `purchase`), optional otherwise.

Requires: 'anonymous' or 'full' consent. Calls at 'none' are silently dropped.

// Predefined event — typed properties
audience.track(AudienceEvents.PURCHASE, { currency: 'USD', value: '9.99', item_name: 'Sword' });

// Custom event — any properties
audience.track('tutorial_complete', { stepCount: 5 });

identify(id, identityType, traits?)

Associates the player’s userId with their activity and traits. Call at login or account connection.

Parameter	Type	Description
`id`	`string`	The player’s identifier in that provider
`identityType`	`IdentityType`	Which provider the ID comes from (see table below)
`traits`	`object`	Optional. `email`, `name`, or custom key-value pairs

Requires: 'full' consent.

audience.identify('player-456', IdentityType.Passport, {
  email: 'user@example.com',
});

Identity types:

Value	Provider
`'passport'`	Immutable Passport
`'steam'`	Steam
`'epic'`	Epic Games
`'google'`	Google
`'apple'`	Apple
`'discord'`	Discord
`'email'`	Email address
`'custom'`	Custom identity system

alias(from, to)

Links two account IDs that belong to the same player. Call when a player connects a second account with a different provider, for example a player previously identified via Steam who later links a Passport account.

Parameter	Type	Description
`from`	`{ id: string, identityType: IdentityType }`	The account being linked
`to`	`{ id: string, identityType: IdentityType }`	The player’s main account

Requires: 'full' consent.

audience.alias(
  { id: 'steam-user-789', identityType: IdentityType.Steam },
  { id: 'player-456', identityType: IdentityType.Passport },
);

deleteData(userId?)

Requests erasure of all event data for a player. Call when a player submits a data deletion request (e.g. GDPR right-to-erasure). The backend resolves all linked identities via stored alias mappings and queues an erasure event for async processing.

Parameter	Type	Description
`userId`	`string`	Optional. The player’s user ID. When omitted, erases by the device’s anonymous ID instead.

When userId is omitted and no anonymous ID has been created yet (fresh install with no prior tracking), the call is a no-op — there is no record to erase.Failures are surfaced via config.onError with code 'DATA_DELETE_FAILED'. The returned promise always resolves.

// Erase by user ID (call after the player has been identified)
await audience.deleteData('player-123');

// Erase by anonymous ID (when no userId is known)
await audience.deleteData();

getAnonymousId()

Returns the anonymous ID for the current browser session. Useful for debugging, passing the ID to a third-party tool, or carrying it across a browser redirect. See Cross-Browser Tracking.

const aid = audience.getAnonymousId();

reset()

Wipes the current player’s identity and starts a fresh anonymous session. Call when a player logs out so the next player on the same device isn’t mixed up. Reset does not change the consent level, so studios using an explicit consent prompt should also call setConsent('none') at logout if the next player should start unconsented.

audience.reset();

flush()

Sends all queued events to the server immediately. Call when you need events delivered right now instead of waiting for the next automatic flush. Returns a Promise that resolves when the batch is sent.

await audience.flush();

shutdown()

Sends any remaining events and shuts down the SDK. Call when the app unmounts or the page is about to unload.

Cross-Browser Tracking

When a player moves between domains or browser contexts, the SDK mints a fresh anonymous ID in the new context and their prior session history is disconnected. To carry the anonymous ID across, append it to the URL:

const url = new URL(destination);
url.searchParams.set('imtbl_aid', audience.getAnonymousId());
window.open(url.toString(), '_blank');
// e.g. https://yoursite.com/?imtbl_aid=a1b2c3d4-...

The SDK reads imtbl_aid automatically on init, adopts it as the anonymous ID for that session, and removes the parameter from the URL. No extra code is needed on the landing page. If the player logs in after the redirect, call identify() as normal. The anonymous session is linked to their account.

This works for any redirect where you control the destination URL. It does not apply when the OS or browser handles navigation directly (for example, a Share sheet or a bookmark), since there is no opportunity to append parameters before the URL is opened.

Event Delivery

Events are batched and flushed every 5 seconds or when 20 events accumulate (configurable via flushInterval and flushSize)
On page unload (navigate away, close tab), the queue flushes remaining events so they are not lost

FAQ

What browsers are supported?

Chrome 80+, Firefox 78+, Safari 14+, Edge 80+.

Call deleteData() with the player’s user ID. This sends a deletion request to the backend, which resolves all linked identities and queues an erasure event for async processing.

await audience.deleteData('player-123');

If the player has no known user ID (they were only tracked anonymously), call deleteData() with no argument — the SDK uses the device’s persistent anonymous ID automatically.After the deletion request is sent, call reset() to clear the local identity and generate a fresh anonymous ID so the next session is not linked to the erased player:

await audience.deleteData('player-123');
audience.reset();

For server-side erasure (e.g. triggered from a backend request), see Deleting User Data in the REST API docs.

Next Steps

Attribution

How tracking data powers player attribution and Hub reports

Data Dictionary

Full reference of event schemas and consent levels

Unity SDK

In-game tracking for Unity desktop builds

REST API

Send events from your backend or game server

Conversion Postbacks

Send attributed conversions back to ad networks to improve campaign optimisation

API Keys

Manage your publishable and secret keys

PRODUCTS

GUIDES

What You Need

Installation

Quick Start

Complete Example

Auto-Capture

Verify the Integration

Content Security Policy

API Reference

Cross-Browser Tracking

Event Delivery

FAQ

Next Steps

Attribution

Data Dictionary

Unity SDK

REST API

Conversion Postbacks

API Keys

​What You Need

​Installation

​Quick Start

​Complete Example

​Auto-Capture

​Verify the Integration

​Content Security Policy

​API Reference

​Cross-Browser Tracking

​Event Delivery

​FAQ

​Next Steps

Attribution

Data Dictionary

Unity SDK

REST API

Conversion Postbacks

API Keys

What You Need

Installation

Quick Start

Complete Example

Auto-Capture

Verify the Integration

Content Security Policy

API Reference

Cross-Browser Tracking

Event Delivery

FAQ

Next Steps