Event Tracking

The event tracking system captures user interactions and page analytics, sent to the Experience service via protobuf for maximum throughput and minimal payload size.

What's Tracked Automatically

Manual Tracking

Builders can fire custom events:

exp.track('checkout_started', {
  cart_value: '99.99',
  item_count: '3',
  currency: 'GBP'
});

See the JS SDK and React SDK for full API details.

The data-t System

The data-t attribute (short for "tracking ID") is the bridge between the UI and the analytics system. Any HTML element with a data-t attribute is automatically tracked for clicks, hovers, and visibility.

<!-- Automatically tracked -->
<button data-t="checkout-btn">Complete Purchase</button>
<a data-t="nav-pricing" href="/pricing">Pricing</a>
<div data-t="hero-banner">...</div>

How It Works

1. The SDK's ExperienceProvider (React) or Experience.init() (vanilla) sets up a MutationObserver on the document
2. All elements with data-t are registered in an internal map
3. Event delegation on document captures clicks — if the target (or ancestor) has data-t, an event fires
4. An IntersectionObserver tracks visibility of data-t elements (for "was this seen?" analytics)
5. Hover tracking uses mouseenter/mouseleave with a 500ms threshold

Naming Conventions

{section}-{element}-{qualifier}

Examples:
  nav-link-pricing
  hero-cta-signup
  checkout-btn-submit
  sidebar-toggle-theme
  card-product-123

Design System Integration

All interactive @shellapps/react-ui components accept a trackingId prop that maps to data-t:

<Button trackingId="checkout-submit" variant="primary">
  Complete Purchase
</Button>
// Renders: <button data-t="checkout-submit" ...>Complete Purchase</button>

Event Batching & Delivery

Events are NOT sent individually. The SDK collects events in memory and sends them in batches:

Events generated ──► In-memory queue ──► Batch (protobuf encode) ──► POST /api/v1/events/ingest
                          │                        │
                          │                   Every 2 seconds
                          │                   OR queue reaches 50 events
                          │                   OR page unload (sendBeacon)
                          │
                     IndexedDB backup
                     (offline resilience)

• Batch interval: 2 seconds (configurable)
• Max batch size: 50 events (configurable)
• Page unload: Uses navigator.sendBeacon() for reliable delivery on close
• Offline: Events queue in IndexedDB, flush when connection restored
• Sampling: Configurable sampleRate (0.0–1.0) for high-traffic apps

Heatmap Data

Heatmap events are separate from regular tracking events because of their volume. Mouse position is captured every 100ms and batched separately.

The dashboard renders heatmaps by overlaying aggregated position data onto a wireframe/screenshot of the page. Positions are normalized to viewport width so different screen sizes aggregate correctly.

Heatmap data has a shorter retention period (30 days vs 90 days for regular events).

API Endpoints

See the full API Reference and Data Models for protobuf schemas and MongoDB collection structures.