Install

Get the recorder into your app. One CLI command, or one provider you place yourself.

Two rules decide whether an install works, and they are the same in every framework: the key has to reach the browser, and the recorder has to start in client code.

The wizard does it for you

npx @humanbehavior/wizard@latest

It detects your framework, writes the key into the right env file with the right public prefix, and places the initializer in the right file. If it finishes cleanly, skip to Verify.

Or place it yourself

Install the package:

npm install humanbehavior-js

Then start the recorder once, in client code. Pick your framework:

Wrap your app in the provider, then render <Providers> inside app/layout.tsx. The layout itself stays a Server Component — only the provider is a client component.

"use client";

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

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <HumanBehaviorProvider apiKey={process.env.NEXT_PUBLIC_HUMANBEHAVIOR_API_KEY!}>
      {children}
    </HumanBehaviorProvider>
  );
}

Key variable: NEXT_PUBLIC_HUMANBEHAVIOR_API_KEY.

Wrap the tree once, at the root. The provider starts the recorder on mount, which is why it has to live in client code.

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

createRoot(document.getElementById("root")!).render(
  <HumanBehaviorProvider apiKey={import.meta.env.VITE_HUMANBEHAVIOR_API_KEY}>
    <App />
  </HumanBehaviorProvider>,
);

Key variable: VITE_HUMANBEHAVIOR_API_KEY (Create React App uses REACT_APP_HUMANBEHAVIOR_API_KEY).

Call init from your client entry. In Nuxt that means a client-only plugin — plugins/humanbehavior.client.ts — because the recorder must not run during SSR.

import { HumanBehaviorTracker } from "humanbehavior-js";

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

Key variable: VITE_HUMANBEHAVIOR_API_KEY, or NUXT_PUBLIC_HUMANBEHAVIOR_API_KEY in Nuxt.

Call init from onMount in your root layout, so it only ever runs in the browser.

import { onMount } from "svelte";
import { HumanBehaviorTracker } from "humanbehavior-js";
import { PUBLIC_HUMANBEHAVIOR_API_KEY } from "$env/static/public";

onMount(() => {
  HumanBehaviorTracker.init(PUBLIC_HUMANBEHAVIOR_API_KEY);
});

Key variable: PUBLIC_HUMANBEHAVIOR_API_KEY.

Call init from the browser bootstrap in main.ts.

import { HumanBehaviorTracker } from "humanbehavior-js";

HumanBehaviorTracker.init(process.env.NG_APP_HUMANBEHAVIOR_API_KEY!);

Key variable: NG_APP_HUMANBEHAVIOR_API_KEY.

A module script before </body> is enough — no bundler, no env var.

<script type="module">
  import { HumanBehaviorTracker } from "https://esm.sh/humanbehavior-js";
  HumanBehaviorTracker.init("YOUR_API_KEY");
</script>

Naming the environment variable

Your bundler only exposes variables that carry its own public prefix. Use the one your framework expects, or the key will be undefined at runtime:

Framework	Variable
Next.js	`NEXT_PUBLIC_HUMANBEHAVIOR_API_KEY`
Vite (React, Vue, Svelte)	`VITE_HUMANBEHAVIOR_API_KEY`
Nuxt	`NUXT_PUBLIC_HUMANBEHAVIOR_API_KEY`
Angular	`NG_APP_HUMANBEHAVIOR_API_KEY`
Astro, SvelteKit	`PUBLIC_HUMANBEHAVIOR_API_KEY`
Gatsby	`GATSBY_HUMANBEHAVIOR_API_KEY`
Create React App	`REACT_APP_HUMANBEHAVIOR_API_KEY`

Where to find your key

In the app, open Settings → Environments. Copy an existing key from its row, or name a new one and create it. Separate keys per environment let you rotate one without touching the others.

Environments settings with the API keys list — Settings → Environments. Each key can be copied, revealed, renamed, rotated, or deleted.

Settings → Environments. Each key can be copied, revealed, renamed, rotated, or deleted.

Next: confirm a session actually arrived.