JSPM – observify-tracker@1.0.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
✅ 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	✅
`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();
  }
};

🌐 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

Properties

buffer: TrackerEvent[] - Current event buffer
sessionId: string - Unique session ID
flushInterval: number - Flush interval in ms (default: 3000)

🤝 Contributing

Contributions are welcome! Please see the GitHub repository.

📄 License

🔗 Links

💬 Support

📧 Email: your.email@example.com
🐛 Issues: GitHub Issues
💬 Discussions: GitHub Discussions

Made with ❤️ by [Your Name]