Overview

What humanbehavior-js does in the browser, lifecycle, packages, and the map of every SDK subpage.

Packages

Package / import	Role
`humanbehavior-js`	Main browser package — re-exports core; UMD build available
`humanbehavior-js/core`	`HumanBehaviorTracker`, redaction, API client, error capture, tracing
`humanbehavior-js/react`	`HumanBehaviorProvider`, hooks, `HumanBehaviorErrorBoundary`, `captureNextError`
`@humanbehavior/wizard`	Install wizard + `upload-sourcemaps` CLI

Install (typical):

pnpm add humanbehavior-js
# or: npm install humanbehavior-js

What the SDK does in the browser

On HumanBehaviorTracker.init(apiKey, options?) the tracker:

Creates a singleton (window.__humanBehaviorGlobalTracker) and starts immediately (start() is called from init)
Generates sessionId + anonymous endUserId locally (cookie / localStorage) — no bootstrap HTTP call is required
Records replay chunks with rrweb → POST /api/ingestion/events (batched; idle flush ~3s). Users are created on first event
Sends heartbeats (~30s) so idle tabs stay in the dashboard live set → POST /api/ingestion/heartbeat
Ends presence on unload → POST /api/ingestion/session-end
Autocaptures UX signals ($pageview, $click, $form_submitted, $rageclick, $deadclick, …) when automatic tracking is on
Optionally captures console warn/error, network failures, crashes, Core Web Vitals, and performance spans

Default ingestion host when ingestionUrl is omitted: https://ingest.humanbehavior.co.

Minimal install

import { HumanBehaviorTracker } from "humanbehavior-js";

const tracker = HumanBehaviorTracker.init(
  process.env.NEXT_PUBLIC_HUMANBEHAVIOR_API_KEY!,
  {
    ingestionUrl: process.env.NEXT_PUBLIC_HUMANBEHAVIOR_INGESTION_URL,
    redactionStrategy: { mode: "visibility-first" },
    release: process.env.NEXT_PUBLIC_APP_VERSION,
    environment: "production",
  },
);

init returns the tracker instance. Calling init again in the same page returns the existing singleton.

Session timing (shipped constants)

Constant	Value	Meaning
Session idle timeout	30 minutes	SDK rotates `sessionId` after inactivity (aligned with ingestion)
Session max length	24 hours	Hard cap before rotation
Minimum duration gate	5 seconds (default)	Events held until the session is “real”; set `minimumDurationMilliseconds: 0` to send immediately
Idle flush	3 seconds	Normal replay/event batch cadence
Live flush	150 ms	When the server signals an active dashboard live viewer

Subpages

Page	Topic
Init reference	Full options table + signature rules
Automatic tracking	Built-in event names and toggles
Custom events	`customEvent` + batching
Identify	`identifyUser` / `logout`
Replay privacy	Redaction modes
Error monitoring	Crashes → Issues
Source maps	`upload-sourcemaps`
Web vitals & tracing	`$web_vitals` + spans
Console & network	Logs / network errors

Public methods (core)

Method	Purpose
`start()` / `stop()`	Start/stop recording (start is already called by `init`)
`customEvent(name, props?)`	Product / analytics events
`identifyUser(props \| { userProperties })`	Attach traits; upsert via `/user`
`logout()`	Clear identity + rotate session
`captureException(error, options?)`	Manual handled error
`startSpan` / `startInactiveSpan`	Custom performance spans
`setUnredactedFields` / `getUnredactedFields`	Runtime redaction helpers
`getSessionId()`	Current session id
`setUserProperty(key, value)`	Set a single user trait locally
`getUserAttributes()`	Read merged user traits

Verify

Verify data is flowing

Common failures

Symptom	Likely cause
No data	Init never ran in the browser / wrong API key / SSR-only
Hydration warnings	Provider wrapped the entire App Router tree
Blocked requests	Ad blocker — use a reverse proxy
Minified stacks	Missing source maps
Short sessions missing events	Default 5s minimum duration gate

Overview

On this page