Getting Started

Install and configure Databuddy for your application

Getting Started with Databuddy

This guide will help you set up Databuddy analytics in your application in just a few minutes.

Prerequisites: You'll need a verified domain before you can create a project. Verify your domain first if you haven't already.

Create Your Account

  1. Go to app.databuddy.cc
  2. Sign up for a free account
  3. Create your first project with your verified domain
  4. Copy your Client ID from the dashboard

Make sure your domain is verified before creating a project. Unverified domains cannot track analytics data.

Install the SDK

Choose your installation method based on your application type:

Install the official Databuddy SDK:

# Using bun (recommended)
bun add @databuddy/sdk

# Using npm
npm install @databuddy/sdk

# Using yarn
yarn add @databuddy/sdk

For any website, use the script tag method:

<script 
  src="https://app.databuddy.cc/databuddy.js"
  data-client-id="your-client-id-here"
  data-track-screen-views="true"
  data-track-performance="true"
  defer
></script>

Configure Tracking

Add the <Databuddy /> component to your root layout:

app/layout.tsx
import { Databuddy } from '@databuddy/sdk';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <head />
      <body>
        <Databuddy
          clientId={process.env.NEXT_PUBLIC_DATABUDDY_CLIENT_ID!}
          trackScreenViews
          trackPerformance
          trackWebVitals
          trackErrors
        />
        {children}
      </body>
    </html>
  );
}

Environment Variables:

.env.local
NEXT_PUBLIC_DATABUDDY_CLIENT_ID=your-client-id-here

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

index.html
<!DOCTYPE html>
<html>
<head>
  <title>My Website</title>
</head>
<body>
  <!-- Your content -->
  
  <!-- Databuddy Analytics -->
  <script 
    src="https://app.databuddy.cc/databuddy.js"
    data-client-id="your-client-id-here"
    data-track-screen-views="true"
    data-track-performance="true"
    data-track-web-vitals="true"
    data-track-errors="true"
    defer
  ></script>
</body>
</html>

Verify Installation

Check that analytics are working correctly:

  1. Visit your website in a new browser tab
  2. Open your Databuddy dashboard at app.databuddy.cc
  3. Check Real-time data - you should see yourself as an active visitor
  4. Navigate between pages - verify page views are being recorded

If you see real-time data in your dashboard, congratulations! Databuddy is now tracking your website analytics.

⚙️ Configuration Options

Essential Settings

Recommended Configuration
<Databuddy
  clientId="your-client-id"
  
  // Core tracking (recommended for all sites)
  trackScreenViews={true}        // Track page/route changes
  trackPerformance={true}        // Track loading times
  trackWebVitals={true}         // Track Core Web Vitals
  trackErrors={true}            // Track JavaScript errors
  
  // Optional tracking (enable as needed)
  trackSessions={true}          // Track user sessions
  trackOutgoingLinks={false}    // Track external link clicks
  trackScrollDepth={false}      // Track scroll behavior
  trackEngagement={false}       // Track user engagement
/>
Recommended Configuration
<script 
  src="https://app.databuddy.cc/databuddy.js"
  data-client-id="your-client-id"
  
  data-track-screen-views="true"
  data-track-performance="true"
  data-track-web-vitals="true"
  data-track-errors="true"
  
  data-track-sessions="true"
  data-track-outgoing-links="false"
  data-enable-batching="true"
  data-batch-size="10"
  defer
></script>

<Callout type="info">
**Security**: All tracking scripts automatically include `crossorigin="anonymous"` for enhanced security.
</Callout>

Environment-Specific Setup

Best Practice: Disable tracking in development to avoid polluting your analytics with test data.

Environment Configuration
const isDevelopment = process.env.NODE_ENV === 'development';
const isProduction = process.env.NODE_ENV === 'production';

<Databuddy
  clientId={process.env.NEXT_PUBLIC_DATABUDDY_CLIENT_ID!}
  disabled={isDevelopment} // 🚫 No tracking in development
  
  // Core tracking
  trackScreenViews
  trackPerformance
  trackWebVitals={isProduction}
  trackErrors={isProduction}
  
  // Performance optimizations for production
  enableBatching={isProduction}
  batchSize={isProduction ? 20 : 1}
  samplingRate={isProduction ? 1.0 : 0.1}
/>

🎯 Custom Event Tracking

Track custom events with rich properties for comprehensive analytics:

Custom Events with Rich Properties
import { useEffect } from 'react';

function SignupForm() {
  const handleSignup = (plan: string) => {
    // Track conversion event with detailed context
    window.databuddy?.track('signup_completed', {
      source: 'landing_page',
      plan: plan,
      trial_days: plan === 'pro' ? 14 : 7,
      form_type: 'inline',
      utm_source: new URLSearchParams(window.location.search).get('utm_source'),
      referrer_domain: document.referrer ? new URL(document.referrer).hostname : null
    });
  };

  const handleFormInteraction = (fieldName: string) => {
    // Track form engagement
    window.databuddy?.track('form_field_focused', {
      form_type: 'signup',
      field_name: fieldName,
      page: window.location.pathname,
      user_agent_mobile: /Mobile|Android/i.test(navigator.userAgent)
    });
  };

  useEffect(() => {
    // Track form view with context
    window.databuddy?.track('signup_form_viewed', {
      page: window.location.pathname,
      form_position: 'hero_section',
      visit_source: document.referrer || 'direct',
      viewport_width: window.innerWidth
    });
  }, []);

  return (
    <form onSubmit={() => handleSignup('free')}>
      <input 
        type="email" 
        onFocus={() => handleFormInteraction('email')}
        placeholder="Enter your email" 
      />
      <button type="submit">Sign Up Free</button>
      <button type="button" onClick={() => handleSignup('pro')}>
        Start Pro Trial
      </button>
    </form>
  );
}
Custom Events with Detailed Properties
<script>
// Track button clicks with comprehensive context
function trackSignup(plan) {
  db.track('signup_completed', {
    source: 'landing_page',
    plan: plan,
    trial_days: plan === 'pro' ? 14 : 7,
    button_position: 'hero',
    page_scroll_depth: Math.round((window.pageYOffset / document.body.scrollHeight) * 100),
    session_page_count: sessionStorage.getItem('page_count') || 1
  });
}

// Track feature usage with user context
function trackFeatureUsed(feature, context) {
  db.track('feature_used', {
    feature: feature,
    page: window.location.pathname,
    user_tier: context?.tier || 'free',
    feature_category: context?.category || 'general',
    previous_page: document.referrer || 'direct',
    time_on_page: Date.now() - window.pageLoadTime
  });
}

// Track product interactions
function trackProductView(productId, category) {
  db.track('product_viewed', {
    product_id: productId,
    product_category: category,
    view_source: 'product_grid',
    page: window.location.pathname,
    user_returning: localStorage.getItem('returning_user') === 'true'
  });
}

// Store page load time for time-on-page calculations
window.pageLoadTime = Date.now();
</script>

<button onclick="trackSignup('free')">Sign Up Free</button>
<button onclick="trackSignup('pro')">Start Pro Trial</button>
<button onclick="trackFeatureUsed('export', {tier: 'premium', category: 'data'})">
  Export Data
</button>

Property Analytics: Your custom event properties are automatically analyzed in the dashboard with expandable breakdowns, showing property distributions and value percentages in an interactive tree structure.

🎉 What's Next?

🆘 Troubleshooting

Not seeing data in your dashboard?

  1. Check your Client ID - Make sure it matches your project
  2. Verify your domain - Ensure your domain is verified in the dashboard
  3. Test manually - Try db.track('test', {}) in your browser console
  4. Check Network tab - Look for requests to basket.databuddy.cc
  5. Review environment - Make sure tracking isn't disabled in production

Need help? Join our Discord community or contact support.