Getting Started
Minimum setup for the PSYKHE AI Tracking API using Snowplow.
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-ecommercepnpm add @snowplow/browser-tracker @psykhe-ai/browser-plugin-snowplow-ecommerceyarn add @snowplow/browser-tracker @psykhe-ai/browser-plugin-snowplow-ecommercebun 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();
// Pass this into the Recommendation API as `user.device_id`.-
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.
Snowplow exposes this identifier as domain_userid / domainUserId.
The Recommendation API expects the same long-lived browser identifier in user.device_id.
// 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;