A TypeScript library for tracking user interactions in applications.
npm install usergeist
// 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
-
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
-
-
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 whenuseNavigationTransactions
is enabled)
When useNavigationTransactions
is enabled, navigation events are handled in a transaction-like manner:
- Navigation events are stored as pending until either:
- A new navigation occurs (automatically commits the previous one)
- The developer explicitly calls
commitNavigation()
- The page title is captured at commit time, not at navigation start time
- This is useful for Single Page Applications (SPAs) where the page title might change after the initial navigation
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()
{
"type": "start_session",
"timestamp": 1742640283316,
"sessionId": "123",
"url": "http://localhost:5173/contact?email=&message="
}
{
"type": "navigation",
"timestamp": 1742640341874,
"sessionId": "123",
"url": "http://localhost:5173/about",
"action": "pushState",
"title": "Vite + React + TS"
}
{
"type": "click",
"timestamp": 1742640341874,
"sessionId": "123",
"url": "http://localhost:5173/about",
"element": {
"tag": "button",
"id": "submit-btn",
"text": "Submit"
}
}
{
"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
# Install dependencies
npm install
# Build the library
npm run build
# Run tests
npm test
# Run linter
npm run lint
# Format code
npm run format