@billdog.io/analytics

BillDog Analytics SDK v2.0.0 - Industry-standard event tracking like Mixpanel.

Server-authoritative audience

Analytics records customer events and attributes used by server-side segmentation. Report filtering can consume segment IDs, but the Analytics SDK does not import or evaluate @billdog.io/segments or @billdog.io/targeting at runtime.

Installation

npm install @billdog.io/analytics
# or
yarn add @billdog.io/analytics

Quick Start

import { analytics } from '@billdog.io/analytics';

// Configure the SDK
analytics.configure({
  apiKey: 'your-api-key',
  projectUrl: 'https://your-project.supabase.co',
  enableLogging: true,
  autoTrack: true, // Enable automatic tracking (default)
});

// Identify a user
analytics.identify('user123', {
  email: '[email protected]',
  name: 'John Doe',
  plan: 'premium'
});

// Track an event
analytics.track('Button Clicked', {
  button_name: 'Subscribe',
  screen: 'Paywall'
});

Core Features

Event Tracking

// Track any event with properties
analytics.track('Purchase Completed', {
  product_id: 'premium_monthly',
  price: 9.99,
  currency: 'USD'
});

// Track screen views
analytics.trackScreen('Onboarding');

// Track revenue (high priority - flushes immediately)
analytics.trackRevenue(9.99, 'USD', {
  product_id: 'premium_monthly',
  payment_method: 'credit_card'
});

// Time an event (measure duration)
analytics.timeEvent('Checkout');
// ... later
analytics.track('Checkout'); // Includes $duration property

User Properties

// Set a single property
analytics.setUserProperty('plan', 'premium');

// Set multiple properties
analytics.setUserProperties({
  plan: 'premium',
  region: 'US',
  signup_date: '2024-01-15'
});

// Increment numeric properties
analytics.incrementUserProperty('login_count');
analytics.incrementUserProperty('purchases', 2);

// Append to array properties
analytics.appendToUserProperty('interests', 'music');

Super Properties

Super properties are attached to every event automatically.

// Set super properties
analytics.setSuperProperty('app_version', '2.1.0');
analytics.setSuperProperties({
  platform: 'ios',
  environment: 'production'
});

// Get current super properties
const props = analytics.getSuperProperties();

// Clear all super properties
analytics.clearSuperProperties();

Groups (B2B Analytics)

// Associate user with a group
analytics.setGroup('company', 'acme-corp');

// Set group properties
analytics.setGroupProperties('company', 'acme-corp', {
  name: 'Acme Corporation',
  industry: 'Technology',
  employee_count: 500
});

Identity Management

// Identify a user
analytics.identify('user123', { email: '[email protected]' });

// Alias (link anonymous ID to user ID)
analytics.alias('user123', 'anon_abc123');

// Reset (logout)
analytics.reset();

// Get IDs
analytics.getUserId();      // 'user123' or undefined
analytics.getAnonymousId(); // 'anon_...'
analytics.getSessionId();   // 'sess_...'

Attribution

// Set attribution context (attached to revenue events)
analytics.setAttributionContext({
  notification_id: 'notif_123',
  campaign_id: 'summer_sale',
  source: 'email',
  medium: 'newsletter'
});

// Get current attribution
const attr = analytics.getAttributionContext();

// Clear attribution
analytics.clearAttributionContext();

Control

// Force flush events to server
await analytics.flush();

// GDPR: Opt out (stops all tracking, resets data)
analytics.optOut();

// GDPR: Opt back in
analytics.optIn();

Auto-Tracking

By default, the SDK automatically tracks:

| Event | Description | |-------|-------------| | $session_start | New session started | | $session_end | Session ended (page unload) | | $page_view | Page/screen view | | $app_foregrounded | App became visible | | $app_backgrounded | App went to background | | $first_open | First time user opened app | | $deep_link | UTM parameters detected |

Configure Auto-Tracking

analytics.configure({
  apiKey: '...',
  projectUrl: '...',
  autoTrack: {
    pageViews: true,      // Track page views
    sessions: true,       // Track session start/end
    appLifecycle: true,   // Track foreground/background
    attribution: true,    // Track UTM parameters
    deepLinks: true,      // Track deep links
    scrollDepth: false,   // Track scroll depth (opt-in)
  }
});

// Or disable all auto-tracking
analytics.configure({
  apiKey: '...',
  projectUrl: '...',
  autoTrack: false
});

Advanced Usage

Offline Support

Events are automatically queued to IndexedDB when offline and synced when back online.

Compression

All events are compressed (40-55% smaller) before sending to minimize bandwidth.

Screen Tracker

import { ScreenTracker } from '@billdog.io/analytics';

const screenTracker = new ScreenTracker(analytics, {
  trackTiming: true,
  trackScrollDepth: true,
  screenNameResolver: (path, title) => customScreenName
});

screenTracker.autoTrack();

Attribution Tracker

import { AttributionTracker } from '@billdog.io/analytics';

const attrTracker = new AttributionTracker(analytics, {
  attributionWindow: 30, // days
  firstTouch: true,      // use first-touch attribution
  persist: true          // persist across sessions
});

attrTracker.initialize();

Migration from @billdog.io/analysis

// BEFORE (deprecated)
import { analysis, AnalysisSDK } from '@billdog.io/analysis';

// AFTER (recommended)
import { analytics, AnalyticsSDK } from '@billdog.io/analytics';

// Backward compatible aliases still work
import { analysis } from '@billdog.io/analytics'; // Works!

API Reference

AnalyticsSDK

| Method | Description | |--------|-------------| | configure(config) | Initialize the SDK | | identify(userId, properties?) | Identify a user | | alias(newId, previousId) | Link two IDs | | reset() | Reset user state | | track(event, properties?) | Track an event | | trackScreen(name, properties?) | Track a screen view | | trackRevenue(amount, currency, properties?) | Track revenue | | timeEvent(event) | Start timing an event | | setUserProperty(key, value) | Set user property | | setUserProperties(props) | Set multiple user properties | | incrementUserProperty(key, amount?) | Increment user property | | appendToUserProperty(key, value) | Append to array property | | setSuperProperty(key, value) | Set super property | | setSuperProperties(props) | Set multiple super properties | | getSuperProperties() | Get all super properties | | clearSuperProperties() | Clear super properties | | setAttributionContext(ctx) | Set attribution context | | getAttributionContext() | Get attribution context | | clearAttributionContext() | Clear attribution context | | setGroup(type, id) | Set group membership | | setGroupProperties(type, id, props) | Set group properties | | flush() | Force send events | | optOut() | Stop tracking (GDPR) | | optIn() | Resume tracking | | getUserId() | Get current user ID | | getAnonymousId() | Get anonymous ID | | getSessionId() | Get session ID |

License

MIT