HTML / Vanilla JS

Install HumanBehavior in bundled HTML or a static page, including wizard detection, npm entry, and CDN global names.

The HTML guide is for browser pages without a detected JS framework. The wizard path assumes a bundled HTML/JS project; the published SDK also exposes browser bundle metadata for CDN use.

Wizard detection

The wizard's HTML config is the broadest fallback and runs last. It matches when:

Signal	Details
`index.html`	Root HTML file exists
`public/index.html`	Public HTML fallback
`src/index.html`	Source HTML fallback
`<script` in those files	Script-bearing HTML is considered a browser app

This is only reached after Next, Nuxt, Vue, Remix, Svelte, Angular, Astro, Gatsby, and React fail detection.

Supported install shapes

Shape	Status
Bundled HTML/JS with npm package	Shipped wizard reference path
Static HTML using published unpkg/jsdelivr bundle	Package metadata exposes bundle; install manually
Backend-only project with no browser HTML	Not a shipped wizard target
HTML file with no package manager/build and no place to persist env vars	Wizard support is limited; manual install may be required

Package install for bundled HTML

pnpm add humanbehavior-js

Environment variables for Vite-bundled HTML

VITE_HUMANBEHAVIOR_API_KEY=your-api-key
VITE_HUMANBEHAVIOR_INGESTION_URL=https://ingest.humanbehavior.co

The wizard reference project uses Vite-style import.meta.env, so it uses VITE_ public env vars.

Bundled init in `src/main.js`

import { HumanBehaviorTracker } from "humanbehavior-js";

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

Reference src/main.js from HTML as your bundler expects:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Your app</title>
  </head>
  <body>
    <main id="app"></main>
    <script type="module" src="/src/main.js"></script>
  </body>
</html>

CDN/manual static install

The published humanbehavior-js package declares unpkg and jsdelivr browser bundle entries and the browser entry exposes:

Global	Meaning
`window.HumanBehaviorTracker`	Tracker class
`window.humanbehavior.init(apiKey, ingestionUrl?, options?)`	Convenience init function

Manual CDN example:

<script src="https://unpkg.com/humanbehavior-js@latest/packages/browser/dist/index.min.js"></script>
<script>
  window.humanbehavior.init("YOUR_API_KEY", undefined, {
    redactionStrategy: { mode: "visibility-first" },
  });
</script>

If you override ingestion with the CDN convenience function, the second positional argument is ingestionUrl:

<script>
  window.humanbehavior.init(
    "YOUR_API_KEY",
    "https://ingest.humanbehavior.co",
    { release: "1.2.3" }
  );
</script>

For npm imports, prefer HumanBehaviorTracker.init(apiKey, options) as shown in the SDK reference. The CDN init helper is a browser-bundle convenience.

Where to put it

Site type	Recommended placement
Vite HTML	`src/main.js` imported by `index.html`
Multi-page static site with shared template	Shared layout/footer script
One-off static page	Before `</body>` after the SDK bundle
Server-rendered templates	Shared base template that every page includes

Initialize once per browser page load. Do not paste the snippet in every partial that can render multiple times.

Privacy

HTML pages often include forms. Configure redaction before sending traffic:

HumanBehaviorTracker.init(apiKey, {
  redactionStrategy: {
    mode: "privacy-first",
    unredactFields: ["[data-hb-visible]"],
  },
});

For CDN:

<script>
  window.humanbehavior.init("YOUR_API_KEY", undefined, {
    redactionStrategy: {
      mode: "privacy-first",
      unredactFields: ["[data-hb-visible]"],
    },
  });
</script>

Common pitfalls

Pitfall	Symptom	Fix
Using `import` in a non-module script	Browser syntax error	Use `type="module"` or CDN global
Missing `VITE_` env prefix in bundled project	`apiKey` undefined	Rename env var and restart bundler
Hardcoding key in a committed HTML file	Key leak in git	Prefer build-time env or server template injection
Loading CDN bundle after calling init	`humanbehavior` undefined	Put SDK script first
Expecting wizard to configure unbundled static hosting perfectly	Early reject or needs-attention	Use manual CDN install

Wizard config summary

Wizard field	Value
Integration	`html`
Package name	Empty; `usesPackageJson` is false for detection
Env vars	`VITE_HUMANBEHAVIOR_API_KEY`, `VITE_HUMANBEHAVIOR_INGESTION_URL`
Detection	`index.html`, `public/index.html`, `src/index.html`
Reference files	`index.html`, `src/main.js`

Verify

Open the actual hosted page in a browser.
Confirm the SDK script or module loads without console errors.
Confirm /api/ingestion/events and /heartbeat return 2xx (init is not required).
Click and navigate.
Open Replays.

Full guide: Verify data is flowing.

HTML / Vanilla JS

On this page