Getting Started

The Psykhe AI Tracking API lets you record rich behavioral data from any storefront using Snowplow under the hood. Start here to understand the minimum setup and core concepts before you dive into code examples in the plugin README.

Minimum Viable Setup (5 steps)

Install the SDK

npm install @snowplow/browser-tracker @psykhe-ai/browser-plugin-snowplow-ecommerce

pnpm add @snowplow/browser-tracker @psykhe-ai/browser-plugin-snowplow-ecommerce

yarn add @snowplow/browser-tracker @psykhe-ai/browser-plugin-snowplow-ecommerce

bun add @snowplow/browser-tracker @psykhe-ai/browser-plugin-snowplow-ecommerce

Initialize a tracker

import {newTracker} from "@snowplow/browser-tracker";
import {PsykheSnowplowEcommercePlugin} from "@psykhe-ai/browser-plugin-snowplow-ecommerce";

const PSYKHE_BASE_URL = "https://api.psykhe.dev";
const POST_PATH = "/v1/collector";

// Client identifier, e.g. "store-name.com"
const clientIdentifier = "store-name.com";

const tracker = newTracker("psykhe-ai", PSYKHE_BASE_URL, {
    appId: clientIdentifier,
    appVersion: "1.0.0",
    postPath: POST_PATH,
    cookieName: "_psykhe_",
    cookieDomain: document.location.hostname,
    stateStorageStrategy: "cookieAndLocalStorage",
    cookieSecure: true,
    cookieSameSite: "Lax",
    keepalive: true,
    credentials: "include",
    bufferSize: 1,
    contexts: {
        session: true, // mandatory session context
        webPage: true, // optional
        browser: true // optional
    },
    plugins: [PsykheSnowplowEcommercePlugin()]
});

const domainUserId = tracker.getDomainUserId();
// Same value travels under three names: `domain_userid` (Snowplow) = `psykhe_duid` (cookie)
// = `user.device_id` (Recommendation API). Reuse the same string everywhere.

Track the mandatory events on the relevant pages See the events table.
Explore helper functions in the plugin README, Usage section.

Next Steps

For full setup instructions and usage examples, see the GitHub repository: psykhe-ai/browser-plugin-snowplow-ecommerce

How to get domain user identifier

The domain user identifier is the primary way to recognize and persist the identity of a user across sessions. This identifier enables accurate personalization, attribution, and behavioral tracking.

You must include the domain user identifier in all recommendation requests. Without it, personalization will not function properly and every request will be treated as if it is from a brand new user - losing all user-specific context.

The best way to retrieve and use this identifier is to extract it immediately after initializing your Snowplow tracker, then store it globally in your application state (e.g., via a global context, or client-side storage). Snowplow internally manages and persists this identifier using cookies or local storage, so you do not need to manually persist it separately.

The same long-lived browser identifier travels under three names across our stack — they are all the same value:

Surface	Name
Snowplow event	`domain_userid` / `domainUserId`
Cookie (`_psykhe_`)	`psykhe_duid`
Recommendation API	`user.device_id`

Read it once via getDomainUserId() and reuse the same value for every Recommendation API call.

// Configure a tracker instance
const sp = newTracker('sp', '{{COLLECTOR_URL}}', {
    appId: 'snowplowExampleApp'
});

// Access the domain user ID
const domainUserId = sp.getDomainUserId();

// Store it globally (e.g., React context, Redux store, or global JS variable)
window._psykheDomainUserId = domainUserId;

How to get domain session identifier

The domain session identifier (psykhe_dsid) is the per-visit session UUID — the same value Snowplow sends as domain_sessionid on every event. Use it when you need to correlate a recommendation request or an out-of-band server call with the events fired during the same session.

Snowplow browser tracker 4.6.x does not expose getDomainSessionId(). The public BrowserTracker API only exposes getDomainUserId, getDomainUserInfo, and getDomainSessionIndex. Read the session UUID from getDomainUserInfo() instead — index [6] holds the same session UUID Snowplow derives for domain_sessionid.

// Configure a tracker instance
const sp = newTracker('sp', '{{COLLECTOR_URL}}', {
    appId: 'snowplowExampleApp'
});

// getDomainUserInfo returns a tuple; index 6 is the session UUID (domain_sessionid).
// On 4.6.x this is async; on earlier sync builds drop the `await`.
const info = await sp.getDomainUserInfo();
const domainSessionId = info[6];

// Store it globally for use in recommendation requests or other server calls.
window._psykheDsid = domainSessionId;

The tuple layout (Snowplow's internal id cookie format) is:

Index	Field	Notes
0	cookieDisabled	`"0"` when cookies are enabled
1	domainUserId	Same as `getDomainUserId()`
2	cookieCreateTs	Seconds since epoch
3	visitCount	Same as `getDomainSessionIndex()`
4	nowTs	Last activity timestamp
5	lastVisitTs	Previous visit timestamp
6	sessionId	`domain_sessionid` (`psykhe_dsid`)
7	previousSessionId	Previous session UUID
8	firstEventId	First event UUID of the session
9	firstEventTs	First event timestamp (ms)
10	eventIndex	Event counter within the session

Minimum Viable Setup (5 steps)

Next Steps

How to get domain user identifier

How to get domain session identifier

On this page