​
HumanBehaviorProvider

If you are using the Next.js App Router, the HumanBehaviorProvider must be used in a client component because the SDK requires browser APIs and cannot run during server-side rendering. Add “use client” to your provider file or create a separate client component wrapper.
The HumanBehaviorProvider is a React context provider that makes the HumanBehavior tracker available throughout your React component tree.
How to find your Public API Key:
Flow: Project Home → Settings (on sidebar) → Public API Key
Where to find your Public API Key

Example screenshot – your actual API key will be different.

​
Import

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

​
Props

​
apiKey (string, optional)

Your HumanBehavior API key. Required if no client is provided. Example: 
<HumanBehaviorProvider apiKey="your-api-key-here">
  <App />
</HumanBehaviorProvider>

​
client (HumanBehaviorTracker, optional)

An existing tracker instance to use instead of creating a new one. Example: 
import { HumanBehaviorTracker } from 'humanbehavior-js';

const tracker = HumanBehaviorTracker.init('your-api-key');

<HumanBehaviorProvider client={tracker}>
  <App />
</HumanBehaviorProvider>

​
options (object, optional)

Configuration options for the tracker. Properties:
  • redactFields (string[], optional): CSS selectors for fields to redact
The React provider’s options parameter is defined but not yet implemented. For redactFields, you’ll need to configure it after initialization using the tracker methods.
Example: 
<HumanBehaviorProvider 
  apiKey="your-api-key-here"
  options={{
    redactFields: ['input[type="password"]', '#email']
  }}
>
  <App />
</HumanBehaviorProvider>

​
Usage

​
Basic Usage

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

function App() {
  return (
    <HumanBehaviorProvider apiKey="your-api-key-here">
      <YourApp />
    </HumanBehaviorProvider>
  );
}

​
With Direct API Key

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

function App() {
  return (
    <HumanBehaviorProvider 
      apiKey="your-api-key-here"
    >
      <YourApp />
    </HumanBehaviorProvider>
  );
}

​
With Custom Client

import { HumanBehaviorProvider } from 'humanbehavior-js/react';
import { HumanBehaviorTracker } from 'humanbehavior-js';

// Create custom tracker
const tracker = HumanBehaviorTracker.init('your-api-key');

function App() {
  return (
    <HumanBehaviorProvider client={tracker}>
      <YourApp />
    </HumanBehaviorProvider>
  );
}

​
Context Value

The provider creates a React context with the following value: 
{
  humanBehavior: HumanBehaviorTracker | null,
  queueEvent: (event: any) => void
}

​
humanBehavior

The HumanBehavior tracker instance that can be used to call all tracker methods, or null if not yet initialized.

​
queueEvent

Function to queue events before initialization is complete.

​
Error Handling

​
Missing API Key

// Error: Missing API key
<HumanBehaviorProvider>
  <App />
</HumanBehaviorProvider>
// Throws: "An apiKey is required when no client is provided"

​
Invalid Client

// Error: Invalid client
<HumanBehaviorProvider client="invalid">
  <App />
</HumanBehaviorProvider>
// Throws: "Client must be a HumanBehaviorTracker instance"

​
Server-Side Rendering

The provider is fully compatible with SSR: 
// Works in both client and server environments
function App() {
  return (
    <HumanBehaviorProvider apiKey="your-api-key">
      <YourApp />
    </HumanBehaviorProvider>
  );
}

​
Performance

​
Automatic Initialization

The provider automatically initializes the tracker when mounted: 
// Tracker is initialized automatically
<HumanBehaviorProvider apiKey="your-api-key">
  <App />
</HumanBehaviorProvider>

​
Memory Management

The provider automatically cleans up resources when unmounted: 
// Resources are cleaned up automatically
function ConditionalProvider({ show }) {
  if (!show) return null;
  
  return (
    <HumanBehaviorProvider apiKey="your-api-key">
      <App />
    </HumanBehaviorProvider>
  );
}

​
Testing

​
Mock Provider

// test-utils.js
import { HumanBehaviorProvider } from 'humanbehavior-js/react';

const mockTracker = {
  start: jest.fn(),
  stop: jest.fn(),
  customEvent: jest.fn(),
  addUserInfo: jest.fn(),
  setRedactedFields: jest.fn()
};

export function TestProvider({ children }) {
  return (
    <HumanBehaviorProvider client={mockTracker}>
      {children}
    </HumanBehaviorProvider>
  );
}

​
Component Testing

import { render } from '@testing-library/react';
import { TestProvider } from './test-utils';
import MyComponent from './MyComponent';

test('renders with provider', () => {
  render(
    <TestProvider>
      <MyComponent />
    </TestProvider>
  );
  
  // Component renders successfully
});

​
Best Practices

​
Single Provider

Use only one provider at the root of your app: 
// Good: Single provider at root
function App() {
  return (
    <HumanBehaviorProvider apiKey="your-api-key">
      <Header />
      <Main />
      <Footer />
    </HumanBehaviorProvider>
  );
}

// Avoid: Multiple providers
function App() {
  return (
    <HumanBehaviorProvider apiKey="your-api-key">
      <Header />
      <HumanBehaviorProvider apiKey="your-api-key"> {/* Don't do this */}
        <Main />
      </HumanBehaviorProvider>
      <Footer />
    </HumanBehaviorProvider>
  );
}

​
Configuration

Configure the provider with your API key: 
// App.js
function App() {
  return (
    <HumanBehaviorProvider 
      apiKey="your-api-key-here"
    >
      <YourApp />
    </HumanBehaviorProvider>
  );
}

​
Error Boundaries

Wrap your app with error boundaries: 
import { HumanBehaviorProvider } from 'humanbehavior-js/react';

function App() {
  return (
    <ErrorBoundary>
      <HumanBehaviorProvider apiKey="your-api-key">
        <YourApp />
      </HumanBehaviorProvider>
    </ErrorBoundary>
  );
}

​
Troubleshooting

​
Common Issues

// Issue: Provider not found
// Solution: Ensure provider is imported correctly
import { HumanBehaviorProvider } from 'humanbehavior-js/react';

// Issue: API key not working
// Solution: Ensure your API key is valid and properly configured

// Issue: SSR errors
// Solution: Provider handles SSR automatically
// No additional setup needed

​
Debug Mode

function DebugProvider({ children }) {
  return (
    <HumanBehaviorProvider 
      apiKey="your-api-key-here"
    >
      <DebugComponent />
      {children}
    </HumanBehaviorProvider>
  );
}

function DebugComponent() {
  const { humanBehavior } = useHumanBehavior();
  
  useEffect(() => {
    if (humanBehavior) {
      humanBehavior.viewLogs();
    }
  }, [humanBehavior]);
  
  return null;
}
The HumanBehaviorProvider automatically handles initialization and cleanup, making it easy to integrate the SDK into React applications.
Always ensure you have user consent before starting session recording, especially in regions with strict privacy laws.