Tracking and Attribution Module¶

Overview¶

The tracking module records impressions and clicks on banners, sliders, and hero blocks, then attributes downstream conversions (cart adds and purchases) to those interactions.

Models¶

TrackingEvent (`tracking_events` table)¶

Append-only table — no updated_at. Records every impression and click.

Field	Type	Description
`id`	BigInteger PK
`event_type`	String(20)	`impression` or `click`
`entity_type`	String(20)	`banner`, `slide`, or `hero`
`entity_id`	BigInteger	ID of the tracked entity
`user_id`	BigInteger, nullable	Authenticated user
`customer_group_id`	BigInteger, nullable
`is_authenticated`	Boolean
`session_id`	String(255)	From `X-Session-ID` header
`ip_address`	String(45)	IPv4/IPv6
`user_agent`	String(500)
`page_url`	String(500)	Page where event occurred
`referrer_url`	String(500)
`is_repeat`	Boolean	True if user/session clicked before
`channel_id`	BigInteger, nullable

Indexes: (entity_type, entity_id, created_at), (user_id, created_at), (session_id, entity_type, entity_id).

TrackingAttribution (`tracking_attributions` table)¶

Links click events to conversions.

Field	Type	Description
`tracking_event_id`	FK → tracking_events	The click that led to conversion
`attribution_type`	String(20)	`cart_add` or `purchase`
`product_id`, `category_id`, `brand_id`	BigInteger, nullable	What converted
`order_id`	BigInteger, nullable	For purchases
`attributed_revenue`	Decimal, nullable	Order line total

Attribution Flow¶

Storefront fires impression/click events via POST /api/track (BFF) → POST /track (backend)
On click, TrackingService.record_event() checks for repeat clicks
EventBus listener on cart.item_added → TrackingService.attribute_cart_add() finds recent clicks within the 24h attribution window
EventBus listener on order.completed → TrackingService.attribute_purchase() links clicks to purchase revenue

REST Endpoint¶

POST /track — lightweight fire-and-forget endpoint. Lower overhead than GraphQL for high-frequency beacons.

Storefront Integration¶

tracking.ts — shared client using IntersectionObserver (50% visibility, 1s delay, deduped per page load) for impressions and click handlers for clicks
POST /api/track — SvelteKit BFF route that proxies to backend
All tracked elements use data-vectis-entity-type and data-vectis-entity-id attributes