# SDK

URL: /docs/sdk

> One package, one init call, and the options worth knowing about.

`humanbehavior-js` records the session and sends batches to ingestion. Almost
  everything is on by default, so the options below are mostly about turning
  things off, tightening privacy, or stamping releases.

## Entry points

| Import | Use for |
|---|---|
| `humanbehavior-js` | Any framework. Exports `HumanBehaviorTracker`. |
| `humanbehavior-js/react` | React apps. `HumanBehaviorProvider`, `useHumanBehavior`, `useRedaction`, `useUserTracking`, `HumanBehaviorErrorBoundary`. |

```ts
import { HumanBehaviorTracker } from "humanbehavior-js";

const tracker = HumanBehaviorTracker.init(apiKey, {
  environment: "production",
  release: "web@2026.8.28",
});
```

`init` is idempotent: calling it again returns the tracker that already exists
rather than starting a second recorder.

## On by default

Session recording, autocaptured clicks and navigation, console capture, network
error capture, crash capture, Core Web Vitals, and tracing all run without
configuration. Each has an opt-out below.

## Options

**Identity and connection**

| Option | Default | Effect |
|---|---|---|
| `ingestionUrl` | our endpoint | Point at a [reverse proxy](#reverse-proxy) you control |
| `logLevel` | `'error'` | `'none' \| 'error' \| 'warn' \| 'info' \| 'debug'` |
| `minimumDurationMilliseconds` | `5000` | Hold events until the session is this old. `0` sends immediately |
| `maxQueueSize` | `1000` | Cap on queued events before older ones are dropped |

**What gets captured**

| Option | Default | Effect |
|---|---|---|
| `enableAutomaticTracking` | `true` | Autocapture clicks, links, forms, navigation |
| `automaticTrackingOptions` | — | `trackButtons`, `trackLinks`, `trackForms`, `includeText`, `includeClasses` |
| `enableConsoleTracking` | `true` | Capture `console.warn` / `console.error` |
| `enableNetworkTracking` | `true` | Capture failed and slow requests |
| `enableErrorTracking` | `true` | Capture crashes and unhandled rejections |
| `enableWebVitals` | `true` | FCP, LCP, CLS, INP, TTFB |
| `enableTracing` | `true` | Page-load, resource, and custom spans |
| `recordCanvas` | `false` | Record `<canvas>` content |
| `enableAutomaticProperties` | `true` | Detect properties automatically |
| `propertyDenylist` | — | Property names to never send |

**Errors** — see [Errors](/docs/sdk/errors) for how these are used.

| Option | Effect |
|---|---|
| `ignoreErrors` | Drop matching messages client-side (string or RegExp) |
| `denyUrls` / `allowUrls` | Drop, or keep only, errors from matching script URLs |
| `captureThirdPartyResourceErrors` | Report cross-origin resource load failures (default `false`) |
| `captureRequestBodies` | Attach redacted request/response bodies to correlated errors (default `false`) |
| `release`, `environment`, `commitSha`, `dist` | Stamped on every error report |

**Privacy** — see [Masking and PII](/docs/sdk/privacy).

| Option | Effect |
|---|---|
| `redactionStrategy` | `{ mode: 'privacy-first' \| 'visibility-first', unredactFields, redactFields }` |

**redactFields at the top level is deprecated**

  Use `redactionStrategy` instead. The old flat `redactFields` option still
  parses, but it cannot express the visibility-first mode.

## Reverse proxy

Setting `ingestionUrl` to a path on your own domain routes recording through your
infrastructure, which keeps requests first-party and survives blockers that reject
third-party analytics hosts. Your proxy forwards to our ingestion endpoint
unchanged.