For the complete documentation index, see llms.txt. For the full corpus, see llms-full.txt. For raw markdown, append .md to this URL or send Accept: text/markdown.

Setup & Installation

Get the Split Testing SDK running in your app

Last updated: May 19, 2026

Installation

npm / ES Module

npm install @sessionsight/split-testing

Then initialize in your app:

Initialize

import SplitTesting from '@sessionsight/split-testing';

await SplitTesting.init({
  publicApiKey: 'YOUR_PUBLIC_API_KEY',
  propertyId: 'YOUR_PROPERTY_ID',
});

Script Tag

If you’re not using a bundler, add the script tag directly:

Script tag

<script src="https://cdn.sessionsight.com/split-testing.js"></script>
<script>
  SessionSightSplitTesting.init({
    publicApiKey: 'YOUR_PUBLIC_API_KEY',
    propertyId: 'YOUR_PROPERTY_ID',
  }).then(function () {
    var headline = SessionSightSplitTesting.get('hero-headline', 'Welcome');
    document.getElementById('hero').textContent = headline;
  });
</script>

When using the script tag, the SDK is available as SessionSightSplitTesting on the global window object.

Configuration

Option	Type	Default	Description
`publicApiKey`	`string`	required	Your public API key from the API Keys page
`propertyId`	`string`	required	Your property ID from the Properties page
`apiUrl`	`string`	`https://api.sessionsight.com`	Override for self-hosted or local dev
`visitorId`	`string`	auto-generated	Stable visitor ID. If omitted, the SDK reads or creates an `ss_vid` cookie, staying in sync with the Insights SDK
`attributes`	`object`	`{}`	Visitor attributes for targeting (e.g., `{ plan: 'pro' }`)
`bootstrap`	`object`	`null`	Pre-resolved assignments from the server for SSR usage
`antiFlicker`	`boolean`	`false`	Hide `[data-ss-split]` elements until assignments resolve. See Anti-Flicker
`staleTTL`	`number`	`0`	Milliseconds before cached config triggers a background refresh
`maxAge`	`number`	`86400000` (24h)	Milliseconds before cached config is considered expired
`onAssignment`	`function`	`null`	Callback fired when a variation is assigned: `(testKey, { key, value }) => void`

Pairing with the Insights SDK

When Insights is running on the same page, the two SDKs stay in sync automatically:

Visitor id (ss_vid cookie): reused via getOrCreateVisitorId() at construction so both SDKs hash to the same visitor bucket. Variant allocation is purely client-side; the visitor id is never attached to exposure records.
Session id (ss_sid cookie): read fresh from document.cookie on every exposure flush and attached to the exposure audit record. If the backend rotates the session (e.g., after a sealed-session archive), subsequent exposures carry the new id without any manual refresh().

SSR / Node bindings

For server-side rendering or server-driven bootstraps, call forRequest(req) to bind the session id from the inbound request’s cookies:

typescript

const bound = SplitTesting.forRequest(req);
await bound.init();
const variation = bound.get('hero-test', 'control');
bound.flush();

Works with every major framework (Next.js, SvelteKit, Nuxt, Hono, Express, Fastify, Koa, Workers, Remix, and more). See Pairing with backend SDKs for framework-specific examples.

Cleanup

typescript

SplitTesting.destroy();

Calling destroy() flushes any pending exposure events and cleans up the SDK instance.