Tracking
How PSYKHE AI tracks shopper behaviour on Shopify through a Web Pixel, the consent model, and the events emitted.
PSYKHE AI tracking on Shopify is delivered as a Shopify Web Pixel.
How It Works
The pixel collects shopper behaviour on the storefront and forwards it to PSYKHE AI. No script tag, no theme edit. Shopify controls when the pixel can run based on the merchant's privacy configuration and the shopper's consent state (see Consent Model).
Shopper Identifiers
The Web Pixel exposes the Shopify identifiers used by PSYKHE AI in storefront
localStorage:
| localStorage key | PSYKHE AI field | Description |
|---|---|---|
psykhe_device_id | user.device_id | Shopify's long-lived client-side shopper identifier. This is the same value used as domain_userid in tracking events. |
psykhe_user_id | user.user_id | Shopify's customer ID when the shopper is logged in. It is separate from the device identifier and may be empty for anonymous shoppers. |
For custom storefront code that calls the Recommendation API, read these values on every page load. Do not generate and persist a separate device identifier, because that would split the shopper's recommendation and tracking histories.
const TEMPORARY_DEVICE_ID = "00000000-0000-0000-5000-000000000000";
const deviceId =
window.localStorage.getItem("psykhe_device_id") || TEMPORARY_DEVICE_ID;
const userId =
window.localStorage.getItem("psykhe_user_id") || undefined;
const user = {
device_id: deviceId,
...(userId ? { user_id: userId } : {}),
};The ...5000... placeholder value is temporary. It must not be replaced with a
newly generated identifier or persisted under another integration-specific
key.
Consent Model
The pixel runs inside Shopify's Web Pixel sandbox, which means:
- it honours Shopify's Customer Privacy API and the merchant's consent banner
- it only emits events when Shopify allows the consent categories required by the pixel configuration
- merchants control the consent banner and consent categories through Shopify's standard configuration
Before Shopify receives the shopper's consent, the PSYKHE AI localStorage
values can be missing, empty, or use the temporary device ID
00000000-0000-0000-5000-000000000000. Once consent is granted, Shopify runs
the pixel and replays eligible events that occurred earlier on the page. The
extension then stores the actual Shopify client identifier in
psykhe_device_id so subsequent page loads and recommendation requests use the
same identifier as PSYKHE AI tracking.
References:
Events We Track
The pixel captures Shopify-native shopper interactions used for ranking and attribution: product views, add-to-cart, remove-from-cart, checkout, and conversion. It also accepts PSYKHE AI custom events for search, list views, list clicks, product dwell, and promotional placements.
For the full event catalogue (names, payloads, mandatory vs. recommended, quality filters), see the canonical reference: Tracking API Events.
For custom Shopify theme UI that needs to publish list, click, search, or dwell events into the PSYKHE AI Web Pixel, see Custom UI Tracking.
What The Pixel Does Not Track
- shoppers whose consent state does not allow the pixel to run
- non-online-store sales channels