Back to Details

databuddy

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Databuddy

Databuddy

Databuddy is a privacy-first analytics platform. This skill covers both the SDK (
@databuddy/sdk
) and the REST API.
Databuddy是一款隐私优先的分析平台。本技能涵盖SDK（
@databuddy/sdk
）和REST API的使用方法。

External Documentation

外部文档

For the most up-to-date documentation, fetch: https://databuddy.cc/llms.txt
如需获取最新文档，请访问：https://databuddy.cc/llms.txt

When to Use This Skill

何时使用本技能

Use this skill when:
  • Setting up analytics in React/Next.js/Vue applications
  • Implementing server-side tracking in Node.js
  • Adding feature flags to an application
  • Tracking custom events, errors, or Web Vitals
  • Integrating LLM observability with Vercel AI SDK
  • Querying analytics data via the REST API
  • Building custom dashboards or reports
在以下场景中使用本技能：
  • 在React/Next.js/Vue应用中设置分析功能
  • 在Node.js中实现服务端追踪
  • 为应用添加功能标志
  • 追踪自定义事件、错误或Web Vitals
  • 集成LLM可观测性与Vercel AI SDK
  • 通过REST API查询分析数据
  • 构建自定义仪表盘或报告

SDK Entry Points

SDK入口点

Import PathEnvironmentDescription
@databuddy/sdk
Browser (Core)Core tracking utilities and types
@databuddy/sdk/react
React/Next.jsReact component and hooks
@databuddy/sdk/node
Node.js/ServerServer-side tracking with batching
@databuddy/sdk/vue
Vue.jsVue plugin and composables
@databuddy/sdk/ai/vercel
AI/LLMVercel AI SDK middleware for LLM analytics
导入路径运行环境描述
@databuddy/sdk
浏览器（核心）核心追踪工具与类型定义
@databuddy/sdk/react
React/Next.jsReact组件与钩子
@databuddy/sdk/node
Node.js/服务端支持批量处理的服务端追踪
@databuddy/sdk/vue
Vue.jsVue插件与组合式函数
@databuddy/sdk/ai/vercel
AI/LLM用于LLM分析的Vercel AI SDK中间件

Quick Start

快速开始

React/Next.js

React/Next.js

tsx
import { Databuddy } from "@databuddy/sdk/react";

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <Databuddy
          clientId={process.env.NEXT_PUBLIC_DATABUDDY_CLIENT_ID}
          trackWebVitals
          trackErrors
          trackPerformance
        />
      </body>
    </html>
  );
}
tsx
import { Databuddy } from "@databuddy/sdk/react";

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <Databuddy
          clientId={process.env.NEXT_PUBLIC_DATABUDDY_CLIENT_ID}
          trackWebVitals
          trackErrors
          trackPerformance
        />
      </body>
    </html>
  );
}

Node.js Server-Side

Node.js服务端

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

const client = new Databuddy({
  clientId: process.env.DATABUDDY_CLIENT_ID,
  enableBatching: true,
});

await client.track({
  name: "api_call",
  properties: { endpoint: "/users", method: "GET" },
});

// Important: flush before process exit in serverless
await client.flush();
typescript
import { Databuddy } from "@databuddy/sdk/node";

const client = new Databuddy({
  clientId: process.env.DATABUDDY_CLIENT_ID,
  enableBatching: true,
});

await client.track({
  name: "api_call",
  properties: { endpoint: "/users", method: "GET" },
});

// 重要提示：在无服务器环境中，进程退出前需调用flush
await client.flush();

Feature Flags

功能标志

tsx
import { FlagsProvider, useFlag, useFeature } from "@databuddy/sdk/react";

// Wrap your app
<FlagsProvider clientId="..." user={{ userId: "123" }}>
  <App />
</FlagsProvider>

// In components
function MyComponent() {
  const { on, loading } = useFeature("dark-mode");
  if (loading) return <Skeleton />;
  return on ? <DarkTheme /> : <LightTheme />;
}
tsx
import { FlagsProvider, useFlag, useFeature } from "@databuddy/sdk/react";

// 包裹你的应用
<FlagsProvider clientId="..." user={{ userId: "123" }}>
  <App />
</FlagsProvider>

// 在组件中使用
function MyComponent() {
  const { on, loading } = useFeature("dark-mode");
  if (loading) return <Skeleton />;
  return on ? <DarkTheme /> : <LightTheme />;
}

LLM Analytics

LLM分析

typescript
import { databuddyLLM } from "@databuddy/sdk/ai/vercel";
import { openai } from "@ai-sdk/openai";

const { track } = databuddyLLM({
  apiKey: process.env.DATABUDDY_API_KEY,
});

const model = track(openai("gpt-4o"));
// All LLM calls are now automatically tracked
typescript
import { databuddyLLM } from "@databuddy/sdk/ai/vercel";
import { openai } from "@ai-sdk/openai";

const { track } = databuddyLLM({
  apiKey: process.env.DATABUDDY_API_KEY,
});

const model = track(openai("gpt-4o"));
// 所有LLM调用现在会被自动追踪

Key Configuration Options

关键配置选项

OptionTypeDefaultDescription
clientId
string
Auto-detectProject client ID
disabled
boolean
false
Disable all tracking
trackWebVitals
boolean
false
Track Web Vitals metrics
trackErrors
boolean
false
Track JavaScript errors
trackPerformance
boolean
true
Track performance metrics
enableBatching
boolean
true
Enable event batching
samplingRate
number
1.0
Sampling rate (0.0-1.0)
skipPatterns
string[]
—Glob patterns to skip tracking
选项类型默认值描述
clientId
string
自动检测项目客户端ID
disabled
boolean
false
禁用所有追踪功能
trackWebVitals
boolean
false
追踪Web Vitals指标
trackErrors
boolean
false
追踪JavaScript错误
trackPerformance
boolean
true
追踪性能指标
enableBatching
boolean
true
启用事件批量处理
samplingRate
number
1.0
采样率（0.0-1.0）
skipPatterns
string[]
—跳过追踪的Glob模式

Common Patterns

常见模式

Disable in Development

开发环境中禁用

tsx
<Databuddy
  disabled={process.env.NODE_ENV === "development"}
  clientId="..."
/>
tsx
<Databuddy
  disabled={process.env.NODE_ENV === "development"}
  clientId="..."
/>

Skip Sensitive Paths

跳过敏感路径

tsx
<Databuddy
  clientId="..."
  skipPatterns={["/admin/**", "/internal/**"]}
  maskPatterns={["/users/*", "/orders/*"]}
/>
tsx
<Databuddy
  clientId="..."
  skipPatterns={["/admin/**", "/internal/**"]}
  maskPatterns={["/users/*", "/orders/*"]}
/>

Custom Event Tracking

自定义事件追踪

typescript
// Browser
import { track } from "@databuddy/sdk/react";

track("purchase", {
  product_id: "sku-123",
  amount: 99.99,
  currency: "USD",
});

// Node.js
await client.track({
  name: "subscription_renewed",
  properties: { plan: "pro", amount: 29.99 },
});
typescript
// 浏览器环境
import { track } from "@databuddy/sdk/react";

track("purchase", {
  product_id: "sku-123",
  amount: 99.99,
  currency: "USD",
});

// Node.js环境
await client.track({
  name: "subscription_renewed",
  properties: { plan: "pro", amount: 29.99 },
});

Global Properties

全局属性设置

typescript
// Browser
window.databuddy?.setGlobalProperties({
  plan: "enterprise",
  abVariant: "checkout-v2",
});

// Node.js
client.setGlobalProperties({
  environment: "production",
  version: "1.0.0",
});
typescript
// 浏览器环境
window.databuddy?.setGlobalProperties({
  plan: "enterprise",
  abVariant: "checkout-v2",
});

// Node.js环境
client.setGlobalProperties({
  environment: "production",
  version: "1.0.0",
});

REST API

REST API

Base URLs

基础URL

ServiceURLPurpose
Analytics API
https://api.databuddy.cc/v1
Query analytics data
Event Tracking
https://basket.databuddy.cc
Send custom events
服务URL用途
分析API
https://api.databuddy.cc/v1
查询分析数据
事件追踪
https://basket.databuddy.cc
发送自定义事件

Authentication

认证方式

Use API key in the 
x-api-key
header:
bash
curl -H "x-api-key: dbdy_your_api_key" \
  https://api.databuddy.cc/v1/query/websites
Get API keys from: Dashboard → Organization Settings → API Keys
在
x-api-key
请求头中使用API密钥：
bash
curl -H "x-api-key: dbdy_your_api_key" \
  https://api.databuddy.cc/v1/query/websites
从以下路径获取API密钥：仪表盘 → 组织设置 → API密钥

Query Analytics Data

查询分析数据

bash
curl -X POST -H "x-api-key: dbdy_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": ["summary", "pages"],
    "preset": "last_30d"
  }' \
  "https://api.databuddy.cc/v1/query?website_id=web_123"
Available Query Types:
TypeDescription
summary
Overall website metrics and KPIs
pages
Page views and performance by URL
traffic
Traffic sources and referrers
browser_name
Browser usage breakdown
device_types
Device category breakdown
countries
Visitors by country
errors
JavaScript errors
performance
Web vitals and load times
custom_events
Custom event data
Date Presets: 
today
, 
yesterday
, 
last_7d
, 
last_30d
, 
last_90d
, 
this_month
, 
last_month
bash
curl -X POST -H "x-api-key: dbdy_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": ["summary", "pages"],
    "preset": "last_30d"
  }' \
  "https://api.databuddy.cc/v1/query?website_id=web_123"
可用查询类型：
类型描述
summary
网站整体指标与关键绩效指标（KPI）
pages
按URL统计的页面浏览量与性能数据
traffic
流量来源与引荐网站
browser_name
浏览器使用情况细分
device_types
设备类别细分
countries
访客所在国家/地区
errors
JavaScript错误信息
performance
Web Vitals与加载时间
custom_events
自定义事件数据
日期预设： 
today
、
yesterday
、
last_7d
、
last_30d
、
last_90d
、
this_month
、
last_month

Send Events via API

通过API发送事件

bash
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "type": "custom",
    "name": "purchase",
    "properties": {
      "value": 99.99,
      "currency": "USD"
    }
  }' \
  "https://basket.databuddy.cc/?client_id=web_123"
bash
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "type": "custom",
    "name": "purchase",
    "properties": {
      "value": 99.99,
      "currency": "USD"
    }
  }' \
  "https://basket.databuddy.cc/?client_id=web_123"

Batch Events

批量发送事件

bash
curl -X POST \
  -H "Content-Type: application/json" \
  -d '[
    {"type": "custom", "name": "event1", "properties": {...}},
    {"type": "custom", "name": "event2", "properties": {...}}
  ]' \
  "https://basket.databuddy.cc/batch?client_id=web_123"
bash
curl -X POST \
  -H "Content-Type: application/json" \
  -d '[
    {"type": "custom", "name": "event1", "properties": {...}},
    {"type": "custom", "name": "event2", "properties": {...}}
  ]' \
  "https://basket.databuddy.cc/batch?client_id=web_123"

Detailed Documentation

详细文档

For detailed documentation on specific topics, see:
  • Core SDK - Browser tracking utilities and types
  • React Integration - React/Next.js component and hooks
  • Node.js Integration - Server-side tracking with batching
  • Feature Flags - Feature flags for all platforms
  • AI/LLM Tracking - Vercel AI SDK integration
  • REST API Reference - Full REST API documentation
如需特定主题的详细文档，请查看：
  • 核心SDK - 浏览器追踪工具与类型定义
  • React集成 - React/Next.js组件与钩子
  • Node.js集成 - 支持批量处理的服务端追踪
  • 功能标志 - 全平台功能标志使用方法
  • AI/LLM追踪 - Vercel AI SDK集成
  • REST API参考 - 完整REST API文档