Flow Trace

A client-side analytics hook that tracks user navigation paths, time spent on pages, and interaction events with support for session management and traffic source attribution.

Usage

import { FlowTrace } from '@/hooks/flow-trace'

export default function Layout() {
  return (
    <>
      <Suspense>
        <FlowTrace />
      </Suspense>
      {/* Your content */}
    </>
  )
}

Features

• Path Tracking: Records complete navigation history with timestamps
• Time Measurement: Tracks time spent on each page using Luxon with timezone support (America/Chicago)
• Session Management: Distinguishes first-time vs returning visitors
• Traffic Source Attribution: Captures UTM parameters and referrer information
• Interaction Tracking: Monitors clicks on elements with .ft-tracking class
• Non-blocking Telemetry: Uses sendBeacon or fetch with keepalive for reliable data transmission
• Storage Management: Uses localStorage for persistent data and sessionStorage for session-specific data

Storage Keys

localStorage

• ft_path: Navigation path history (JSON array)
• ft_first: First seen timestamp
• ft_time_spent_ms: Total time spent across all sessions
• ft_session_source: Source attribution for current session

sessionStorage

• ft_session_start: Current session start timestamp
• ft_last_interaction: Last interaction timestamp

How it Works

• Page Views: Automatically recorded on route changes (Next.js pathname/searchParams)
• Time Attribution: Calculates time delta between interactions using Luxon DateTime
• Source Detection: Identifies traffic source from UTM parameters or referrer
• Session Attribution: Marks first external arrival in each session
• Click Tracking: Listens for clicks on .ft-tracking elements with 5-second debounce
• Data Transmission: Sends analytics payload to /api/flow-trace endpoint

Payload Structure

{
  firstSeen: string,              // ISO timestamp of first visit
  sessionStart: string,           // ISO timestamp of session start
  timeSpentTotalMs: number,       // Total time spent (all sessions)
  page: {
    url: string,                  // Current page URL
    title: string                 // Page title
  },
  path: [
    {
      path: string,               // Full path with query & hash
      ts: string,                 // ISO timestamp
      spentMs: number,            // Time spent on this page
      source?: string             // Traffic source (if new arrival)
    }
  ]
}

Interaction Tracking

Add the ft-tracking class to elements you want to track:

<a
  href="/contact"
  className="ft-tracking"
>
  Contact Us
</a>

<button
  className="ft-tracking"
  id="newsletter-signup"
>
  Subscribe
</button>

Click payloads include:

• element.href: Link destination (if anchor)
• element.innerText: Element text content
• element.id: Element ID
• context: Complete analytics payload

Configuration

• Default Endpoint: /api/flow-trace
• Max Path Length: 100 entries (FIFO)
• Click Debounce: 5000ms per element
• Timezone: America/Chicago (configurable via zone constant)

Source Attribution

Traffic sources are determined in priority order:

• UTM source parameter (utm_source)
• Document referrer
• "direct" (default)

External sources are validated to exclude:

• "direct"
• localhost
• Current production URL (from NEXT_PUBLIC_PRODUCTION_URL)

Implementation

The component is used in src/app/layout.tsx to enable flow tracking throughout the application.

Dependencies

• next/navigation for route change detection
• luxon for timezone-aware datetime handling