Documentation Index
Fetch the complete documentation index at: https://mintlify.com/databuddy-analytics/Databuddy/llms.txt
Use this file to discover all available pages before exploring further.
Installation
Install the SDK package:
npm install @databuddy/sdk
Quick Start
Import and use the tracking functions:
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();
Core Functions
track()
Tracks a custom event with optional properties.
track(name: string, properties?: Record<string, unknown>): void
name - Event name (e.g., "signup", "purchase", "feature_used")properties - Key-value pairs of event metadata
Example:
track('item_purchased', {
itemId: 'sku-123',
price: 29.99,
currency: 'USD',
category: 'electronics'
});
trackError()
Tracks an error event with context.
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()
Forces all queued events to be sent immediately.
Example:
// Ensure event is sent before navigation
function handleExternalLink(url: string) {
track('external_link_clicked', { url });
flush(); // Send immediately
window.location.href = url;
}
clear()
Clears the current session and generates new IDs.
Example:
async function handleLogout() {
await signOut();
clear(); // Reset tracking identity
router.push('/login');
}
Identity Functions
getAnonymousId()
Returns the persistent anonymous user ID.
getAnonymousId(urlParams?: URLSearchParams): string | null
const anonId = getAnonymousId();
await fetch('/api/identify', {
body: JSON.stringify({ anonId })
});
getSessionId()
Returns the current session ID (resets after 30 min inactivity).
getSessionId(urlParams?: URLSearchParams): string | null
getTrackingIds()
Returns both anonymous ID and session ID.
getTrackingIds(urlParams?: URLSearchParams): {
anonId: string | null;
sessionId: string | null;
}
const { anonId, sessionId } = getTrackingIds();
await api.identify({
anonId,
sessionId,
userId: user.id
});
getTrackingParams()
Returns tracking IDs as URL query string for cross-domain tracking.
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>
Utility Functions
isTrackerAvailable()
Checks if the tracker script is loaded.
isTrackerAvailable(): boolean
if (isTrackerAvailable()) {
track('feature_used', { feature: 'export' });
} else {
console.warn('Tracker not loaded yet');
}
getTracker()
Returns the raw tracker instance.
getTracker(): DatabuddyTracker | null
const tracker = getTracker();
if (tracker) {
// Access low-level tracker methods
tracker.track('event', { prop: 'value' });
}
Best Practices
- Use
flush() before navigation - Ensure events are captured before page unload
- Call
clear() on logout - Reset identity for multi-user devices
- Track errors - Use
trackError() to monitor client-side errors
- Cross-domain tracking - Use
getTrackingParams() to preserve identity across domains
- Server-side identification - Use
getTrackingIds() to correlate client and server events