BlogPricingDashboardGitHubGitHub★ 493

Getting Started

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

Try Databuddy with Leap

Let Leap generate a complete application that uses Databuddy for analytics.

Examples:
1

Create Your Account

  1. Go to app.databuddy.cc
  2. Sign up for a free account
  3. Copy your Client ID from the dashboard
2

Install the SDK

Choose your installation method based on your application type:

Install the official Databuddy SDK:

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

# Using npm
npm install @databuddy/sdk

# Using yarn
yarn add @databuddy/sdk
3

Configure Tracking

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

app/layout.tsxtsx
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={true} // Default is false, explicitly enable for quick start
        trackErrors={true} // Default is false, explicitly enable for quick start
      />
      {children}
    </body>
  </html>
);
}

Environment Variables:

.env.localbash
NEXT_PUBLIC_DATABUDDY_CLIENT_ID=your-client-id-here
4

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

Configuration Options

Essential Settings

Recommended Configurationtsx
<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
/>

Environment-Specific Setup

Environment Configurationtsx
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 Propertiestsx
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: "in    line",
    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>
);
}

What's Next?

API Playground

Test endpoints interactively and explore query types with real data

SDK Configuration Guide

Explore all SDK configuration props and options

Dashboard Guide

Learn to navigate your analytics dashboard and its features

Event Tracking Deep Dive

Master custom event tracking, SDK methods, and standard event types

Security & Privacy

Configure privacy settings and GDPR compliance

Troubleshooting

Not seeing data in your dashboard?

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