# @thisbefine/analytics SDK
> Lightweight analytics, error tracking, and logging for indie SaaS.
## Quick Start
```bash
npm install @thisbefine/analytics
```
```tsx
// Next.js: app/layout.tsx
import { Analytics } from "@thisbefine/analytics/next";
export default function RootLayout({ children }) {
return (
{children}
);
}
```
## Core Methods
```typescript
import { analytics } from "@thisbefine/analytics";
// Track events
analytics.track("button_clicked", { buttonId: "signup" });
// Identify users (call on login/signup)
analytics.identify("user_123", { email: "user@example.com", name: "Jane" });
// Group users into accounts/teams (B2B)
analytics.group("account_456", { name: "Acme Inc", plan: "pro" });
// Track page views (automatic in Next.js)
analytics.page("Dashboard");
// Reset on logout (CRITICAL - prevents data leakage)
analytics.reset();
```
## Error Tracking
```typescript
// Catch and report errors
analytics.captureException(error, { context: "checkout" });
// Report without Error object
analytics.captureMessage("Payment failed", "error", { orderId: "123" });
// Leave breadcrumb trail
analytics.addBreadcrumb({ type: "click", message: "Clicked checkout" });
```
## Logging
```typescript
// Structured logs: debug | info | warn | error | fatal
analytics.log("User exported data", "info", { format: "csv", rows: 1000 });
```
## React Hooks
```typescript
import { useTrack, useIdentify, useReset, useCaptureException } from "@thisbefine/analytics/next";
const track = useTrack("feature_used");
const identify = useIdentify();
const reset = useReset();
const captureException = useCaptureException();
// Use in event handlers
onClick={() => track({ feature: "export" })}
```
## Lifecycle Events
```typescript
import { useSignup, useLogin, useLogout, useSubscriptionStarted } from "@thisbefine/analytics/next";
const signup = useSignup();
signup({ source: "landing_page" });
```
## Bug Report Widget
```tsx
import { BugReportFAB } from "@thisbefine/analytics/next";
```
## Configuration
```tsx
```
## Privacy
```typescript
analytics.optOut(); // Stop tracking (persists)
analytics.optIn(); // Resume tracking
analytics.isOptedOut(); // Check status
```
## Key Points
- API keys start with `tif_`
- Call `reset()` on logout to prevent data leakage
- Call `identify()` early to link events to users
- Events are batched (20 events or 10s interval)
- Respects Do Not Track by default
- ~4KB gzipped total
## Full Documentation
See llms-full.txt for complete API reference, types, and patterns.