Manual install

Install humanbehavior-js by hand: package managers, init rules, Next leaf initializer, React provider, CDN, env vars, and verification.

When to install manually

The CLI wizard is unavailable or failed.
You want full control over file placement.
You are following a framework guide line-by-line.

Hard rules (read before pasting code)

Package name: humanbehavior-js (runtime). Not @humanbehavior/wizard (that is only the installer CLI).
Init signature: HumanBehaviorTracker.init(apiKey, options?) — configuration goes inside options.
Never call init from a React Server Component / server-only file.
Never hardcode the API key in source you will commit.
On Next.js App Router, prefer a leaf client initializer that returns null over wrapping the entire tree with HumanBehaviorProvider (avoids hydration useId mismatches).
Do not invent an endpoint prop on the provider — use options.ingestionUrl.

1) Install the package

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

CDN alternative (no bundler):

<script src="https://unpkg.com/humanbehavior-js@latest"></script>

2) Set environment variables

Create .env.local (Next) or your framework’s env file:

NEXT_PUBLIC_HUMANBEHAVIOR_API_KEY=your-key-here
# optional:
NEXT_PUBLIC_HUMANBEHAVIOR_INGESTION_URL=http://localhost:8000

Vite example:

VITE_HUMANBEHAVIOR_API_KEY=your-key-here
VITE_HUMANBEHAVIOR_INGESTION_URL=http://localhost:8000

Restart the dev server after changing env files.

3) Initialize in the browser

Next.js App Router (recommended)

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, {
      ingestionUrl: process.env.NEXT_PUBLIC_HUMANBEHAVIOR_INGESTION_URL,
      redactionStrategy: { mode: "visibility-first" as const },
      // release: process.env.NEXT_PUBLIC_APP_VERSION,
      // environment: process.env.NODE_ENV,
    });
  }, []);
  return null;
}

app/layout.tsx — mount inside <body>:

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

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

React SPA / Vite (provider OK)

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

export function HBProvider({ children }: { children: React.ReactNode }) {
  return (
    <HumanBehaviorProvider
      apiKey={import.meta.env.VITE_HUMANBEHAVIOR_API_KEY}
      options={{
        ingestionUrl: import.meta.env.VITE_HUMANBEHAVIOR_INGESTION_URL,
        redactionStrategy: { mode: "visibility-first" as const },
      }}
    >
      {children}
    </HumanBehaviorProvider>
  );
}

Wrap once at the client root.

Vue / other non-React

In the client entry (main.ts):

import { HumanBehaviorTracker } from "humanbehavior-js";

HumanBehaviorTracker.init(import.meta.env.VITE_HUMANBEHAVIOR_API_KEY, {
  ingestionUrl: import.meta.env.VITE_HUMANBEHAVIOR_INGESTION_URL,
});

Plain HTML / CDN

<script src="https://unpkg.com/humanbehavior-js@latest"></script>
<script>
  HumanBehaviorTracker.init("YOUR_API_KEY");
  // alias: window.humanbehavior.init("YOUR_API_KEY", undefined, { /* options */ });
</script>

4) Framework-specific file placement

See the full guides (each repeats env + init with framework conventions):

5) Optional but recommended init options

Option	Why set it
`redactionStrategy`	Mask sensitive UI in replays
`release`	Powers Releases and issue grouping by version
`environment`	Filter Issues by `production` / `staging`
`ingestionUrl`	Local stacks or reverse proxy

Full table: Init reference.

await tracker.identifyUser({ email: "ada@example.com", plan: "pro" });

Details: Identify users.

7) Custom events for business moments

tracker.customEvent("signed_up", { plan: "pro" });

Details: Custom events.

8) Verify

Follow Verify data is flowing. If empty, use I installed but see no data.

Manual install

On this page