Astro

Step 1: Installation

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

Step 2: Basic Setup

Create a HumanBehavior Component

Create a new component file src/components/HumanBehavior.astro:

---
// This component will only run on the client side
---

<script>
  import { HumanBehaviorTracker } from 'humanbehavior-js';
  
  // Get API key from environment variable
  const apiKey = import.meta.env.PUBLIC_HUMANBEHAVIOR_API_KEY;
  
  if (apiKey) {
    const tracker = HumanBehaviorTracker.init(apiKey);
  } else {
    console.error('HumanBehavior: No API key found');
  }
</script>

Add the Component to Your Layout

In your main layout file (usually src/layouts/Layout.astro):

---
export interface Props {
  title: string;
}

const { title } = Astro.props;

import HumanBehavior from '../components/HumanBehavior.astro';
---

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="description" content="Astro description">
    <meta name="viewport" content="width=device-width" />
    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
    <meta name="generator" content={Astro.generator} />
    <title>{title}</title>
  </head>
  <body>
    <slot />
    <HumanBehavior />
  </body>
</html>

<style is:global>
  @import '../styles/global.css';
</style>

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

Step 3: Environment Variables

Create a .env file in your project root:

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

Security Best Practice: The PUBLIC_ prefix is required for Astro to expose the environment variable to the client-side code.

Optional: Advanced Features

Track Custom Events

You can track custom events from any Astro component:

---
// Your component logic here
---

<div>
  <button id="cta-button">Click Me</button>
</div>

<script>
  import { HumanBehaviorTracker } from 'humanbehavior-js';
  
  const apiKey = import.meta.env.PUBLIC_HUMANBEHAVIOR_API_KEY;
  const tracker = HumanBehaviorTracker.init(apiKey);
  
  document.getElementById('cta-button')?.addEventListener('click', () => {
    tracker.customEvent('button_clicked', {
      button: 'cta-button',
      page: window.location.pathname
    });
  });
</script>

User Identification

Identify users after authentication:

---
// In your authentication component
---

<script>
  import { HumanBehaviorTracker } from 'humanbehavior-js';
  
  const apiKey = import.meta.env.PUBLIC_HUMANBEHAVIOR_API_KEY;
  const tracker = HumanBehaviorTracker.init(apiKey);
  
  // After successful login
  function onLoginSuccess(user) {
    tracker.identifyUser({
      userProperties: {
        email: user.email,
        name: user.name,
        userId: user.id
      }
    });
  }
</script>

Data Redaction

Configure data redaction for sensitive information:

---
// In your HumanBehavior component
---

<script>
  import { HumanBehaviorTracker } from 'humanbehavior-js';
  
  const apiKey = import.meta.env.PUBLIC_HUMANBEHAVIOR_API_KEY;
  
  const tracker = HumanBehaviorTracker.init(apiKey, {
    redactionStrategy: { 
      mode: 'visibility-first' as const
    }
  });
</script>

Astro-Specific Considerations

Client-Side Only Execution

Astro components run on the server by default. The Human Behavior must run on the client side, which is why we use the <script> tag in the component.

Environment Variables

Astro requires environment variables to be prefixed with PUBLIC_ to be available in client-side code.

Performance

The HumanBehavior component is lightweight and won't impact your Astro site's performance. It only loads the tracking code when needed.

SSR Compatibility

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

Troubleshooting

Common Issues

"API key not found"

Ensure your environment variable is prefixed with PUBLIC_
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 the HumanBehavior component is included in your layout

"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

Next Steps

Once you've completed the setup:

Test the integration by visiting your site and checking the browser console
Verify events are being sent to your HumanBehavior dashboard
Customize tracking by adding custom events where needed
Monitor performance to ensure the SDK isn't impacting your site

For more advanced features, check out our API Reference and Custom Events documentation.

Astro

On this page