@elyochola/analytics-web

Browser SDK for Pulse analytics. Auto-tracks page views, errors, and Web Vitals.

Installation

npm install @elyochola/analytics-web

Quick Start

import { createBrowserAnalytics } from '@elyochola/analytics-web';

const analytics = createBrowserAnalytics({
  apiKey: 'pk_live_xxx',                // Publishable key (safe for browsers)
  endpoint: 'https://ingest.example.com',
});

// Track custom events
analytics.track('button_clicked', { buttonId: 'signup' });

// Identify users
analytics.identify('user_123', { name: 'Ely', plan: 'pro' });

Auto-Tracking

By default, the SDK automatically tracks:

| Feature | Default | Description | |---------|---------|-------------| | Page views | true | Tracks route changes (pushState, popstate) | | Errors | true | Captures window.onerror and unhandled promise rejections | | Web Vitals | true | LCP, FID, CLS, TTFB, FCP via PerformanceObserver |

Disable with:

const analytics = createBrowserAnalytics({
  apiKey: 'pk_live_xxx',
  endpoint: 'https://ingest.example.com',
  autoPageViews: false,
  autoErrors: false,
  autoPerformance: false,
});

Next.js Integration

// pages/_app.js
import { createBrowserAnalytics } from '@elyochola/analytics-web';
import { useEffect } from 'react';

const analytics = typeof window !== 'undefined'
  ? createBrowserAnalytics({
      apiKey: process.env.NEXT_PUBLIC_PULSE_KEY,
      endpoint: process.env.NEXT_PUBLIC_PULSE_ENDPOINT,
    })
  : null;

export default function App({ Component, pageProps }) {
  return <Component {...pageProps} />;
}

API

| Method | Description | |--------|-------------| | track(eventName, properties?) | Track a custom event | | identify(userId, traits?) | Identify a user | | page(properties?) | Manual page view | | error(err, properties?) | Manual error capture | | setGlobalProperties(props) | Add props to every event | | reset() | Clear identity and session | | flush() | Force flush | | shutdown() | Flush and stop tracking |

Session Management

Sessions are tracked automatically using sessionStorage. A new session starts when:

• The user opens a new tab
• 30 minutes of inactivity elapses (configurable via sessionTimeout)

Anonymous IDs persist in localStorage across sessions.

Privacy

• Uses publishable keys that are rate-limited and origin-validated
• No cookies by default — uses localStorage/sessionStorage
• Call analytics.reset() on logout to clear identity