Databuddy SDK

Hosted product analytics for your web app: pageviews, custom events, funnels, feature flags, and errors, without cookies.

✨ Features

• 📊 Automatic page/screen view tracking
• ⚡ Performance, Web Vitals, and error tracking
• 🧑‍💻 Custom event tracking
• 🧩 Drop-in React/Next.js and Vue components
• 🖥️ Node.js server-side event tracking
• 🚩 Client and server-side feature flags
• 🔌 MCP server analytics: tool calls, clients, latency, and errors
• 🛡️ Privacy-first: anonymized by default, sampling, batching, and more
• 🛠️ Type-safe config and autocompletion
• 📋 Observability: logging, error tracking, and distributed tracing

🚀 Quickstart

bun add @databuddy/sdk
# or
npm install @databuddy/sdk

Add to your root layout (Next.js/React):

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

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

🖥️ Node.js Events

import { Databuddy } from "@databuddy/sdk/node";

const client = new Databuddy({
  apiKey: process.env.DATABUDDY_API_KEY!,
  websiteId: process.env.DATABUDDY_WEBSITE_ID,
  source: "server"
});

await client.track({
  name: "job_completed",
  eventId: "job-123",
  properties: { queue: "emails" }
});

const result = await client.flush();
if (!result.success) {
  console.error("Failed to flush analytics:", result.error);
}

🔌 MCP Servers

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { trackMcp } from "@databuddy/sdk/mcp";

const server = trackMcp(new McpServer({ name: "my-server", version: "1.0.0" }));

Records each tool call with its client, duration, result size, error code and error message. Needs only DATABUDDY_API_KEY; for a stdio server, set it in the env of the client config that starts the server. Arguments and successful results never leave your server; only the length of the text a tool returns is recorded. Failed calls send their error message, and Databuddy stores up to 512 characters of it, unless you keep error messages private with beforeSend. On serverless platforms, pass your platform's waitUntil: trackMcp(server, { waitUntil }). See the MCP docs.

🚩 Server-Side Flags

import { createServerFlagsManager } from "@databuddy/sdk/node";

const flags = createServerFlagsManager({
  clientId: process.env.DATABUDDY_CLIENT_ID!,
  maxCacheSize: 5000
});

const result = await flags.getFlag("new-dashboard", {
  userId: "user-123",
  organizationId: "org-456"
});

🔁 Migrating from PostHog

Change posthog-js, posthog-js/react, and posthog-node imports to @databuddy/sdk/posthog, @databuddy/sdk/posthog/react, and @databuddy/sdk/posthog/node. The adapters keep PostHog's method names for events, identify, and feature flags, so existing call sites keep working.

import posthog from "@databuddy/sdk/posthog";

posthog.init(process.env.NEXT_PUBLIC_DATABUDDY_CLIENT_ID!);
posthog.identify(user.id, { plan: user.plan });
posthog.capture("checkout_completed", { total: 49 });

See the migration guide for the server adapter and the PostHog features that map differently.

🛠️ Browser Configuration Options

All options are type-safe and documented in DatabuddyConfig:

| Option | Type | Default | Description | |-----------------------|-----------|--------------|-------------| | clientId | string | — | Required. Your Databuddy Client ID. | | apiUrl | string | https://basket.databuddy.cc | Custom API endpoint. | | scriptUrl | string | SDK-pinned, date-versioned CDN URL | Custom script URL. | | scriptIntegrity | string | SDK-pinned SHA-384 hash | SRI for a custom script URL. | | sdk | string | web | SDK name. Only override for custom builds. | | sdkVersion | string | auto | SDK version. Defaults to package version. | | disabled | boolean | false | Disable all tracking. | | debug | boolean | false | Enable debug logging (SDK-only). | | trackHashChanges | boolean | false | Track hash changes in URL. | | trackAttributes | boolean | false | Track data-* attributes on elements. | | trackOutgoingLinks | boolean | false | Track clicks on outgoing links. | | trackInteractions | boolean | false | Track user interactions. | | trackWebVitals | boolean | false | Track Web Vitals metrics. | | trackErrors | boolean | false | Track JavaScript errors. | | ignoreBotDetection | boolean | false | Ignore bot detection. | | usePixel | boolean | false | Use pixel tracking instead of script. | | samplingRate | number | 1.0 | Sampling rate (0.0–1.0). | | enableRetries | boolean | true | Enable retries for failed requests. | | maxRetries | number | 3 | Max retries. | | initialRetryDelay | number | 500 | Initial retry delay (ms). | | enableBatching | boolean | true | Enable event batching. | | batchSize | number | 10 | Events per batch (1–50). | | batchTimeout | number | 5000 | Batch timeout (ms, 100–30000). | | skipPatterns | string[] | — | Array of glob patterns to skip tracking. | | maskPatterns | string[] | — | Array of glob patterns to mask sensitive paths. | | filter | function | — | Filter function to conditionally skip events. |

💡 FAQ

Q: Is Databuddy privacy-friendly?
A: Yes. The tracker sets no cookies and does no fingerprinting. It keeps a random visitor ID in localStorage, visitor IDs are salted and hashed at ingestion by default, and location is stored at city level. Traits you send with identify(), such as email or name, are personal data and are stored on that website's profiles.

Q: Can I use this in Next.js, Remix, or plain React?
A: Yes! <Databuddy /> works in any React app. For non-React, use the script tag directly.

Q: How do I disable analytics in development?
A: Use the disabled prop: <Databuddy disabled={process.env.NODE_ENV === 'development'} ... />

Q: Where do I find my clientId?
A: In your Databuddy dashboard.

🧑‍💻 Troubleshooting

• Script not loading?
  • Make sure your clientId is correct and the script URL is reachable.
• No events in dashboard?
  • Check your config, especially clientId and network requests in the browser dev tools.
• Type errors?
  • All config options are type-safe. Use your IDE's autocomplete for help.
• SSR/Next.js?
  • The component is safe for SSR/React Server Components. It only injects the script on the client.

📚 Documentation & Support

• Databuddy Docs
• Dashboard
• Contact Support

© Databuddy. All rights reserved.

Pinned browser scripts

Each SDK release embeds date-versioned tracker URLs and SHA-384 integrity hashes. Updating the CDN cannot silently update a pinned SDK installation. Debug and replay scripts are pinned too; a hash mismatch blocks execution with no unversioned fallback. New tracker bytes require a new SDK version, so security fixes require customers to upgrade their SDK.

scriptUrl supports self-hosting; provide scriptIntegrity to verify custom bytes. For a custom recorder use replay: { scriptUrl: "/replay.js", integrity: "sha384-..." }. Custom URLs without integrity retain the existing unverified loading behavior. Plain unversioned script-tag installations are not covered by SDK pinning.