Analytics and experiments
Measure recommendation performance per scenario and compare A/B variants. Tenant-wide metrics work without scenarioSlug; per-placement CTR and experiments need consistent attribution.
Tenant-wide vs per-scenario analytics
| Setting | Type | Default | Description |
|---|---|---|---|
| GET /analytics/interaction-volume | tenant-wide | — | All interactions — scenarioSlug not required. |
| GET /analytics/interactions-by-type | tenant-wide | — | Breakdown by view / cart / purchase / rating. |
| GET /analytics/top-items | tenant-wide | — | Top items by interaction count across the site. |
| GET /analytics/scenario/:slug/* | per-scenario | — | CTR, funnel, top items — requires scenarioSlug on impressions and attributed interactions. |
Logging interactions without scenarioSlug is valid for personalization and tenant dashboards. Those events do not appear in per-scenario funnel or experiment results.
Prerequisites for accurate funnels
| Setting | Type | Default | Description |
|---|---|---|---|
| Impressions | required | — | Log when rec items are visible, with scenarioSlug. |
| Interactions | required | — | view / cart / purchase with matching scenarioSlug when attributing to a placement. |
| Stable scenario slugs | required | — | Same slug on fetch, impressions, and downstream events. |
Scenario analytics endpoints
| Setting | Type | Default | Description |
|---|---|---|---|
| GET /analytics/scenario/:slug/summary | endpoint | — | Impressions, clicks, carts, purchases, CTR, conversion. |
| GET /analytics/scenario/:slug/funnel-volume | endpoint | — | Daily time series per funnel stage. |
| GET /analytics/scenario/:slug/top-items | endpoint | — | Per-item metrics for the scenario. |
| GET /analytics/top-recommended | endpoint | — | Cross-scenario top items. |
| GET /analytics/summary | endpoint | — | Tenant-wide aggregates. |
Integration health checklist
Before trusting CTR numbers:
- Impressions fire when carousel cards become visible (50% threshold default in SDK).
scenarioSlugon impressions matches the scenario used inrecommend().- Cart and purchase events include the placement that drove the action when known.
- Identity merge runs after login so user history is complete.
Experiments (A/B tests)
Experiments attach to a base scenario and assign users to variant scenarios (different slugs, filters, or algorithms).
| Setting | Type | Default | Description |
|---|---|---|---|
| variants | array | — | Each variant references a scenario slug and traffic weight. |
| assignment | userId | — | Sticky per user at recommendation fetch time. |
| GET /experiments/:slug/results | endpoint | — | Per-variant CTR and conversion comparison. |
Use case
Homepage — control vs boosted featured
Control variant: scenario homepage-for-you. Treatment: homepage-for-you-boosted with extra boosters on featured titles. Compare results after 2 weeks of traffic.