JSPM – observify-tracker@1.1.1

Package Exports

observify-tracker
observify-tracker/dist/tracker.bundle.js
observify-tracker/dist/tracker.esm.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (observify-tracker) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Automatic Error Tracking - Captures uncaught errors and promise rejections
Breadcrumbs - Track user journey with automatic and manual breadcrumbs
Performance Monitoring - Tracks page load times and web vitals
Network Monitoring - Monitors fetch requests (status, duration, failures)
Session Tracking - Groups events by user session
Zero Dependencies - Pure vanilla JavaScript
Tiny Bundle - < 5KB gzipped
TypeScript Support - Full type definitions included
Framework Agnostic - Works with React, Vue, Angular, or vanilla JS

Installation

npm

npm install @observify/tracker

yarn

yarn add @observify/tracker

CDN

<script src="https://cdn.jsdelivr.net/npm/@observify/tracker/dist/tracker.bundle.js"></script>

Quick Start

ES Modules (Recommended)

import { Tracker } from '@observify/tracker';

const tracker = new Tracker(
  'your-api-key',
  'https://your-backend.com/ingest',
  1.0  // 100% sampling rate
);

tracker.start();

CommonJS

const { Tracker } = require('@observify/tracker');

const tracker = new Tracker(
  'your-api-key',
  'https://your-backend.com/ingest'
);

tracker.start();

CDN / Browser

<script src="https://cdn.jsdelivr.net/npm/@observify/tracker/dist/tracker.bundle.js"></script>
<script>
  const tracker = new Observify.Tracker(
    'your-api-key',
    'https://your-backend.com/ingest'
  );
  tracker.start();
</script>

Usage

Basic Setup

import { Tracker } from '@observify/tracker';

// Initialize tracker
const tracker = new Tracker(
  'your-api-key',           // Your API key
  'https://api.example.com/ingest',  // Backend endpoint
  1.0                        // Sample rate (1.0 = 100%, 0.5 = 50%)
);

// Start tracking
tracker.start();

Manual Event Tracking

// Track custom events
tracker.queue({
  type: 'custom',
  action: 'button_click',
  buttonId: 'checkout',
  userId: '12345',
  ts: Date.now()
});

// Track business metrics
tracker.queue({
  type: 'conversion',
  event: 'purchase_completed',
  amount: 99.99,
  currency: 'USD'
});

Configuration Options

const tracker = new Tracker(apiKey, endpoint, sampleRate);

// Customize flush interval (default: 3000ms)
tracker.flushInterval = 5000; // Flush every 5 seconds

// Access session ID
console.log(tracker.sessionId); // Unique session identifier

// Check buffer
console.log(tracker.buffer); // Current queued events

Event Types

Observify automatically captures these event types:

Type	Description	Auto-Captured
`init`	Tracker initialization	✅
`error`	JavaScript errors	✅
`rejection`	Unhandled promise rejections	✅
`network`	Successful fetch requests	✅
`network-error`	Failed fetch requests	✅
`performance`	Page load metrics	✅
`breadcrumb`	User journey tracking	✅ (auto) / ❌ (manual)
`custom`	Your custom events	❌ (manual)

🔧 Advanced Usage

Sampling

Control what percentage of sessions are tracked:

// Track 50% of sessions
const tracker = new Tracker('api-key', 'https://api.example.com/ingest', 0.5);

// Track 10% of sessions
const tracker = new Tracker('api-key', 'https://api.example.com/ingest', 0.1);

Manual Flush

// Flush events immediately
await tracker.flush();

React Integration

import { useEffect } from 'react';
import { Tracker } from '@observify/tracker';

function App() {
  useEffect(() => {
    const tracker = new Tracker(
      process.env.REACT_APP_OBSERVIFY_KEY,
      process.env.REACT_APP_OBSERVIFY_ENDPOINT
    );
    tracker.start();
    
    return () => {
      tracker.flush(); // Flush on unmount
    };
  }, []);

  return <div>Your App</div>;
}

Vue Integration

import { Tracker } from '@observify/tracker';

export default {
  created() {
    this.tracker = new Tracker(
      process.env.VUE_APP_OBSERVIFY_KEY,
      process.env.VUE_APP_OBSERVIFY_ENDPOINT
    );
    this.tracker.start();
  },
  beforeUnmount() {
    this.tracker.flush();
  }
};

🍞 Breadcrumbs

Breadcrumbs help you understand the user journey leading up to an error or event. Observify automatically captures breadcrumbs for common user interactions and allows you to add custom breadcrumbs.

Automatic Breadcrumbs

Observify automatically captures breadcrumbs for:

Navigation: Page loads and URL changes
User Clicks: Button and link clicks (with XPath)
Network Requests: Fetch API calls (URL, method, status, duration)

// Breadcrumbs are captured automatically when you start the tracker
tracker.start();

// Now all navigation, clicks, and network requests are tracked!

Manual Breadcrumbs

Add custom breadcrumbs to track business logic, user flows, or important events:

// Basic breadcrumb
tracker.addBreadcrumb({
  message: 'User started checkout',
  category: 'navigation'
});

// Breadcrumb with additional data
tracker.addBreadcrumb({
  message: 'Item added to cart',
  category: 'user-action',
  level: 'info',
  data: {
    productId: '12345',
    quantity: 2,
    price: 29.99
  }
});

// Error-level breadcrumb
tracker.addBreadcrumb({
  message: 'Payment validation failed',
  category: 'business-logic',
  level: 'error',
  data: {
    reason: 'Invalid card number',
    attemptCount: 3
  }
});

Property	Type	Required	Description
`message`	`string`	✅	Description of the breadcrumb
`category`	`string`	❌	Category (e.g., 'navigation', 'user-action', 'network')
`level`	`'info' \| 'warning' \| 'error' \| 'debug'`	❌	Severity level (default: 'info')
`data`	`object`	❌	Additional context data
`timestamp`	`number`	❌	Auto-generated if not provided

Breadcrumbs in Error Events

When an error occurs, Observify automatically attaches the last 50 breadcrumbs to the error event:

// User journey:
// 1. Clicked "Add to Cart" button
// 2. Navigated to /checkout
// 3. Filled payment form
// 4. Error occurred!

// The error event will include all breadcrumbs:
{
  type: 'error',
  message: 'Payment processing failed',
  breadcrumbs: [
    { type: 'ui.click', message: 'Clicked button#add-to-cart', ... },
    { type: 'navigation', message: 'Navigated to /checkout', ... },
    { type: 'user-action', message: 'Filled payment form', ... }
  ],
  // ... other error properties
}

Maximum breadcrumbs: 50 (configurable via tracker.maxBreadcrumbs)
Oldest breadcrumbs are removed when limit is reached
Breadcrumbs are session-scoped (cleared on page reload)

// Customize max breadcrumbs (default: 50)
tracker.maxBreadcrumbs = 100;

Accessing Breadcrumbs

// View current breadcrumbs
console.log(tracker.breadcrumbs);

// Get breadcrumb count
console.log(`Total breadcrumbs: ${tracker.breadcrumbs.length}`);

Backend Setup

You need a backend to receive events. See the full project for a complete backend implementation.

Quick backend example:

// Express.js endpoint
app.post('/ingest', (req, res) => {
  const events = req.body.events;
  // Store events in database
  console.log('Received events:', events);
  res.json({ ok: true });
});

API Reference

`Tracker`

Constructor

new Tracker(apiKey: string, endpoint: string, sampleRate?: number)

Parameters:

apiKey - Your API key for authentication
endpoint - Backend ingestion URL
sampleRate - Sampling rate 0-1 (default: 1)

Methods

start()

Initializes event listeners
Starts auto-flush timer
Sends init event

queue(event: TrackerEvent)

Manually queue an event
Auto-flushes if buffer reaches 8 events

flush(): Promise<void>

Manually flush buffered events
Returns a promise

addBreadcrumb(breadcrumb: Partial<Breadcrumb>)

Manually add a breadcrumb to track user journey
Breadcrumbs are automatically attached to error events
Maximum 50 breadcrumbs kept (configurable)

Properties

buffer: TrackerEvent[] - Current event buffer
sessionId: string - Unique session ID
flushInterval: number - Flush interval in ms (default: 3000)
breadcrumbs: Breadcrumb[] - Current breadcrumbs array
maxBreadcrumbs: number - Maximum breadcrumbs to keep (default: 50)

Contributing

Contributions are welcome! Please see the GitHub repository.

License

MIT © Rethash

Support

Made by Rethash LinkedIn: https://www.linkedin.com/in/rethash-reddy/ GitHub: https://github.com/reth0608

observify-tracker