Core Tracker

npm install @databuddy/sdk

import { track, flush, clear } from '@databuddy/sdk';

// Track custom event
track('button_click', {
  buttonName: 'checkout',
  value: 99.99
});

// Force send queued events
flush();

// Clear session (e.g., on logout)
clear();

track(name: string, properties?: Record<string, unknown>): void

track('item_purchased', {
  itemId: 'sku-123',
  price: 29.99,
  currency: 'USD',
  category: 'electronics'
});

trackError(message: string, properties?: {
  filename?: string;
  lineno?: number;
  colno?: number;
  stack?: string;
  error_type?: string;
  [key: string]: unknown;
}): void

try {
  await riskyOperation();
} catch (error) {
  trackError(error.message, {
    stack: error.stack,
    error_type: error.name,
    context: 'checkout_flow',
    userId: currentUser.id
  });
}

flush(): void

// Ensure event is sent before navigation
function handleExternalLink(url: string) {
  track('external_link_clicked', { url });
  flush(); // Send immediately
  window.location.href = url;
}

clear(): void

async function handleLogout() {
  await signOut();
  clear(); // Reset tracking identity
  router.push('/login');
}

getAnonymousId(urlParams?: URLSearchParams): string | null

const anonId = getAnonymousId();
await fetch('/api/identify', {
  body: JSON.stringify({ anonId })
});

getSessionId(urlParams?: URLSearchParams): string | null

getTrackingIds(urlParams?: URLSearchParams): {
  anonId: string | null;
  sessionId: string | null;
}

const { anonId, sessionId } = getTrackingIds();
await api.identify({
  anonId,
  sessionId,
  userId: user.id
});

getTrackingParams(urlParams?: URLSearchParams): string

// Link to subdomain with tracking continuity
const params = getTrackingParams();
const url = `https://app.example.com/dashboard${params ? `?${params}` : ''}`;

// In JSX
<a href={`https://shop.example.com?${getTrackingParams()}`}>
  Visit Shop
</a>

isTrackerAvailable(): boolean

if (isTrackerAvailable()) {
  track('feature_used', { feature: 'export' });
} else {
  console.warn('Tracker not loaded yet');
}

getTracker(): DatabuddyTracker | null

const tracker = getTracker();
if (tracker) {
  // Access low-level tracker methods
  tracker.track('event', { prop: 'value' });
}