Usergeist

A TypeScript library for tracking user interactions in applications.

Installation

npm install usergeist

Usage

// main.ts
import Usergeist from 'usergeist'

export const tracker = new Usergeist({
  sessionId: '123',
  sendInterval: 1000,
})

Upon initialization, the tracker automatically monitors the following user interactions:

• Click Events: Captures click interactions on elements marked with the data-track="true" attribute
• Navigation Events: Records browser navigation actions including history changes and popstate events

API

Constructor Options

• sessionId: string - Required. Unique identifier for the tracking session
• endpoint?: string | null - Optional. API endpoint for sending tracking data. If null, logs to console
• batchSize?: number - Optional. Number of events to batch before sending. Defaults to 10
• sendInterval?: number - Optional. Interval in ms between sending batches. Defaults to 5000
• textLimitSize?: number - Optional. Maximum length of tracked text content. Defaults to 255
• navigation?: object - Optional. Navigation tracking configuration
  • useNavigationTransactions?: boolean - Enable transaction-based navigation tracking. Defaults to false
  • trackNavigationTransactionTime?: boolean - Track how long (milliseconds) navigation transactions are pending. Defaults to false
  • transactionRoutePatterns?: RegExp[] - Array of regex patterns to match routes that should use transactions. Patterns are matched against the path part of the URL only (including query parameters and hash). If empty, transactions are used for all routes when enabled

Methods

• trackCustomEvent(eventName: string, eventData?: Record<string, unknown>): void - Track a custom event with optional data
• trackToastEvent({ message, position, severity, duration? }): void - Track a toast notification event
  • message: string - The toast message content
  • position: string - Position where toast was shown
  • severity: 'success' | 'info' | 'warning' | 'error' - Toast severity level
  • duration?: number - Optional display duration in milliseconds
• commitNavigation(): void - Commit the current pending navigation event (only when useNavigationTransactions is enabled)

Navigation Transactions

When useNavigationTransactions is enabled, navigation events are handled in a transaction-like manner:

1. Navigation events are stored as pending until either:
   • A new navigation occurs (automatically commits the previous one)
   • The developer explicitly calls commitNavigation()
2. The page title is captured at commit time, not at navigation start time
3. This is useful for Single Page Applications (SPAs) where the page title might change after the initial navigation

Route-Specific Navigation Transactions

You can configure navigation transactions to only apply to specific routes using the transactionRoutePatterns option:

const tracker = new Usergeist({
  sessionId: '123',
  navigation: {
    useNavigationTransactions: true,
    transactionRoutePatterns: [
      /^\/dashboard/, // Only use transactions for dashboard routes
      /^\/profile/, // And profile routes
      /^\/settings/ // And settings routes
    ]
  }
})

In this example, navigation transactions will only be used for URLs with paths matching the specified patterns. For all other routes, navigation events will be sent immediately without using the transaction mechanism.

Note: The patterns are matched against the path part of the URL only (including query parameters and hash), ignoring the protocol, domain, and port. This makes your patterns more portable across different environments.

If transactionRoutePatterns is not provided or is an empty array, navigation transactions will be used for all routes when useNavigationTransactions is enabled.

Example with navigation transactions:

const tracker = new Usergeist({
  sessionId: '123',
  useNavigationTransactions: true,
})

// Later in your code, after the page has fully loaded and title is updated
tracker.commitNavigation()

Output Data Format Examples

Session Start

{
  "type": "start_session",
  "timestamp": 1742640283316,
  "sessionId": "123",
  "url": "http://localhost:5173/contact?email=&message="
}

Navigation Event

{
  "type": "navigation",
  "timestamp": 1742640341874,
  "sessionId": "123",
  "url": "http://localhost:5173/about",
  "action": "pushState",
  "title": "Vite + React + TS"
}

Click Event

{
  "type": "click",
  "timestamp": 1742640341874,
  "sessionId": "123",
  "url": "http://localhost:5173/about",
  "element": {
    "tag": "button",
    "id": "submit-btn",
    "text": "Submit"
  }
}

Toast Notification

{
  "type": "toast",
  "timestamp": 1742640982390,
  "sessionId": "123",
  "url": "http://localhost:5173/contact",
  "message": "Message sent successfully!",
  "position": "top-right",
  "severity": "success",
  "duration": 3000
}

Note: Toast severity can be one of: success, error, warning, info

Development

# Install dependencies
npm install

# Build the library
npm run build

# Run tests
npm test

# Run linter
npm run lint

# Format code
npm run format

License

MIT licensed.