Skip to main content
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.

​
Quickstart

​
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:
  1. Ask for your API key (if not provided as an argument)
  2. Let you select your framework from the supported options:
    • React
    • Next.js
    • Vue
    • Angular
    • Svelte
    • Nuxt.js
    • Remix
    • Astro
    • Gatsby
    • Vanilla JS/TS
  3. 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.

​
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:
BrowserVersion
Chrome60+
Firefox55+
Safari12+
Edge79+
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:
  1. Automatic Session Recording: The SDK automatically captures user interactions using rrweb
  2. Automatic Event Tracking: Button clicks, link clicks, and form submissions are tracked automatically
  3. Session Persistence: Sessions persist across page reloads for 15 minutes
  4. Navigation Tracking: SPA navigation and URL changes are automatically tracked
  5. Console Tracking: Console logs, warnings, and errors are captured
  6. Data Processing: Events are processed and sent to your dashboard
  7. User Identification: Users are identified client-side after successful authentication
  8. Analytics: View session recordings and analytics in your HumanBehavior dashboard