@pandastack/event-tracker

A lightweight SDK for tracking events in both browser and server environments. Events are automatically batched and sent to your specified endpoint.

Features

• 🌐 Browser event tracking (page views, clicks)
• 🖥️ Server-side API request tracking
• 📦 Automatic event batching
• 🔄 Offline support (browser)
• 📊 Custom event support
• 🛡️ TypeScript support

Installation

npm install @pandastack/event-tracker
# or
yarn add @pandastack/event-tracker

Browser Usage

import { browserTracker } from '@pandastack/event-tracker';

// Initialize with configuration
browserTracker.init({
  projectId: 'my-project', // optional
  endpoint: 'https://your-endpoint.com/events', // optional
  debug: true // optional
});

// Track custom events
browserTracker.track('button_click', {
  buttonId: 'signup',
  page: '/home'
});

// Automatic tracking includes:
// - Page views
// - Click events (with element details)

Advanced Browser Usage

import { BrowserTracker } from '@pandastack/event-tracker';

// Create custom instance
const tracker = new BrowserTracker({
  projectId: 'my-project',
  endpoint: 'https://your-endpoint.com/events',
  batchSize: 10, // events per batch
  batchInterval: 5000, // flush interval in ms
  debug: true
});

tracker.init();

// Custom event with metadata
tracker.track('form_submit', {
  formId: 'contact',
  success: true,
  duration: 1500
});

// Cleanup when needed
tracker.destroy();

Server Usage (Express Middleware)

import express from 'express';
import { createRequestTracker } from '@pandastack/event-tracker';

const app = express();

// Add the tracking middleware
app.use(createRequestTracker({
  projectId: 'my-project',
  endpoint: 'https://your-endpoint.com/events',
  ignorePaths: ['/health', '/metrics'],
  customFields: (req) => ({
    userId: req.user?.id,
    // Add any custom fields from the request
  })
}));

// Your routes
app.get('/api/data', (req, res) => {
  res.json({ message: 'Hello!' });
});

Advanced Server Usage

import { ServerTracker } from '@pandastack/event-tracker';

const tracker = new ServerTracker({
  projectId: 'my-project',
  endpoint: 'https://your-endpoint.com/events',
  batchSize: 50,
  batchInterval: 10000,
  debug: true,
  ignorePaths: [
    '/health',
    '/metrics',
    /^\/static\//  // Regex support
  ],
  customFields: (req) => ({
    userId: req.user?.id,
    ip: req.ip,
    userAgent: req.get('user-agent')
  })
});

app.use(tracker.middleware());

Event Types

Browser Events

// Page View Event
{
  event_type: 'pageview',
  timestamp: 1645568732000,
  project_id: 'my-project',
  session_id: 'abc123',
  page_url: 'https://example.com/products',
  referrer: 'https://google.com',
  user_agent: '...'
}

// Click Event
{
  event_type: 'click',
  timestamp: 1645568732000,
  project_id: 'my-project',
  session_id: 'abc123',
  page_url: 'https://example.com/products',
  element_id: 'signup-button',
  element_class: 'btn primary',
  element_text: 'Sign Up Now'
}

API Events

{
  event_type: 'api_request',
  timestamp: 1645568732000,
  project_id: 'my-project',
  method: 'GET',
  path: '/api/products',
  status_code: 200,
  duration_ms: 150,
  request_id: 'req_abc123',
  ip_address: '127.0.0.1',
  user_agent: '...',
  metadata: {
    query: { page: '1' },
    // Custom fields...
  }
}

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Examples

The SDK comes with example implementations for both browser and server usage.

Browser Example

# First build the SDK
npm run build

# Then serve the examples directory using any static server
# For example, using Python's built-in server:
python3 -m http.server 8000

# Visit http://localhost:8000/examples/browser/

The browser example demonstrates:

• Automatic page view tracking
• Click event tracking
• Custom event tracking
• Event batching
• Debug logging

Server Example

# First build the SDK
npm run build

# Then install dependencies and run the server example
cd examples/server
npm install
npm start

# The server will start at http://localhost:3000
# Try these endpoints:
# - GET /api/hello
# - GET /api/error
# - GET /api/slow

The server example demonstrates:

• API request tracking
• Response time monitoring
• Error tracking
• Custom field injection
• Debug logging

License

MIT