databuddy-integration

---
name: databuddy-integration
description: Help users integrate Databuddy into their own products. Use when the user wants to install or use Databuddy's SDK, React or Vue component, tracker helpers, Node SDK, server-side feature flags, REST API, event tracking endpoint, or LLM observability package.
---

# Databuddy Integration

Use this skill for people adopting Databuddy in their own app or backend. Optimize for the public integration surface, not the internal monorepo.

## Start By Choosing The Surface

- Browser analytics in React or Next.js: `@databuddy/sdk/react`
- Browser analytics in Vue: `@databuddy/sdk/vue`
- Browser analytics in plain HTML or vanilla JS: CDN script `https://cdn.databuddy.cc/databuddy.js`
- Tracker helpers for custom events in the browser: `@databuddy/sdk`
- Server-side event tracking: `@databuddy/sdk/node`
- Server-side feature flags: `createServerFlagsManager` from `@databuddy/sdk/node`
- LLM observability: `@databuddy/ai`
- Analytics querying or event ingestion over HTTP: Databuddy REST/API endpoints

Read [public-surfaces.md](./references/public-surfaces.md) when you need framework-specific routing, env vars, or endpoint details.
Read [event-design.md](./references/event-design.md) when the user asks what custom events to add, which properties are useful, how to keep events actionable, or how to avoid noisy/high-cardinality tracking.

## Workflow

1. Identify whether the user is integrating Databuddy in the browser, on the server, via REST API, or for LLM observability.
2. Prefer the highest-level supported API:
   - React/Vue component before custom script wiring
   - Node SDK before hand-rolled HTTP calls
   - `@databuddy/ai` before custom `/llm` instrumentation
3. Ask for or infer the minimum required credentials:
   - `clientId` for browser tracking and flags
   - `DATABUDDY_API_KEY` for server-side tracking, API access, and LLM observability
4. Give copy-pasteable setup with the correct env vars and endpoint defaults.
5. Include verification steps so the user can confirm events or API responses are working.

## Core Public Defaults

- Browser/event ingestion base URL: `https://basket.databuddy.cc`
- LLM tracking endpoint: `https://basket.databuddy.cc/llm`
- Query API base URL: `https://api.databuddy.cc/v1`
- Feature flag API base URL: `https://api.databuddy.cc`
- Tracker script URL: `https://cdn.databuddy.cc/databuddy.js`

## Credentials

- Browser SDKs usually need a `clientId`
- React SDK can auto-detect `NEXT_PUBLIC_DATABUDDY_CLIENT_ID`
- Vue examples commonly use `VITE_DATABUDDY_CLIENT_ID`
- Server SDKs and REST APIs use `DATABUDDY_API_KEY`
- Server-side website scoping may also use `DATABUDDY_WEBSITE_ID` or a per-event `websiteId`

## Decision Rules

### React / Next.js

- Use `@databuddy/sdk/react`
- Put `<Databuddy />` near the app root
- Use tracker helpers from `@databuddy/sdk` for custom events

### Vue

- Use `@databuddy/sdk/vue`
- Translate props to kebab-case in templates

### Vanilla JS

- Use the CDN script when the app does not need a package install
- Configure behavior with `data-*` attributes

### Server / Backend

- Use `@databuddy/sdk/node`
- Prefer `apiKey` auth
- Call `flush()` before exit in serverless or short-lived runtimes

### Feature Flags

- Client-side flags in React use the SDK's flags helpers
- Server-side flag evaluation uses `createServerFlagsManager` from `@databuddy/sdk/node` with `clientId` (commonly `DATABUDDY_CLIENT_ID`)
- Flags are fetched from the main API host under `/public/v1/flags` (default base `https://api.databuddy.cc`), not from basket
- Feature flags need a website `clientId`, not API key-only auth

### REST API

- Auth: `x-api-key: dbdy_...` (preferred), or `Authorization: Bearer dbdy_...`
- Query analytics from `https://api.databuddy.cc/v1`
- Send events to `https://basket.databuddy.cc`

### LLM Observability

- Use `@databuddy/ai` for OpenAI, Anthropic, or Vercel AI SDK integrations
- Use `DATABUDDY_API_KEY`
- Only fall back to raw transport logic when the user needs a custom pipeline

## Event Design Rules

- Track user intent, value moments, and operational outcomes, not every click by default
- Prefer a small number of stable event names with useful low-cardinality properties
- Use `snake_case` for event names and property keys
- Do not track PII or secrets in event properties
- Avoid high-cardinality raw values unless they are essential for a specific workflow
- If the user asks what to instrument, propose a minimal event taxonomy first instead of dumping many events into the app

## Verification

- Browser SDK:
  - verify the Databuddy script loads
  - verify network requests reach `basket.databuddy.cc`
  - verify the correct `clientId` is configured
- Node SDK:
  - send one test event
  - call `flush()` if batching is enabled
  - confirm no auth or queue errors are logged
- REST API:
  - start with a simple authenticated query such as listing websites
  - then move to scoped analytics queries
- Feature flags:
  - wait for initialization before first read
  - test with a known flag key and user context

## Response Style

- Default to practical integration guidance and working examples
- Avoid internal monorepo details unless the user is debugging Databuddy itself
- If the user says "API", determine whether they mean:
  - analytics query API
  - event ingestion endpoint
  - feature flags API
  - LLM observability endpoint