journey-mapper-tracker
v1.0.0
Published
Track user page flows and capture screenshots for UX research - Journey Mapper SDK
Maintainers
bhuvan_adeReadme
Journey Mapper Tracker SDK
Track user page flows and capture screenshots automatically for UX research and analysis.
Installation
npm install journey-mapper-trackerQuick Start
import { JourneyTracker } from 'journey-mapper-tracker';
// Initialize the tracker
JourneyTracker.init({
apiKey: 'jm_your_api_key_here',
endpoint: 'https://your-journey-mapper-instance.com', // optional
captureDelay: 1000, // optional, ms to wait after navigation
excludedRoutes: ['/admin/*', '/login'], // optional
debug: false, // optional
});
// Manually capture a page (optional)
await JourneyTracker.capture();
// Stop tracking when done
JourneyTracker.stop();React/Next.js Integration
Option 1: Use the Provider Component
// components/JourneyTrackerProvider.tsx
"use client";
import { useEffect } from "react";
import { JourneyTracker } from "journey-mapper-tracker";
export function JourneyTrackerProvider({
apiKey,
children
}: {
apiKey: string;
children: React.ReactNode;
}) {
useEffect(() => {
JourneyTracker.init({
apiKey,
endpoint: window.location.origin,
debug: process.env.NODE_ENV === 'development',
});
return () => {
JourneyTracker.stop();
};
}, [apiKey]);
return <>{children}</>;
}Option 2: Initialize in Layout
// app/layout.tsx (Next.js 13+)
"use client";
import { useEffect } from 'react';
import { JourneyTracker } from 'journey-mapper-tracker';
export default function RootLayout({ children }) {
useEffect(() => {
JourneyTracker.init({
apiKey: process.env.NEXT_PUBLIC_JOURNEY_MAPPER_KEY!,
debug: true,
});
}, []);
return (
<html>
<body>{children}</body>
</html>
);
}Configuration Options
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| apiKey | string | required | Your project API key from Journey Mapper |
| endpoint | string | window.location.origin | Your Journey Mapper server URL |
| captureDelay | number | 1000 | Milliseconds to wait after navigation before capturing |
| excludedRoutes | string[] | [] | Routes to skip (supports wildcards like /admin/*) |
| debug | boolean | false | Enable console logging for debugging |
API Reference
JourneyTracker.init(config)
Initialize and start tracking. Must be called before any other methods.
JourneyTracker.stop()
Stop tracking and complete the current session. Call this when unmounting or when you want to end the session.
JourneyTracker.capture()
Manually capture the current page. Useful for capturing state after user interactions that don't trigger navigation.
JourneyTracker.isInitialized()
Returns true if the tracker is initialized and running.
How It Works
- Automatic Detection: The SDK detects page navigations (including SPA navigation via
pushState/replaceState) - Screenshot Capture: Uses
html2canvasto capture full-page screenshots - Data Upload: Sends captured data to your Journey Mapper instance
- Session Management: Groups all captured pages into a session for easy analysis
Requirements
- Browser environment (not compatible with SSR/Node.js)
- React 17+ (optional - works with any framework)
License
MIT