databuddy

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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 Path	Environment	Description
`@databuddy/sdk`	Browser (Core)	Core tracking utilities and types
`@databuddy/sdk/react`	React/Next.js	React component and hooks
`@databuddy/sdk/node`	Node.js/Server	Server-side tracking with batching
`@databuddy/sdk/vue`	Vue.js	Vue plugin and composables
`@databuddy/sdk/ai/vercel`	AI/LLM	Vercel AI SDK middleware for LLM analytics

导入路径	运行环境	描述
`@databuddy/sdk`	浏览器（核心）	核心追踪工具与类型定义
`@databuddy/sdk/react`	React/Next.js	React组件与钩子
`@databuddy/sdk/node`	Node.js/服务端	支持批量处理的服务端追踪
`@databuddy/sdk/vue`	Vue.js	Vue插件与组合式函数
`@databuddy/sdk/ai/vercel`	AI/LLM	用于LLM分析的Vercel AI SDK中间件

Quick Start

快速开始

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

关键配置选项

Option	Type	Default	Description
`clientId`	`string`	Auto-detect	Project 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

Base URLs

基础URL

Service	URL	Purpose
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:

Type	Description
`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文档