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
- Go to app.databuddy.cc
- Sign up for a free account
- Create your first project with your verified domain
- 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://cdn.databuddy.cc/databuddy.js"
data-client-id="your-client-id-here"
data-track-screen-views="true"
data-track-performance="true"
async
></script>
Configure Tracking
Add the <Databuddy />
component to your root layout:
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:
NEXT_PUBLIC_DATABUDDY_CLIENT_ID=your-client-id-here
Add the script to your HTML before the closing </body>
tag:
<!DOCTYPE html>
<html>
<head>
<title>My Website</title>
</head>
<body>
<!-- Your content -->
<!-- Databuddy Analytics -->
<script
src="https://cdn.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"
async
></script>
</body>
</html>
Verify Installation
Check that analytics are working correctly:
- Visit your website in a new browser tab
- Open your Databuddy dashboard at app.databuddy.cc
- Check Real-time data - you should see yourself as an active visitor
- 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
<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
/>
<script
src="https://cdn.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"
async
></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.
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:
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>
);
}
<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?
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?
- Check your Client ID - Make sure it matches your project
- Verify your domain - Ensure your domain is verified in the dashboard
- Test manually - Try
db.track('test', {})
in your browser console - Check Network tab - Look for requests to
basket.databuddy.cc
- Review environment - Make sure tracking isn't disabled in production
Need help? Join our Discord community or contact support.