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://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:
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:
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://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:
- 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://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.
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 Reference
Explore all configuration options and advanced features
Dashboard Guide
Learn to navigate your analytics dashboard
SDK Reference
Set up custom events, performance monitoring, and more
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.