Skip to main content

​
Package Manager Installation

Install the SDK using your preferred package manager: 
npm install @databuddy/sdk

​
Framework-Specific Setup

​
Next.js (App Router)

Add the Databuddy component to your root layout:
app/layout.tsx
import { Databuddy } from '@databuddy/sdk/react';

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Databuddy
          trackWebVitals
          trackErrors
          trackScrollDepth
        />
      </body>
    </html>
  );
}
The clientId is automatically detected from NEXT_PUBLIC_DATABUDDY_CLIENT_ID environment variable.

​
Next.js (Pages Router)

Add to _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 (
    <>
      <Component {...pageProps} />
      <Databuddy
        trackWebVitals
        trackErrors
      />
    </>
  );
}

​
React (Vite / Create React App)

Add to your root component:
src/main.tsx
import { Databuddy } from '@databuddy/sdk/react';
import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import App from './App';

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <App />
    <Databuddy
      clientId="your-client-id"
      trackWebVitals
    />
  </StrictMode>
);

​
Vue 3

Add to your main app file:
src/main.ts
import { createApp } from 'vue';
import { Databuddy } from '@databuddy/sdk/vue';
import App from './App.vue';

const app = createApp(App);

app.component('Databuddy', Databuddy);
app.mount('#app');
Then use in your root component:
App.vue
<template>
  <div id="app">
    <RouterView />
    <Databuddy
      client-id="your-client-id"
      :track-web-vitals="true"
      :track-errors="true"
    />
  </div>
</template>

​
Node.js / Express

For server-side tracking: 
npm install @databuddy/sdk
server.ts
import { Databuddy } from '@databuddy/sdk/node';

const analytics = new Databuddy({
  apiKey: process.env.DATABUDDY_API_KEY!,
  websiteId: process.env.DATABUDDY_WEBSITE_ID,
});

// Track events
await analytics.track({
  name: 'api_request',
  properties: {
    endpoint: '/api/users',
    method: 'POST',
  },
});

// Flush before exit (important for serverless)
await analytics.flush();

​
CDN Installation (Script Tag)

For quick setup without a build step:
index.html
<!DOCTYPE html>
<html>
<head>
  <script
    src="https://cdn.databuddy.cc/databuddy.js"
    data-client-id="your-client-id"
    data-track-web-vitals="true"
    data-track-errors="true"
    async
  ></script>
</head>
<body>
  <h1>My Website</h1>
  
  <script>
    // Track custom events
    window.databuddy.track('page_loaded', {
      timestamp: Date.now()
    });
  </script>
</body>
</html>

​
Script Tag Options

All configuration options can be passed as data-* attributes: 
<script
  src="https://cdn.databuddy.cc/databuddy.js"
  data-client-id="your-client-id"
  data-api-url="https://basket.databuddy.cc"
  data-track-web-vitals="true"
  data-track-errors="true"
  data-track-scroll-depth="true"
  data-track-outgoing-links="true"
  data-sampling-rate="0.5"
  data-debug="true"
  async
></script>

​
Environment Variables

The SDK automatically detects these environment variables:
VariableDescriptionExample
NEXT_PUBLIC_DATABUDDY_CLIENT_IDYour client ID (browser)3ed1fce1-5a56-4cbc-a917-66864f6d18e3
DATABUDDY_API_KEYAPI key for Node.js SDKdbdy_xxx
DATABUDDY_WEBSITE_IDWebsite ID for Node.js SDKwebsite-uuid
For Next.js, prefix browser environment variables with NEXT_PUBLIC_ to expose them to the client.

​
Verification

After installation, verify the SDK is working:

​
Browser Console

Open your browser’s developer console and check: 
// Check if tracker is loaded
window.databuddy !== undefined; // Should be true

// Get tracking IDs
window.databuddy.options;

// Track a test event
window.databuddy.track('test_event', { source: 'console' });

​
Debug Mode

Enable debug mode to see detailed logs: 
<Databuddy debug />
This will log all events to the console before sending them.

​
Troubleshooting

  • Check that clientId is provided or environment variable is set
  • Verify the CDN URL is accessible
  • Check browser console for errors
  • Ensure ad blockers aren’t blocking the script
  • Enable debug mode to see if events are being sent
  • Check network tab for failed requests
  • Verify your client ID is correct
  • Ensure events aren’t being filtered by skipPatterns
  • Ensure you’re using TypeScript 4.5 or later
  • Check that @databuddy/sdk is in your dependencies
  • Restart your TypeScript server
  • Place <Databuddy /> component at the end of your layout/app
  • Ensure you’re not using client-side only code in server components

​
Next Steps

JavaScript Guide

Learn how to use the SDK in vanilla JavaScript

React Guide

Explore React hooks and components

Configuration

See all available configuration options

Node.js Guide

Set up server-side tracking

Build docs developers (and LLMs) love

Get started for freeTalk to us