npm package: @productbet/tracker-core
Description: Core behavioral analytics SDK for ProductBet - session recording, event tracking, and user identification
Latest version: 0.1.9

# @productbet/tracker-core

Core behavioral analytics SDK for [ProductBet](https://productbet.io). Handles session recording, event tracking, user identification, and data ingestion.

> Most users should install **[@productbet/tracker-react](https://www.npmjs.com/package/@productbet/tracker-react)** or **[@productbet/tracker-next](https://www.npmjs.com/package/@productbet/tracker-next)** instead, which include this package automatically.

## Install

```bash
npm install @productbet/tracker-core
```

## Usage

```ts
import { ProductBetTracker } from "@productbet/tracker-core";

const tracker = ProductBetTracker.init("pb_live_xxxx", {
  enableSessionRecording: true,
  enableAutoTracking: true,
});

tracker.start();

// Identify a user
tracker.identify("user_123", { plan: "pro", company: "Acme" });

// Track a custom event
tracker.track("feature_used", { feature: "export", format: "csv" });

// Stop tracking
tracker.stop();
```

## Configuration

All options are optional.

| Option                   | Type                  | Default                            | Description                                  |
| ------------------------ | --------------------- | ---------------------------------- | -------------------------------------------- |
| `ingestionUrl`           | `string`              | `"https://productbet.io/tracking"` | Ingestion endpoint URL                       |
| `enableSessionRecording` | `boolean`             | `false`                            | Enable rrweb session replay                  |
| `enableAutoTracking`     | `boolean`             | `true`                             | Auto-track clicks, forms, navigation, scroll |
| `enableConsoleTracking`  | `boolean`             | `true`                             | Capture console errors and warnings          |
| `enableNetworkTracking`  | `boolean`             | `true`                             | Capture failed network requests              |
| `recordCanvas`           | `boolean`             | `false`                            | Include canvas elements in recordings        |
| `maxQueueSize`           | `number`              | `1000`                             | Max events queued before flush               |
| `flushIntervalMs`        | `number`              | `3000`                             | How often events are sent (ms)               |
| `sessionTimeoutMs`       | `number`              | `1800000`                          | Session timeout (30 min default)             |
| `debug`                  | `boolean`             | `false`                            | Enable debug logging                         |
| `redaction`              | `RedactionOptions`    | `{ mode: "privacy-first" }`        | PII redaction settings                       |
| `autoTrackingOptions`    | `AutoTrackingOptions` | See below                          | Fine-tune auto-tracking                      |

### Auto-tracking options

| Option             | Type      | Default |
| ------------------ | --------- | ------- |
| `trackClicks`      | `boolean` | `true`  |
| `trackForms`       | `boolean` | `true`  |
| `trackNavigation`  | `boolean` | `true`  |
| `trackScrollDepth` | `boolean` | `true`  |
| `detectRageClicks` | `boolean` | `true`  |
| `detectDeadClicks` | `boolean` | `true`  |
| `includeText`      | `boolean` | `true`  |
| `includeClasses`   | `boolean` | `true`  |

### Redaction

By default, the SDK runs in `privacy-first` mode where all text input values are redacted. Use `unredactFields` to allowlist specific fields:

```ts
ProductBetTracker.init("pb_live_xxxx", {
  redaction: {
    mode: "privacy-first",
    unredactFields: ["search", "email"],
  },
});
```

Set `mode: "visibility-first"` to capture all field values by default.

## License

MIT