Session Replay

Visual playback of visitor sessions showing cursor movement, clicks, scroll behavior, and page navigation — all from the R2 event logs captured by tracker.js.

How It Works

The tracker script (/tracker.js) captures behavioral events in real-time:

Event Type	Data Captured
mousemove	x, y coordinates (throttled 100ms)
click	x, y, element (tag + id + class)
scroll	scroll_percent (0-100, throttled 250ms)
page_view	page URL
navigation	SPA route changes
visibility_change	tab focus/blur

Events are batched every 5 seconds and stored as append-only R2 objects under sessions/YYYY/MM/DD/{session_id}/events/.

The replay viewer reads these events back and plays them chronologically on a visual canvas.

API Endpoints

All data endpoints require API key authentication (same key as /analytics/*).

GET /replay

Serves the self-contained HTML replay viewer. No auth required — the viewer itself is public; data fetching from within the viewer uses the API key entered by the user.

GET /replay/sessions

Lists sessions with event counts, ordered by recency.

Query Parameters:

Param	Type	Default	Description
limit	number	50	Max results (capped at 100)
offset	number	0	Pagination offset
visitor_id	string	—	Filter by visitor ID

Response:

{
  "sessions": [
    {
      "session_id": "abc-123",
      "visitor_id": "def-456",
      "entry_page": "https://example.com/",
      "country": "IN",
      "started_at": 1708617600000,
      "duration": 300000,
      "engagement_score": 65,
      "event_count": 142
    }
  ],
  "total": 1
}

GET /replay/sessions/:id

Returns full session metadata and all events for playback.

Events are loaded from R2 first (append-only event files). Falls back to D1 events table if R2 has no data.

Response:

{
  "session": { "...full SessionRecord..." },
  "events": [
    {
      "event_id": "evt-1",
      "event_type": "click",
      "x": 450,
      "y": 320,
      "element": "BUTTON#cta.hero-btn",
      "page": "https://example.com/",
      "timestamp": 1708617612000
    }
  ],
  "event_count": 142
}

Viewer Features

The HTML viewer at /replay includes:

• Session sidebar — searchable list with engagement scores, country, event count, duration
• Visual canvas — shows cursor movement trail, click pulse animations, scroll position indicator, current page URL
• Timeline — scrubber bar with event type ticks (red = clicks, green = scroll, yellow = page views), elapsed/total time
• Playback controls — play/pause, 1×/2×/4×/8× speed
• Keyboard shortcuts — Space (play/pause), arrow keys (skip ±5s), 1-4 (speed)
• Visitor filter — search by visitor_id to focus on a specific user's sessions