analytics/docs/client-sdk.md

Client SDK Documentation

The @analytics/client package provides browser and server-side analytics tracking.

Installation

npm install @analytics/client
# or
yarn add @analytics/client
# or
bun add @analytics/client

Quick Start

Browser (Vanilla JavaScript)

import { AnalyticsClient } from '@analytics/client';

const analytics = new AnalyticsClient({
  apiBaseUrl: 'https://analytics.example.com',
  appName: 'my-app',
});

// Track a page view
analytics.trackEngagement({
  type: 'navigation',
  action: 'page_view',
  metadata: { path: window.location.pathname },
});

// Track a custom event
analytics.trackEngagement({
  type: 'user_action',
  action: 'button_click',
  metadata: { buttonId: 'signup-cta' },
});

// Identify a user
analytics.identify('user-123', {
  email: 'user@example.com',
  plan: 'pro',
});

Server-Side (Node.js)

import { BackendAnalyticsClient } from '@analytics/client';

const analytics = new BackendAnalyticsClient({
  apiBaseUrl: 'http://analytics-collector:4001',
  appName: 'my-api',
});

// Track from server
analytics.trackEngagement({
  sessionId: req.headers['x-session-id'] || 'server',
  userId: req.user?.id,
  type: 'api_request',
  action: 'GET /users',
  metadata: {
    statusCode: 200,
    durationMs: 45,
  },
});

Configuration

AnalyticsConfig

Property	Type	Default	Description
apiBaseUrl	string	required	Analytics collector URL
appName	string	required	Application identifier
enabled	boolean	true	Enable/disable tracking
enableDebugLogging	boolean	false	Log tracking calls
batchSize	number	10	Events per batch
flushInterval	number	5000	Batch flush interval (ms)
autoCapture	object	see below	Auto-capture settings

Auto-Capture Settings

{
  autoCapture: {
    pageViews: true,      // Track page navigation
    clicks: true,         // Track click events
    scrollDepth: true,    // Track scroll percentage
    performance: true,    // Track Core Web Vitals
    errors: false,        // Track JavaScript errors
  }
}

Core Methods

trackEngagement()

Track user interactions and events.

analytics.trackEngagement({
  type: string,           // Event category
  action: string,         // Event name
  metadata?: object,      // Additional data
  sessionId?: string,     // Override session ID
  userId?: string,        // User identifier
});

identify()

Associate a user ID with the current session.

analytics.identify(userId: string, traits?: object);

setUserId() / clearUserId()

Manage user identity.

analytics.setUserId('user-123');
analytics.clearUserId();

flush()

Force send queued events immediately.

await analytics.flush();

Event Types

Navigation Events

// Page view
analytics.trackEngagement({
  type: 'navigation',
  action: 'page_view',
  metadata: {
    path: '/products',
    title: 'Products Page',
    referrer: document.referrer,
  },
});

// Route change (SPA)
analytics.trackEngagement({
  type: 'navigation',
  action: 'route_change',
  metadata: {
    from: '/home',
    to: '/products',
  },
});

User Actions

// Button click
analytics.trackEngagement({
  type: 'click',
  action: 'cta_button',
  metadata: {
    buttonText: 'Get Started',
    location: 'hero',
  },
});

// Form submission
analytics.trackEngagement({
  type: 'form',
  action: 'submit',
  metadata: {
    formName: 'contact',
    success: true,
  },
});

E-commerce Events

// Product view
analytics.trackEngagement({
  type: 'ecommerce',
  action: 'product_view',
  metadata: {
    productId: 'prod-123',
    productName: 'Blue Widget',
    price: 29.99,
  },
});

// Purchase
analytics.trackEngagement({
  type: 'ecommerce',
  action: 'purchase',
  metadata: {
    orderId: 'ord-456',
    total: 99.99,
    currency: 'USD',
    isConversion: true,
    conversionValue: 99.99,
  },
});

Consent-Free Mode

The SDK uses in-memory session IDs by default, requiring no cookies or localStorage:

• Session IDs generated per page load
• No persistent storage used
• UTM parameters captured from URL only
• GDPR/ePrivacy compliant without consent banners

Device Information

Automatically captured (no storage required):

• Screen resolution
• Viewport size
• Device type (mobile/tablet/desktop)
• Browser name and version
• Operating system
• Language preference
• Timezone

Error Handling

The SDK silently handles errors to never break your application:

// All tracking calls are fire-and-forget
analytics.trackEngagement({...}); // Never throws

// Enable debug logging to see issues
const analytics = new AnalyticsClient({
  apiBaseUrl: '...',
  appName: '...',
  enableDebugLogging: true, // Logs to console
});

TypeScript Support

Full TypeScript support with exported types:

import type {
  AnalyticsConfig,
  EngagementEvent,
  DeviceInfo,
  AttributionData,
} from '@analytics/client';