Manual install

Add humanbehavior-js by hand: the package, the env var, and the one init call, with the rules that keep it working.

Three things have to be true: the package is installed, your API key reaches the browser through an environment variable, and init runs exactly once on the client. Use this after access is unlocked when the wizard cannot write your repo — or when we hand you these steps in Slack.

When you need this

Take the manual path when the wizard is not an option, when you want to choose where the code lives, or when you are following a framework guide line by line.

The rules that break installs

Read these before pasting anything. Nearly every broken manual install is one of these six:

The runtime package is humanbehavior-js. @humanbehavior/wizard is only the installer.
The signature is HumanBehaviorTracker.init(apiKey, options?). Everything except the key goes inside options.
init must never run in a React Server Component or any server-only file. It is a browser API.
Never hardcode the key in committed source.
On the Next.js App Router, use a small client component that returns null rather than wrapping your tree in HumanBehaviorProvider. Wrapping the whole tree causes hydration useId mismatches.
There is no endpoint prop on the provider. The option is options.ingestionUrl.

Install the package

pnpm add humanbehavior-js
# npm install humanbehavior-js
# yarn add humanbehavior-js

Without a bundler, use the CDN browser bundle:

<script src="https://unpkg.com/humanbehavior-js@latest/packages/browser/dist/index.min.js"></script>

Set the environment variable

Client-side frameworks only expose variables with the right prefix. In Next.js, that is .env.local:

NEXT_PUBLIC_HUMANBEHAVIOR_API_KEY=your-key-here

With Vite:

VITE_HUMANBEHAVIOR_API_KEY=your-key-here

Restart the dev server afterwards. The full list of variable names covers the other frameworks.

Call init in the browser

Next.js App Router

Create a leaf initializer:

app/humanbehavior-init.tsx

"use client";

import { useEffect } from "react";
import { HumanBehaviorTracker } from "humanbehavior-js";

export function HumanBehaviorInit() {
  useEffect(() => {
    const apiKey = process.env.NEXT_PUBLIC_HUMANBEHAVIOR_API_KEY;
    if (!apiKey) return;
    HumanBehaviorTracker.init(apiKey, {
      // release: process.env.NEXT_PUBLIC_APP_VERSION,
      // environment: process.env.NODE_ENV,
    });
  }, []);
  return null;
}

Mount it once, inside <body>:

app/layout.tsx

import { HumanBehaviorInit } from "./humanbehavior-init";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <HumanBehaviorInit />
        {children}
      </body>
    </html>
  );
}

React SPA on Vite

A provider is fine here, because there is no server render to mismatch. Wrap once at the client root:

import { HumanBehaviorProvider } from "humanbehavior-js/react";

export function HBProvider({ children }: { children: React.ReactNode }) {
  return (
    <HumanBehaviorProvider apiKey={import.meta.env.VITE_HUMANBEHAVIOR_API_KEY}>
      {children}
    </HumanBehaviorProvider>
  );
}

Vue and other non-React frameworks

Call it from the client entry:

main.ts

import { HumanBehaviorTracker } from "humanbehavior-js";

HumanBehaviorTracker.init(import.meta.env.VITE_HUMANBEHAVIOR_API_KEY);

Plain HTML

<script src="https://unpkg.com/humanbehavior-js@latest/packages/browser/dist/index.min.js"></script>
<script>
  HumanBehaviorTracker.init("YOUR_API_KEY");
</script>

Use HumanBehaviorTracker.init on CDN loads. The UMD helper window.humanbehavior.init only constructs a tracker and does not call start().

For exact file placement in your stack, the framework guides cover Next, React, Vue, Angular, Svelte, Nuxt, Remix, Astro, Gatsby, and HTML.

Options worth setting

init works with nothing but a key. These four are the ones most teams end up wanting:

Option	Why you would set it
`redactionStrategy`	Mask sensitive UI before it leaves the browser
`release`	Tags errors for Issues filters and source-map pairing
`environment`	Lets you filter Issues to production or staging
`ingestionUrl`	Points at a local stack or a reverse proxy

The init reference has the complete set.

What changes in the product

Once init runs in a real browser session, sessions and autocaptured events start arriving within seconds, and Replays gets a row. Nothing else is required for that baseline.

Two additions are worth doing next, and each is one line: identifyUser after login so visitors become people, and customEvent for the business moments autocapture cannot infer.

Verify data is flowing. If nothing shows up, I installed but see no data is the page you want.

Manual install

On this page