Visitor Tracking

The tracking system records detailed visitor behavior for analytics, heatmaps, and session replay.

Frontend Integration

Include the tracker script on any page. The script is minified when served (same build step as /form.js; run npm run build:form locally if you change the source).

<script src="https://your-worker.your-domain.workers.dev/tracker.js"></script>
<script>
  PulseGateSession.init({ endpoint: 'https://your-worker.your-domain.workers.dev' });
</script>

What Gets Tracked

Event Type	Trigger	Data Captured
page_view	Page load, SPA navigation	Page URL
click	Mouse click	x, y coordinates, element selector
scroll	Window scroll (250ms throttle)	Scroll depth percentage (0-100)
mousemove	Mouse movement (100ms throttle)	x, y coordinates
navigation	pushState or popstate	Page URL
visibility_change	Tab switch	Visibility state

Session Lifecycle

1. Start — PulseGateSession.init() generates a fingerprint, calls /track/session/start, receives session_id
2. Track — Events are queued client-side and flushed every 5 seconds via /track/events/batch
3. End — On beforeunload, remaining events are flushed and /track/session/end is called via sendBeacon

Client-Side Queue

Events are buffered in an in-memory queue (max 500 events) and flushed:

• Every 5 seconds (interval timer)
• On tab hidden (visibility change)
• On page unload (beforeunload)

Flushing uses navigator.sendBeacon when available, with XHR fallback.

SPA Support

The tracker monkey-patches history.pushState and listens for popstate events to detect client-side navigation in single-page applications.

Public API

PulseGateSession.init({ endpoint: '...' })   // Start session
PulseGateSession.trackEvent('custom', data)  // Queue a custom event
PulseGateSession.flush()                     // Force-flush event queue

Storage

• D1 — Sessions and events for persistent querying
• KV — Real-time counters (session count, unique IPs/ASNs per fingerprint)
• R2 — Raw event archives for session replay (append-only key pattern)