Quickstart

The Human Behavior SDK allows you to record user sessions and track behavior analytics in web applications for use with the Human Behavior platform.

Important: By using the HumanBehavior SDK, you agree to comply with our Terms of Service and Privacy Policy.

Show How to get your API Key

How to find your Public API Key:
Flow: Project Home → Integrations → Human Behavior SDK → Kebab Menu → Configuration → Public API Key

Example screenshot – your actual API key will be different.

Option 1: Auto-Installation Wizard (`beta`)

The easiest way to get started is using our auto-installation wizard:

# Navigate to your project directory
cd your-project-directory

# Run the installation wizard
npx humanbehavior-js YOUR_API_KEY

When you run this command, the wizard will:

Ask for your API key (if not provided as an argument)
Let you select your framework from the supported options:
- React
- Next.js
- Vue
- Angular
- Svelte
- Nuxt.js
- Remix
- Astro
- Gatsby
- Vanilla JS/TS
Automatically install and configure the SDK for your project:
- Install the humanbehavior-js package
- Add framework-specific integration code
- Configure environment variables
- Set up proper initialization

Version Compatibility: The wizard works with most versions of each framework and automatically detects:

Next.js: App Router (13+) vs Pages Router (12 and earlier)
Angular: Standalone components (17+) vs NgModule (pre-17)
Svelte: SvelteKit vs regular Svelte
Bundlers: Vite, Webpack, esbuild, rollup
Package Managers: npm, yarn, pnpm

The wizard supports React, Next.js, Vue, Angular, Svelte, Nuxt, Remix, Astro, Gatsby, and vanilla JS/TS projects.

Manual Installation Benefits:

Learn exactly how the SDK integrates with your app
Customize the integration to your needs
Better understand the SDK’s features
Get step-by-step guidance with explanations

Option 2: Manual Setup

If you prefer manual setup or the wizard doesn’t work for your project, follow the steps below.

If you are using a framework such as React, NextJS, or Vite, we recommend using one of our Framework Guides instead of the manual quickstart.

The fastest way to get started is by adding a simple JS snippet at the top of your website.

Security Best Practice: Store your API key in environment variables rather than hardcoding it in your source code. This prevents accidental exposure of your key in version control.

Show example

# .env
HUMANBEHAVIOR_API_KEY=your-api-key-here

// In your code
const tracker = HumanBehaviorTracker.init(process.env.HUMANBEHAVIOR_API_KEY);

Step 1: Install the Tracker

Option 1: CDN

Add this to the top of your file.

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

Option 2: Package Manager

Install using npm, yarn, or your package manager of choice.

npm install humanbehavior-js

Step 2: Add the tracker to your project

<head>
	<!-- your other metadata here -->
	<script>const tracker = HumanBehaviorTracker.init('your-api-key-here');</script>
</head>
<body>
	<!-- your website content here -->
</body>

Simple HTML Example

Here is a simple HTML website using the CDN version:

<!DOCTYPE html>
<html>
  <head>
    <title>My Website</title>
    <link rel="stylesheet" href="style.css">

    <!-- Load the HumanBehavior SDK -->
    <script src="https://unpkg.com/humanbehavior-js@latest"></script>

    <!-- Initialize the tracker -->
    <script>const tracker = HumanBehaviorTracker.init('your-api-key-here');</script>

  </head>
  <body>
    <h1>Welcome to My App</h1>
    <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>
  </body>
</html>

That’s it! The SDK now automatically tracks user interactions, navigation, and console events. Everything past here is optional.

Identify users (Optional)

For the best user tracking experience, identify users client-side after successful authentication:

// In your NextAuth configuration
import { HumanBehaviorTracker } from 'humanbehavior-js';

events: {
  async signIn({ user, account }) {
    // Initialize HumanBehavior tracker
    const tracker = HumanBehaviorTracker.init(process.env.NEXT_PUBLIC_HUMAN_BEHAVIOR_API_KEY);
    
    // Identify user with current endUserId
    await tracker.identifyUser({
      userProperties: {
        email: user.email,
        name: user.name,
        userId: user.id,
        provider: account?.provider
      }
    });
  }
}

Browser Compatibility

The SDK supports all modern browsers:

Browser	Version
Chrome	60+
Firefox	55+
Safari	12+
Edge	79+

Internet Explorer is not supported. The SDK uses modern JavaScript features that are not available in IE.

Best Practice:Always initialize the tracker in the <head> section, before any user interaction can occur. This ensures all events—including those on page load—are captured.

Version: This documentation covers HumanBehavior SDK version 0.4.5

Data Redaction

The SDK includes comprehensive data redaction to protect sensitive information:

Two Redaction Modes

Privacy-First: Everything masked by default, selectively unredact fields
Visibility-First: Everything visible by default, selectively redact fields

Flexible Field Selection

Programmatic: Configure via redactionStrategy options
Markup-Driven: Add data-hb-redact="true" to any input
Runtime Control: Change settings after initialization

Key Features

1:1 Character Masking: Shows asterisks matching input length
All Input Types: Works with text, email, password, number, etc.
Always Protected: Password fields cannot be unredacted
Real-time: Masks data as users type

// Privacy-first example
redactionStrategy: { 
  mode: 'privacy-first' as const, 
  unredactFields: ['#public-comment'] 
}

// Visibility-first example  
redactionStrategy: { 
  mode: 'visibility-first' as const
}

<!-- Mark sensitive fields for redaction -->
<input id="username" data-hb-redact="true">
<input id="ssn" data-hb-redact="true">

Learn more in our Data Redaction guide.

What Happens Next?

Once you’ve completed the setup:

Automatic Session Recording: The SDK automatically captures user interactions using rrweb
Automatic Event Tracking: Button clicks, link clicks, and form submissions are tracked automatically
Session Persistence: Sessions persist across page reloads for 15 minutes
Navigation Tracking: SPA navigation and URL changes are automatically tracked
Console Tracking: Console logs, warnings, and errors are captured
Data Processing: Events are processed and sent to your dashboard
User Identification: Users are identified client-side after successful authentication
Analytics: View session recordings and analytics in your HumanBehavior dashboard

Installation

Documentation Index

​Quickstart

​Option 1: Auto-Installation Wizard (beta)

​Option 2: Manual Setup

​Step 1: Install the Tracker

​Option 1: CDN

​Option 2: Package Manager

​Step 2: Add the tracker to your project

​Simple HTML Example

​Identify users (Optional)

​Browser Compatibility

​Data Redaction

​Two Redaction Modes

​Flexible Field Selection

​Key Features

​What Happens Next?

Quickstart

Option 1: Auto-Installation Wizard (`beta`)

Option 2: Manual Setup

Step 1: Install the Tracker

Option 1: CDN

Option 2: Package Manager

Step 2: Add the tracker to your project

Simple HTML Example

Identify users (Optional)

Browser Compatibility

Data Redaction

Two Redaction Modes

Flexible Field Selection

Key Features

What Happens Next?