Skip to main content

Getting Started

The Psykhe AI Tracking API lets you record rich behavioural 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)​

  1. Install the SDK
  pnpm add @snowplow/browser-tracker @psykhe-ai/browser-plugin-snowplow-ecommerce
  1. 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";

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()]
});

  1. Capture the domainUserId immediately
const domainUserId = sp.getDomainUserId();   // ➜ pass into every Recommendation API call

  1. Track the mandatory events on the relevant pages
    See the events table.

  2. 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.

❗️Important: 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's 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 don't need to manually persist it separately.

📘 Note: In our Recommendation API, the field name is currently session_id, while in the Tracking API and Snowplow it's referred to as domain_user_identifier. These are the same value. This naming difference exists during a transition period and will be aligned in the future.

// 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;