Event Categories
Required and recommended tracking events for PSYKHE AI.
| Category | Event | Why it matters |
|---|---|---|
| Mandatory | Product Page View (PDP) | Primary indicator of SKU-level interest; feeds dwell-time and relevance models. |
| Product List View (PLP) | Establishes browsing context and impression exposure for ranking evaluation. | |
| Add to Cart | High-intent signal powering conversion forecasting and cart-aware recommendations. | |
| Transaction | Authoritative conversion event used for revenue attribution and ROI measurement. | |
| Site Search | Mandatory only if you call the Search API; captures explicit intent for preference profiling. | |
| Recommended | Product Dwell Time on PLP | Granular engagement metric-how long shoppers pause on list items. |
| Product Dwell Time on PDP | Measures deep SKU engagement, refining interest scoring. | |
| Hover over Product Card | Micro-engagement that often precedes clicks, enriching intent models with low-friction data. | |
| Remove from Cart | Negative feedback for abandonment, accidental additions, price sensitivity, and replenishment modelling. | |
| Checkout Steps | Enables funnel analytics to pinpoint drop-off points and trigger abandonment recovery campaigns. | |
| List Click | Corrects for positional bias in ranking algorithms and enhances CTR analytics. | |
| Refund | Closes the post-purchase loop, recalibrating lifetime-value and returns-propensity models. |
Refund events: Turnkey platforms such as Shopify emit these automatically. For manual integrations, emit Refund events explicitly to maintain accurate return analytics.
Remove from Cart events: Recommended, not mandatory. Many storefronts expire cart items rather than emitting a discrete remove action. Capture it where possible; otherwise, expiration supplies a weaker proxy.
Quality Filters
Apply client-side filters to boost signal quality:
| Event Type | Minimum | Maximum | Rationale |
|---|---|---|---|
| Dwell Time (PLP/PDP) | 300ms | 5 min | Drops scroll-by flickers and "tab-left-open" outliers. |
| Hover | 300ms | 60s | Ignores accidental passes and extreme idle hovers. |
Getting Started
Minimum setup for the PSYKHE AI Tracking API using Snowplow.
Create new ingestion POST
Creates a new ingestion job for processing product data. ### Which processing mode should I use? | Scenario | Use this mode | |---|---| | Webhook updates (single product or small batch) | `insert` | | Incremental sync (only changed products) | `insert` | | **Full catalog sync** (you are sending the *entire* active catalog) | `soft_replace` | | Hourly / daily catalog dump | `soft_replace` | Set the mode via the `X-PSYKHE-PROCESSING-MODE` header. - **`insert` (default)** - Upserts products present in the feed. Products *not* in the feed are left untouched. This is the safe default for webhooks and incremental batches because it never disables anything. - **`soft_replace`** - Upserts products present in the feed *and marks every other active product in your catalog as inactive* (excluded from recommendations; data is preserved, not hard-deleted). Only use this when the payload contains your **complete** catalog. Sending a partial catalog with `soft_replace` will disable every product you omitted. Request body is newline-delimited JSON (JSONL), one product per line. Gzip compression is supported via `Content-Encoding: gzip`. The ingestion is processed asynchronously - the response returns immediately with an `ingestion_id` you can poll via `GET /ingestion/{id}`.