RecomNext

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 URLAdmin UI
https://api.recomnext.comhttps://admin.recomnext.com

Use the engine base URL as baseUrl in widgets and SDKs.

Impressions vs interactions
SettingTypeDefaultDescription
Impressionvisibility-Item appeared in a recommendation slot. POST /ingestion/impressions.
Interactionaction-User viewed, wishlisted, carted, purchased, or rated. POST /ingestion/interactions.
scenarioSlugoptional-Links event to a placement for per-scenario CTR and experiments. Omit for site-wide history and tenant analytics.
countryoptional-ISO-2 market tag for 7-day geo fill and lift. Omit, invalid, or OTH stores as global. Impressions store country but v1 rank does not use it.

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
SettingTypeDefaultDescription
viewinteractionranker 1×PDP view, list click from rec. Event `weight` defaults to 1.0.
wishlistinteractionranker 1.5×Add to wishlist (`trackWishlist`); add only, not remove. Event `weight` defaults to 1.0.
cartinteractionranker 2×Add to cart. Event `weight` defaults to 1.0.
purchaseinteractionranker 4×Order line / purchase. Event `weight` defaults to 1.0.
ratinginteractionranker 3×Explicit rating. Event `weight` defaults to 1.0.

The ranker column is the type multiplier in weighted-history / popularity / training (~30-day window). Each row's optional event weight field defaults to 1.0: use it only for exceptional overrides, not for wishlist intent.

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",
      "country": "IN"
    },
    {
      "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.

Use case
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"
    }
  ]
}
Use case
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.trackWishlist('game-hades');
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",
      "country": "IN"
    }
  ]
}
Via Browser SDK
With placement attribution
recomnext.trackView('game-elden-ring', 'homepage-for-you');
recomnext.trackWishlist('game-hades', 'homepage-for-you');
recomnext.trackCart('game-hades', 'pdp-related');
recomnext.trackPurchase('bundle-starter', { scenarioSlug: 'cart-upsell', country: 'IN' });
Site-wide (no scenario)
recomnext.trackView('game-elden-ring');
recomnext.trackWishlist('game-hades');
recomnext.trackCart('game-hades');
recomnext.trackPurchase('bundle-starter');
Impressions (scenario recommended for CTR)
const cleanup = recomnext.trackImpressions(document.querySelector('.recs'), {
  scenario: 'homepage-for-you',
  country: 'IN',
  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
Use case
Subscription purchase: higher intent
{ "type": "purchase", "itemId": "sub-annual", "weight": 10, "scenarioSlug": "cart-upsell" }
Use case
Wishlist add

Use type: "wishlist" or trackWishlist. Ranking applies a 1.5× type multiplier (between view and cart). Do not send pseudo-views with custom weight.

{ "type": "wishlist", "itemId": "game-hades", "userId": "customer-42" }
Attribution flow

1. Fetch with scenario: 'homepage-for-you' → 2. Log impressions with same slug → 3. On click/wishlist/cart, pass slug of the placement that surfaced the item → 4. Read analytics summary for that scenario.

Analytics and experiments guide
Interactions and impressions | RecomNext