@databuddy/sdk

v2.4.20

Published

a month ago

Official Databuddy Analytics SDK

0High
0Medium
0Low

izadoesdev

analytics tracking databuddy sdk react vue

Databuddy SDK

The easiest, privacy-first way to add analytics to your web app.

✨ 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
🛡️ 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!}
        trackPerformance
        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);
}

🚩 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"
});

🛠️ Browser Configuration Options

All options are type-safe and documented in DatabuddyConfig:

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

💡 FAQ

Q: Is Databuddy privacy-friendly?
A: Yes! All analytics are anonymized by default. No cookies, no fingerprinting, no PII.

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.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme