BlogPricingDashboardGitHubGitHub★ 898
SDK Reference

Vanilla JavaScript

The Databuddy script can be used directly in vanilla JavaScript projects without any framework dependencies. This is perfect for static sites, traditional HTML pages, or any environment where you want minimal overhead.

Quick Setup

Add the script tag to your HTML before the closing </body> tag:

html
<script
src="https://cdn.databuddy.cc/databuddy.js"
data-client-id="your-client-id"
async
></script>

The script automatically initializes and starts tracking page views.

Configuration Options

Configure the tracker using data attributes on the script tag:

html
<script
src="https://cdn.databuddy.cc/databuddy.js"
data-client-id="your-client-id"
data-track-performance
data-track-errors
data-enable-batching
data-batch-size="20"
async
></script>

Available Options

OptionDefaultDescription
data-track-hash-changesfalseTrack hash changes in URL
data-track-attributesfalseTrack data-track attributes
data-track-outgoing-linksfalseTrack clicks on external links
data-track-interactionsfalseTrack button clicks and form submissions
data-track-scroll-depthfalseTrack scroll depth milestones
data-track-performancetrueInclude performance metrics
data-track-web-vitalsfalseTrack Core Web Vitals
data-track-errorsfalseTrack JavaScript errors
data-enable-batchingfalseBatch events before sending
data-batch-size10Events per batch when batching enabled
data-sampling-rate1.0Sample rate 0.0-1.0

Tracking Events

Manual Tracking

Use the global window.databuddy object to track custom events:

jsx
// Track a custom event
window.databuddy.track('button_click', {
button_text: 'Sign Up',
button_id: 'header-cta'
});

// Track with additional properties
window.databuddy.track('feature_used', {
feature: 'export_data',
user_tier: 'premium'
});

Screen Views

Manually track page views (useful for SPAs):

jsx
window.databuddy.screenView('/dashboard');

// With properties
window.databuddy.screenView('/dashboard', {
section: 'analytics'
});

Using Shorthand

For convenience, use the shorter window.db alias:

jsx
window.db.track('button_click', { button_id: 'cta' });
window.db.screenView('/dashboard');

Getting Tracking IDs

The tracker provides access to anonymous and session IDs for attribution tracking:

jsx
// Get anonymous ID
const anonId = window.databuddy.anonymousId;
console.log('Anonymous ID:', anonId);

// Get session ID
const sessionId = window.databuddy.sessionId;
console.log('Session ID:', sessionId);

// Use for redirect attribution
const signupUrl = `https://app.databuddy.cc/register?anonId=${anonId}&sessionId=${sessionId}`;
window.location.href = signupUrl;

Reading from Storage

IDs are also stored in browser storage for persistence:

jsx
// Get from localStorage
const anonId = localStorage.getItem('did');

// Get from sessionStorage
const sessionId = sessionStorage.getItem('did_session');

Global Properties

Set properties that attach to all future events:

jsx
window.databuddy.setGlobalProperties({
user_id: 'user-123',
plan: 'premium',
version: '2.0'
});

Session Management

Clear Session

Clear current session and generate new IDs:

jsx
window.databuddy.clear();

Flush Events

Force immediate sending of queued events:

jsx
window.databuddy.flush();

Error Tracking

Automatically track JavaScript errors:

html
<script
src="https://cdn.databuddy.cc/databuddy.js"
data-client-id="your-client-id"
data-track-errors
async
></script>

Or track manually:

jsx
try {
// Your code
} catch (error) {
window.databuddy.track('error', {
  message: error.message,
  filename: error.filename,
  lineno: error.lineno,
  error_type: error.name
});
}

Data Attributes Tracking

Track clicks on elements with data-track attributes:

html
<!-- Enable tracking -->
<script
src="https://cdn.databuddy.cc/databuddy.js"
data-client-id="your-client-id"
data-track-attributes
async
></script>

<!-- Elements to track -->
<button data-track="button_click" data-button-text="Sign Up" data-section="header">
Sign Up
</button>

<a href="/pricing" data-track="link_click" data-link-type="pricing">
View Pricing
</a>

Track clicks on external links:

html
<script
src="https://cdn.databuddy.cc/databuddy.js"
data-client-id="your-client-id"
data-track-outgoing-links
async
></script>

<!-- External links are automatically tracked -->
<a href="https://github.com/databuddy-analytics/Databuddy">GitHub</a>

Batch Events

Enable batching to reduce network requests:

html
<script
src="https://cdn.databuddy.cc/databuddy.js"
data-client-id="your-client-id"
data-enable-batching
data-batch-size="20"
data-batch-timeout="2000"
async
></script>

Sampling

Reduce event volume with sampling:

html
<script
src="https://cdn.databuddy.cc/databuddy.js"
data-client-id="your-client-id"
data-sampling-rate="0.5"
async
></script>

Set to 0.5 to track 50% of events, 0.1 for 10%, etc.

Skip Patterns

Skip tracking on specific paths:

html
<script
src="https://cdn.databuddy.cc/databuddy.js"
data-client-id="your-client-id"
data-skip-patterns='["/admin/**", "/internal/*"]'
async
></script>

Opt Out

Allow users to opt out of tracking:

jsx
// User opts out
window.databuddyOptOut();

// User opts back in
window.databuddyOptIn();

Opt-out is stored in localStorage and persists across sessions.

Complete Example

index.htmlhtml
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>My Website</title>
</head>
<body>
<h1>Welcome</h1>

<button onclick="trackSignup()">Sign Up</button>

<!-- Databuddy Script -->
<script
  src="https://cdn.databuddy.cc/databuddy.js"
  data-client-id="your-client-id"
  data-track-performance
  data-track-errors
  data-enable-batching
  async
></script>

<script>
  function trackSignup() {
    window.databuddy.track('signup_clicked', {
      source: 'header_button',
      timestamp: Date.now()
    });
    
    // Redirect with attribution
    const anonId = window.databuddy.anonymousId;
    const sessionId = window.databuddy.sessionId;
    window.location.href = `https://app.databuddy.cc/register?anonId=${anonId}&sessionId=${sessionId}`;
  }
</script>
</body>
</html>

Browser Compatibility

The script works in all modern browsers:

  • Chrome, Edge, Firefox, Safari (latest 2 versions)
  • Mobile browsers (iOS Safari, Chrome Mobile)
  • No Internet Explorer support

CDN URL

Use the official CDN URL for best performance:

https://cdn.databuddy.cc/databuddy.js

The script is automatically minified and gzipped for optimal performance (~15KB).

Tracker Helpers

Helper functions for the SDK

Configuration

All configuration options

React SDK

React component integration

How is this guide?

Edit on GitHub