Interactions and impressions
Measure the recommendation funnel: impressions when items are shown, interactions when users act. scenarioSlug is optional — omit it for site-wide behavior; include it to attribute events to a recommendation placement.
API base URLs
| Engine API base URL | Admin UI |
|---|---|
| https://api.recomnext.com | https://admin.recomnext.com |
Use the engine base URL as baseUrl in widgets and SDKs.
Impressions vs interactions
| Setting | Type | Default | Description |
|---|---|---|---|
| Impression | visibility | — | Item appeared in a recommendation slot. POST /ingestion/impressions. |
| Interaction | action | — | User viewed, carted, purchased, or rated. POST /ingestion/interactions. |
| scenarioSlug | optional | — | Links event to a placement for per-scenario CTR and experiments. Omit for site-wide history and tenant analytics. |
Per-scenario CTR in analytics requires impressions with a matching scenarioSlug. Widgets and Browser SDK batch impressions via IntersectionObserver. Interactions without scenarioSlug still update user history and appear in tenant-wide analytics endpoints.
Interaction types
| Setting | Type | Default | Description |
|---|---|---|---|
| view | interaction | weight 1× | PDP view, list click from rec. |
| cart | interaction | weight 2× | Add to cart. |
| purchase | interaction | weight 4× | Order line / purchase. |
| rating | interaction | weight 3× | Explicit rating. |
Default weights apply in history-based algorithms (~30-day window). Send explicit weight to override.
Via API — interactions
POST https://api.recomnext.com/ingestion/interactions
Content-Type: application/json
X-Tenant-Id: aurora-games
{
"interactions": [
{
"userId": "customer-42",
"itemId": "game-elden-ring",
"type": "view",
"scenarioSlug": "homepage-for-you"
},
{
"userId": "customer-42",
"itemId": "bundle-starter",
"type": "purchase",
"weight": 8,
"scenarioSlug": "cart-upsell"
}
]
}Response
{ "accepted": 2 }Events are processed asynchronously. At least one of userId or sessionId is required.
Without scenario attribution
You do not need a scenario slug to log interactions. Send itemId, type, anduserId or sessionId only. The engine stores the event, feeds weighted-history and co-occurrence algorithms, and counts it in tenant-wide analytics (GET /analytics/top-items,interaction-volume). Per-scenario funnel endpoints ignore events with no slug.
PDP view from search or direct link (not a carousel)
POST https://api.recomnext.com/ingestion/interactions
{
"interactions": [
{
"userId": "customer-42",
"itemId": "game-elden-ring",
"type": "view"
}
]
}Order webhook — backfill purchases site-wide
POST https://api.recomnext.com/ingestion/interactions
{
"interactions": [
{
"userId": "customer-42",
"itemId": "bundle-starter",
"type": "purchase",
"weight": 4,
"timestamp": "2026-06-20T14:30:00Z"
}
]
}No scenarioSlug — the purchase still strengthens personalization without claiming a specific recommendation slot drove the sale.
Browser SDK — omit the second argument
recomnext.trackView('game-elden-ring');
recomnext.trackCart('game-hades');
recomnext.trackPurchase('bundle-starter');Node SDK — batch without scenarioSlug
await client.ingestion.logInteractions([
{ userId: 'customer-42', itemId: 'game-elden-ring', type: 'view' },
{ userId: 'customer-42', itemId: 'bundle-starter', type: 'purchase', weight: 8 },
]);Include scenarioSlug only when you know which recommendation placement surfaced the item — for example after a click from a carousel. See Analytics and experiments for when attribution matters.
Via API — impressions
POST https://api.recomnext.com/ingestion/impressions
{
"impressions": [
{
"userId": "customer-42",
"itemIds": ["game-elden-ring", "game-hades", "bundle-starter"],
"scenarioSlug": "homepage-for-you"
}
]
}Via Browser SDK
With placement attribution
recomnext.trackView('game-elden-ring', 'homepage-for-you');
recomnext.trackCart('game-hades', 'pdp-related');
recomnext.trackPurchase('bundle-starter', 'cart-upsell');Site-wide (no scenario)
recomnext.trackView('game-elden-ring');
recomnext.trackCart('game-hades');
recomnext.trackPurchase('bundle-starter');Impressions (scenario recommended for CTR)
const cleanup = recomnext.trackImpressions(document.querySelector('.recs'), {
scenario: 'homepage-for-you',
itemSelector: '[data-item-id]',
threshold: 0.5,
once: true,
});Via widgets
Carousels auto-log impressions when cards enter the viewport. Clicks fire view events withdata-scenario. Set data-user-id for known users.
Custom weights
Subscription purchase — higher intent
{ "type": "purchase", "itemId": "sub-annual", "weight": 10, "scenarioSlug": "cart-upsell" }Wishlist add as soft signal
If you map wishlist to view with weight: 1.5, history algorithms weight it between view and cart.
Attribution flow
1. Fetch with scenario: 'homepage-for-you' → 2. Log impressions with same slug → 3. On click/cart, pass slug of the placement that surfaced the item → 4. Read analytics summary for that scenario.