Quickstart Guide

Get your analytics up and running in under 5 minutes. This guide will walk you through creating an account, installing the SDK, and seeing your first analytics data.

This quickstart focuses on React/Next.js. For other frameworks, see the Installation guide.

Step 1: Create Your Account

Go to app.databuddy.cc and create a free account.

Create a Project

After signing in, click “Create Project” and give it a name (e.g., “My Website”).

Copy Your Client ID

Once created, you’ll see your Client ID in the project settings. It looks like this:

3ed1fce1-5a56-4cbc-a917-66864f6d18e3

Copy this—you’ll need it in the next step.

Store your Client ID as an environment variable named NEXT_PUBLIC_DATABUDDY_CLIENT_ID for Next.js projects, or VITE_DATABUDDY_CLIENT_ID for Vite projects.

Step 2: Install the SDK

Install the @databuddy/sdk package in your project:

npm install @databuddy/sdk

The SDK is lightweight (< 10KB gzipped) and has zero dependencies.

Step 3: Add Databuddy to Your App

Add the <Databuddy /> component to your root layout or _app.tsx file:

Next.js App Router
Next.js Pages Router
React (Vite/CRA)

Add to your app/layout.tsx:

app/layout.tsx

import { Databuddy } from '@databuddy/sdk/react';

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

Add to your pages/_app.tsx:

pages/_app.tsx

import { Databuddy } from '@databuddy/sdk/react';
import type { AppProps } from 'next/app';

export default function App({ Component, pageProps }: AppProps) {
  return (
    <>
      <Databuddy
        clientId={process.env.NEXT_PUBLIC_DATABUDDY_CLIENT_ID!}
        trackWebVitals
        trackErrors
      />
      <Component {...pageProps} />
    </>
  );
}

Add to your main.tsx or App.tsx:

src/App.tsx

import { Databuddy } from '@databuddy/sdk/react';

function App() {
  return (
    <>
      <Databuddy
        clientId={import.meta.env.VITE_DATABUDDY_CLIENT_ID}
        trackWebVitals
        trackErrors
      />
      {/* Your app components */}
    </>
  );
}

export default App;

Make sure to add your Client ID to your .env.local file:

.env.local

NEXT_PUBLIC_DATABUDDY_CLIENT_ID=your-client-id-here

Never commit your Client ID to version control in plain text.

Step 4: Start Your Development Server

Run your development server:

npm run dev

Databuddy will automatically start tracking:

Page views
Navigation between pages
Web Vitals (FCP, LCP, CLS, INP, TTFB)
JavaScript errors
Session duration
Bounce rate

Step 5: View Your Analytics

Open Your Website

Navigate around your website to generate some analytics data.

Go to Your Dashboard

Open app.databuddy.cc and select your project.

See Your Data

You should see your page views, sessions, and other metrics appearing in real-time!

It may take a few seconds for data to appear. If you don’t see anything after 30 seconds, check your browser’s console for errors and verify your Client ID is correct.

Step 6: Track Custom Events

Now that basic tracking is working, let’s track a custom event:

components/SignupButton.tsx

'use client';

function SignupButton() {
  const handleSignup = () => {
    // Track the signup event
    window.databuddy.track('signup_clicked', {
      button_location: 'hero',
      plan: 'free'
    });
    
    // Your signup logic...
  };

  return (
    <button onClick={handleSignup}>
      Sign Up Free
    </button>
  );
}

Or use the declarative approach with data-track attributes:

components/SignupButton.tsx

function SignupButton() {
  return (
    <button
      data-track="signup_clicked"
      data-button-location="hero"
      data-plan="free"
      onClick={handleSignup}
    >
      Sign Up Free
    </button>
  );
}

With trackAttributes enabled, any element with a data-track attribute will automatically send an event when clicked. The data-* attributes become event properties.

Configuration Options

Here are the most commonly used configuration options:

<Databuddy
  clientId="your-client-id"
  
  // Performance tracking
  trackWebVitals={true}        // Track FCP, LCP, CLS, INP, TTFB
  trackPerformance={true}       // Track load time, DOM ready
  trackErrors={true}            // Track JavaScript errors
  
  // Engagement tracking
  trackScrollDepth={true}       // Track how far users scroll
  trackOutgoingLinks={true}     // Track clicks on external links
  trackInteractions={true}      // Track user interactions
  trackAttributes={true}        // Enable data-track attributes
  
  // Privacy & optimization
  samplingRate={1.0}            // Sample 100% of traffic (0.5 = 50%)
  enableBatching={true}         // Batch events for efficiency
  batchSize={20}                // Send every 20 events
  
  // Development
  disabled={process.env.NODE_ENV === 'development'}
  debug={process.env.NODE_ENV === 'development'}
/>

For a complete list of options, see the Installation Guide.

Advanced Usage

Set Global Properties

Attach properties to all future events (useful for user traits):

useEffect(() => {
  if (user) {
    window.databuddy.setGlobalProperties({
      plan: user.plan,
      role: user.role,
      company_size: user.company?.size
    });
  }
}, [user]);

Manual Page Views

Databuddy tracks page views automatically, but you can trigger them manually:

window.databuddy.screenView({
  screen_name: 'Settings',
  previous_screen: 'Dashboard'
});

Flush Events

Force send all queued events immediately (useful before navigation to external sites):

const handleExternalLink = () => {
  window.databuddy.flush();
  window.location.href = 'https://external-site.com';
};

Reset Session

Clear all tracking data (useful after logout):

const handleLogout = () => {
  window.databuddy.clear();
  // Your logout logic...
};

TypeScript Support

The SDK is fully typed with TypeScript. Use the global types:

// Access the tracker with full autocomplete
if (typeof window !== 'undefined' && window.databuddy) {
  window.databuddy.track('button_clicked', {
    button_text: 'Get Started',
    location: 'hero'
  });
}

// Or use the shorthand
window.db?.track('event_name', { ... });

Troubleshooting

No data appearing in dashboard

Check these common issues:

Verify your Client ID is correct
Check browser console for errors
Make sure you’re not blocking the script with ad blockers
Verify disabled prop is not set to true
Wait 30-60 seconds for data to appear

Debug mode:

<Databuddy debug={true} ... />

This will log all events to the console.

Events not being tracked

For custom events:

Make sure window.databuddy is defined before calling .track()
Check that event properties don’t contain functions or circular references
Verify events appear in browser console with debug={true}

For attribute tracking:

Make sure trackAttributes={true} is enabled
Verify element has data-track attribute
Check that element is clickable

Script not loading

Common causes:

Ad blockers or privacy extensions blocking the script
CSP (Content Security Policy) blocking external scripts
Network issues or CDN unavailable

Solutions:

Whitelist cdn.databuddy.cc and basket.databuddy.cc in your CSP
Check Network tab in browser dev tools
Try disabling browser extensions temporarily

TypeScript errors

If you see TypeScript errors:

Make sure you’re importing from the correct path:

import { Databuddy } from '@databuddy/sdk/react';

Check that window.databuddy exists before using:
```
window.databuddy?.track('event_name');
```

Add type assertions if needed:

(window as any).databuddy.track('event');

Next Steps

Now that you have Databuddy tracking your website, explore these advanced features:

Installation Guide

Detailed setup for Vue, vanilla JS, and custom configurations.

Custom Events

Learn best practices for tracking custom events and user actions.

Privacy Controls

Configure privacy settings, opt-out mechanisms, and GDPR compliance.

API Reference

Explore the full SDK API and all available methods.

Example Projects

Check out these example projects to see Databuddy in action:

Join our Discord community to get help, share feedback, and connect with other Databuddy users!

Get Started

Core Concepts

SDK Integration

Tracking

Features

Privacy & Compliance

Self-Hosting

Guides

Quickstart Guide

Quickstart Guide

Step 1: Create Your Account

Step 2: Install the SDK

Step 3: Add Databuddy to Your App

Step 4: Start Your Development Server

Step 5: View Your Analytics

Step 6: Track Custom Events

Configuration Options

Advanced Usage

Set Global Properties

Manual Page Views

Flush Events

Reset Session

TypeScript Support

Troubleshooting

Next Steps

Installation Guide

Custom Events

Privacy Controls

API Reference

Example Projects

Build docs developers (and LLMs) love

Get Started

Core Concepts

SDK Integration

Tracking

Features

Privacy & Compliance

Self-Hosting

Guides

​Quickstart Guide

​Step 1: Create Your Account

​Step 2: Install the SDK

​Step 3: Add Databuddy to Your App

​Step 4: Start Your Development Server

​Step 5: View Your Analytics

​Step 6: Track Custom Events

​Configuration Options

​Advanced Usage

​Set Global Properties

​Manual Page Views

​Flush Events

​Reset Session

​TypeScript Support

​Troubleshooting

​Next Steps

Installation Guide

Custom Events

Privacy Controls

API Reference

​Example Projects

Build docs developers (and LLMs) love

Quickstart Guide

Step 1: Create Your Account

Step 2: Install the SDK

Step 3: Add Databuddy to Your App

Step 4: Start Your Development Server

Step 5: View Your Analytics

Step 6: Track Custom Events

Configuration Options

Advanced Usage

Set Global Properties

Manual Page Views

Flush Events

Reset Session

TypeScript Support

Troubleshooting

Next Steps

Example Projects