Skip to main content

​
Step 1: Installation

npm install humanbehavior-js
# or
yarn add humanbehavior-js

​
Step 2: Environment Variables

Create or add to a .env.production or .env.development file in your project root based on your staging type: 
GATSBY_HUMANBEHAVIOR_API_KEY=your-api-key-here
Security Best Practice: The GATSBY_ prefix is required for Gatsby to expose the environment variable to the client-side code.

​
Step 3: Basic Setup

​
Add the Tracker to Your App

Create or update your gatsby-browser.js file in the root of your project: 
import "./src/styles/global.css"

// Initialize HumanBehavior SDK
import { HumanBehaviorTracker } from 'humanbehavior-js';

export const onClientEntry = () => {
  const apiKey = process.env.GATSBY_HUMANBEHAVIOR_API_KEY;
  if (apiKey) {
    const tracker = HumanBehaviorTracker.init(apiKey);
  } else {
    console.error('HumanBehavior: No API key found');
  }
};
That’s it! The SDK now automatically tracks user interactions, navigation, and console events. Everything past here is optional.

​
Optional: Advanced Features

​
Track Custom Events

You can track custom events from any React component: 
import React from 'react';
import { HumanBehaviorTracker } from 'humanbehavior-js';

function MyComponent() {
  const handleButtonClick = () => {
    const apiKey = process.env.GATSBY_HUMANBEHAVIOR_API_KEY;
    const tracker = HumanBehaviorTracker.init(apiKey);
    
    tracker.customEvent('button_clicked', {
      button: 'cta-button',
      page: window.location.pathname
    });
  };

  return (
    <div>
      <button onClick={handleButtonClick}>Click Me</button>
    </div>
  );
}

export default MyComponent;

​
User Identification

Identify users after authentication: 
import React, { useEffect } from 'react';
import { HumanBehaviorTracker } from 'humanbehavior-js';

function AuthComponent({ user }) {
  useEffect(() => {
    if (user) {
      const apiKey = process.env.GATSBY_HUMANBEHAVIOR_API_KEY;
      const tracker = HumanBehaviorTracker.init(apiKey);
      
      tracker.identifyUser({
        userProperties: {
          email: user.email,
          name: user.name,
          userId: user.id
        }
      });
    }
  }, [user]);

  return (
    <div>
      {/* Your authentication UI */}
    </div>
  );
}

export default AuthComponent;

​
Data Redaction

Configure data redaction for sensitive information in your gatsby-browser.js: 
import { HumanBehaviorTracker } from 'humanbehavior-js';

export const onClientEntry = () => {
  const apiKey = process.env.GATSBY_HUMANBEHAVIOR_API_KEY;
  if (apiKey) {
    const tracker = HumanBehaviorTracker.init(apiKey, {
      redactText: ['password', 'credit-card', 'ssn'],
      redactInputs: ['password', 'credit-card-number'],
      redactAttributes: ['data-sensitive']
    });
    console.log('HumanBehavior SDK initialized for Gatsby');
  }
};

​
Gatsby-Specific Considerations

​
Client-Side Only Execution

The HumanBehavior SDK runs on the client side using Gatsby’s onClientEntry API, which ensures it only loads after the browser environment is ready.

​
Environment Variables

Gatsby requires environment variables to be prefixed with GATSBY_ to be available in client-side code.

​
Performance

The HumanBehavior SDK is lightweight and won’t impact your Gatsby site’s performance. It only loads the tracking code when needed.

​
SSR Compatibility

The SDK is fully compatible with Gatsby’s SSR (Server-Side Rendering) and SSG (Static Site Generation) modes.

​
Build Process

The SDK works seamlessly with Gatsby’s build process and doesn’t interfere with static generation or deployment.

​
Alternative: Using gatsby-ssr.js

If you prefer to initialize the tracker in the SSR phase, you can also use gatsby-ssr.js: 
import { HumanBehaviorTracker } from 'humanbehavior-js';

export const onRenderBody = ({ setHeadComponents }) => {
  const apiKey = process.env.GATSBY_HUMANBEHAVIOR_API_KEY;
  
  if (apiKey) {
    // Add any SSR-specific initialization here
    // Note: The actual tracker initialization should still happen in gatsby-browser.js
  }
};

​
Troubleshooting

​
Common Issues

“API key not found”
  • Ensure your environment variable is prefixed with GATSBY_
  • Check that the .env file is in your project root
  • Restart your development server after adding environment variables
“Tracker not initializing”
  • Verify the API key is correct
  • Check browser console for error messages
  • Ensure gatsby-browser.js is in your project root
“Events not being tracked”
  • Check your network tab for API calls to HumanBehavior
  • Verify the API key has the correct permissions
  • Check browser console for any error messages
“Build errors”
  • Ensure the SDK is only imported in client-side files
  • Check that environment variables are properly configured
  • Verify Gatsby version compatibility

​
Next Steps

Once you’ve completed the setup:
  1. Test the integration by visiting your site and checking the browser console
  2. Verify events are being sent to your HumanBehavior dashboard
  3. Customize tracking by adding custom events where needed
  4. Monitor performance to ensure the SDK isn’t impacting your site
  5. Deploy your Gatsby site with the tracking enabled
For more advanced features, check out our API Reference and Custom Events documentation.