Configuration

Complete reference for all Databuddy SDK configuration options

Overview

This page documents all configuration options available across the Databuddy SDK. Options are applicable to browser (JavaScript, React, Vue) and Node.js SDKs unless otherwise noted.

Core Options

clientId

clientId · string

Your Databuddy project client ID. Get this from your dashboard.

Browser SDK only. For Node.js, use apiKey instead.

Auto-detected from NEXT_PUBLIC_DATABUDDY_CLIENT_ID environment variable if not provided.

<Databuddy clientId="3ed1fce1-5a56-4cbc-a917-66864f6d18e3" />

apiKey

apiKey · string · required

Your API key for authentication. Node.js SDK only.

Format: dbdy_xxx

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

apiUrl

apiUrl · string · default: "https://basket.databuddy.cc"

Custom API endpoint for event ingestion.

<Databuddy apiUrl="https://custom.example.com" />

scriptUrl

scriptUrl · string · default: "https://cdn.databuddy.cc/databuddy.js"

Custom script URL for the browser bundle. Browser SDK only.

<Databuddy scriptUrl="https://cdn.example.com/databuddy.js" />

disabled

disabled · boolean · default: false

Disable all tracking. No events will be sent.

<Databuddy disabled={!userConsent} />

debug

debug · boolean · default: false

Enable debug logging to console.

<Databuddy debug={process.env.NODE_ENV === 'development'} />

Tracking Features

trackWebVitals

trackWebVitals · boolean · default: false

Track Core Web Vitals metrics: LCP, FID, CLS, TTFB, FCP.

<Databuddy trackWebVitals />

trackErrors

trackErrors · boolean · default: false

Track JavaScript errors automatically.

<Databuddy trackErrors />

trackScrollDepth

trackScrollDepth · boolean · default: false

Track scroll depth percentage at 25%, 50%, 75%, 100%.

<Databuddy trackScrollDepth />

trackOutgoingLinks

trackOutgoingLinks · boolean · default: false

Track clicks on external links.

<Databuddy trackOutgoingLinks />

trackInteractions

trackInteractions · boolean · default: false

Track user interactions (clicks, form submissions).

<Databuddy trackInteractions />

trackAttributes

trackAttributes · boolean · default: false

Enable declarative tracking via data-track attributes.

<Databuddy trackAttributes />

<button data-track="cta_clicked" data-location="hero">
  Get Started
</button>

trackHashChanges

trackHashChanges · boolean · default: false

Track hash changes in the URL (e.g., #section).

<Databuddy trackHashChanges />

trackPerformance

trackPerformance · boolean · default: true

Track page performance metrics.

<Databuddy trackPerformance={false} />

Batching & Performance

enableBatching

enableBatching · boolean · default: true

Enable event batching to reduce network requests.

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

batchSize

batchSize · number · default: 10

Number of events to batch before sending.

Min: 1, Max: 50 (browser), 100 (Node.js)

<Databuddy batchSize={20} />

batchTimeout

batchTimeout · number · default: 2000

Time in milliseconds before auto-flushing batched events.

Min: 100, Max: 30000

<Databuddy batchTimeout={5000} />

samplingRate

samplingRate · number

Fraction of sessions to track (0.0 to 1.0).

Example: 0.5 = track 50% of sessions

<Databuddy samplingRate={0.5} />

Retry Configuration

enableRetries

enableRetries · boolean · default: false

Enable automatic retries for failed requests.

<Databuddy enableRetries />

maxRetries

maxRetries · number · default: 3

Maximum number of retry attempts.

Only used if enableRetries is true.

<Databuddy enableRetries maxRetries={5} />

initialRetryDelay

initialRetryDelay · number · default: 500

Initial delay in milliseconds before first retry. Uses exponential backoff.

Only used if enableRetries is true.

<Databuddy enableRetries initialRetryDelay={1000} />

Privacy & Filtering

ignoreBotDetection

ignoreBotDetection · boolean · default: false

Disable bot detection and track all visitors including bots.

<Databuddy ignoreBotDetection />

skipPatterns

skipPatterns · string[] · default: []

Array of glob patterns to skip tracking on matching paths.

<Databuddy skipPatterns={['/admin/**', '/internal/**']} />

maskPatterns

maskPatterns · string[] · default: []

Array of glob patterns to mask sensitive paths.

Wildcards are replaced with asterisks in tracked URLs.

<Databuddy maskPatterns={['/users/*', '/accounts/*/settings']} />

/users/12345 becomes /users/*

filter

filter · (event: any) => boolean

Function to conditionally skip events. Return false to skip.

Browser SDK only. Must be set via window.databuddyConfig before script loads.

window.databuddyConfig = {
  filter: (event) => {
    // Skip admin pages
    return !event.path?.includes('/admin');
  }
};

Node.js Specific

websiteId

websiteId · string

Default website ID to scope events to. Node.js SDK only.

Can be overridden per event.

const analytics = new Databuddy({
  apiKey: process.env.DATABUDDY_API_KEY!,
  websiteId: 'website-uuid'
});

namespace

namespace · string

Default namespace for logical grouping. Node.js SDK only.

Examples: 'billing', 'auth', 'api'

const analytics = new Databuddy({
  apiKey: process.env.DATABUDDY_API_KEY!,
  namespace: 'billing'
});

source

source · string

Default source identifier for events. Node.js SDK only.

Examples: 'backend', 'webhook', 'cron'

const analytics = new Databuddy({
  apiKey: process.env.DATABUDDY_API_KEY!,
  source: 'api_server'
});

maxQueueSize

maxQueueSize · number · default: 1000

Maximum number of events to queue before dropping. Node.js SDK only.

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

middleware

middleware · Middleware[] · default: []

Array of middleware functions to transform or filter events. Node.js SDK only.

Middleware runs before deduplication and batching.

import type { Middleware } from '@databuddy/sdk/node';

const enrichMiddleware: Middleware = (event) => {
  return {
    ...event,
    properties: {
      ...event.properties,
      serverTime: Date.now()
    }
  };
};

const analytics = new Databuddy({
  apiKey: process.env.DATABUDDY_API_KEY!,
  middleware: [enrichMiddleware]
});

enableDeduplication

enableDeduplication · boolean · default: true

Enable event deduplication based on eventId. Node.js SDK only.

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

maxDeduplicationCacheSize

maxDeduplicationCacheSize · number · default: 10000

Maximum deduplication cache size. Node.js SDK only.

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

logger

logger · Logger

Custom logger instance. Node.js SDK only.

import type { Logger } from '@databuddy/sdk/node';
import pino from 'pino';

const pinoLogger = pino();

const customLogger: Logger = {
  debug: (msg, meta) => pinoLogger.debug(meta, msg),
  info: (msg, meta) => pinoLogger.info(meta, msg),
  warn: (msg, meta) => pinoLogger.warn(meta, msg),
  error: (msg, meta) => pinoLogger.error(meta, msg),
};

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

Advanced Options

sdk

sdk · string · default: "web"

SDK name for analytics identification.

Only override for custom integrations.

<Databuddy sdk="custom" />

sdkVersion

sdkVersion · string

SDK version (defaults to package version).

Only override for custom builds.

<Databuddy sdkVersion="2.0.0-custom" />

usePixel

usePixel · boolean · default: false

Use pixel tracking (1x1 image) instead of script.

Browser SDK only. Useful for email tracking or no-JS environments.

<Databuddy usePixel />

clientSecret

clientSecret · string

Client secret for server-side operations.

Not required for browser usage. Never expose in client-side code.

Environment Variables

Browser SDK

Variable	Description	Example
NEXT_PUBLIC_DATABUDDY_CLIENT_ID	Auto-detected client ID	3ed1fce1-5a56-4cbc-a917-66864f6d18e3

Node.js SDK

Variable	Description	Example
DATABUDDY_API_KEY	API key	dbdy_xxx
DATABUDDY_WEBSITE_ID	Default website ID	website-uuid

Configuration Examples

Production Browser Setup

<Databuddy
  // Auto-detected from NEXT_PUBLIC_DATABUDDY_CLIENT_ID
  trackWebVitals
  trackErrors
  trackScrollDepth
  trackOutgoingLinks
  enableBatching
  batchSize={20}
  samplingRate={1.0}
  skipPatterns={['/admin/**']}
  maskPatterns={['/users/*']}
/>

Development Browser Setup

<Databuddy
  clientId="dev-client-id"
  debug
  samplingRate={1.0}
  trackWebVitals
/>

Node.js Production Setup

const analytics = new Databuddy({
  apiKey: process.env.DATABUDDY_API_KEY!,
  websiteId: process.env.DATABUDDY_WEBSITE_ID,
  namespace: 'api',
  source: 'backend',
  enableBatching: true,
  batchSize: 50,
  batchTimeout: 5000,
  enableDeduplication: true,
});

Node.js Serverless Setup

const analytics = new Databuddy({
  apiKey: process.env.DATABUDDY_API_KEY!,
  enableBatching: false, // Disable batching for serverless
  debug: process.env.NODE_ENV !== 'production',
});

Next Steps

JavaScript SDK

Vanilla JavaScript usage guide

React SDK

React hooks and components

Vue SDK

Vue 3 composables and plugins

Node.js SDK

Server-side event tracking