@zetalyx/browser

Browser SDK for Zetalyx — tracks events, errors, and user behaviors from web applications.

Installation

npm install @zetalyx/browser

Quick Start

import { BrowserClient } from '@zetalyx/browser';

const zetalyx = new BrowserClient({
  apiKey: 'pk_live_your_api_key',
});

// Track a custom event
zetalyx.track('page_view', { page: '/dashboard' });

// Track an error
zetalyx.trackError(new Error('Something failed'));

// Track user behavior
zetalyx.trackBehavior('button_click', { button: 'signup' });

// Identify a user
zetalyx.identify('user_123', { plan: 'pro' });

Features

• Automatic error capture — catches window.onerror and unhandledrejection out of the box
• Click tracking — opt-in auto-tracking of clicks on buttons, links, and interactive elements
• Session management — automatic session_id (sessionStorage) and anonymous_id (localStorage)
• Client enrichment — collects URL, viewport, locale, timezone, user agent, connection type
• Batched transport — events are queued and sent in batches with retry/backoff
• Page visibility flush — flushes queue when the tab goes hidden
• Unload flush — uses sendBeacon on page unload for reliable delivery

Configuration

const zetalyx = new BrowserClient({
  apiKey: 'pk_live_...',       // Required
  endpoint: 'https://...',     // Default: 'https://api.zetalyx.com'
  batchSize: 10,               // Flush after N events
  flushInterval: 5000,         // Flush every N ms
  maxRetries: 3,               // Retry on 5xx/network error
  debug: false,                // Console debug logging
  enabled: true,               // Master kill switch

  // Browser-specific
  autoCapture: true,           // Auto-capture window errors (default: true)
  captureClicks: false,        // Auto-track clicks on interactive elements (default: false)

  // Hooks
  beforeSend: (event) => {     // Transform/filter events
    if (event.metadata?.internal) return null; // Drop internal events
    return event;
  },
});

API

zetalyx.track(eventType, metadata?)

Track a custom event.

zetalyx.track('purchase', {
  product_id: 'sku_123',
  amount: 29.99,
  currency: 'USD',
});

zetalyx.trackError(error, metadata?)

Track an error. Accepts an Error object, a string, or a full ErrorPayload.

// From a caught error
try {
  riskyOperation();
} catch (err) {
  zetalyx.trackError(err, { context: 'checkout' });
}

// From a string
zetalyx.trackError('Payment gateway timeout');

zetalyx.trackBehavior(action, data?)

Track a user behavior/interaction.

zetalyx.trackBehavior('search', {
  query: 'react hooks',
  results_count: 42,
});

zetalyx.identify(userId, traits?)

Associate tracking data with a known user.

zetalyx.identify('user_123', {
  email: '[email protected]',
  plan: 'enterprise',
});

zetalyx.reset()

Clear user identity (e.g., on logout). Generates a new anonymous ID.

zetalyx.reset();

zetalyx.flush()

Manually flush the event queue.

await zetalyx.flush();

zetalyx.shutdown()

Flush remaining events and stop all tracking.

await zetalyx.shutdown();

Click Tracking

When captureClicks: true, the SDK automatically tracks clicks on:

• <button> elements
• <a> links
• input[type="submit"]
• Elements with [role="button"]
• Elements with [data-ztlx-track] attribute

You can add custom tracking names via the data attribute:

<button data-ztlx-track="cta_hero">Get Started</button>

Auto-Captured Metadata

Every event automatically includes client enrichment:

| Field | Description | |-------|-------------| | url | Full page URL | | path | URL pathname | | referrer | Document referrer | | title | Page title | | screen_width / screen_height | Screen dimensions | | viewport_width / viewport_height | Viewport dimensions | | locale | Browser language | | timezone | User timezone | | user_agent | Browser user agent | | connection_type | Network connection type (if available) |

License

MIT