HumanBehavior SDK automatically tracks common user interactions like button clicks, link clicks, and form submissions. For specific business actions or advanced analytics, you can track custom events to capture exactly what matters to your application.

​
Quick Start

​
Step 1: Get the Tracker Instance

Important: Even if you initialize the tracker globally (like in a React provider), you still need to get the tracker instance in each component where you want to track events. React/Next.js: 
import { useHumanBehavior } from 'humanbehavior-js/react';

function MyComponent() {
  const tracker = useHumanBehavior(); // ← Always get the instance
  // Your component code...
}
Vue: 
<script>
export default {
  mounted() {
    const tracker = this.$humanBehavior; // ← Always get the instance
    // Your component code...
  }
}
</script>
Vanilla JavaScript: 
const tracker = HumanBehaviorTracker.init('your-api-key');

​
Step 2: Track Your First Event

// Simple event tracking
await tracker.customEvent('button_clicked', {
  buttonName: 'signup_button',
  page: 'homepage'
});
That’s it! Your custom event is now being tracked. 🎉

​
Understanding Tracker Instances

​
Global vs Component-Level Access

When you set up HumanBehavior in your app (like with a React provider), you’re creating a global tracker instance. However, to use it in your components, you still need to get the tracker instance in each component: 
// ✅ Correct: Get tracker instance in each component
function ProductPage() {
  const tracker = useHumanBehavior(); // ← Get the instance
  
  const handleAddToCart = async () => {
    await tracker.customEvent('product_added_to_cart', { productId: '123' });
  };
  
  return <button onClick={handleAddToCart}>Add to Cart</button>;
}

function CheckoutPage() {
  const tracker = useHumanBehavior(); // ← Get the instance again
  
  const handlePurchase = async () => {
    await tracker.customEvent('purchase_completed', { total: 99.99 });
  };
  
  return <button onClick={handlePurchase}>Complete Purchase</button>;
}

// ❌ Incorrect: Don't try to access tracker globally
function ProductPage() {
  // This won't work - tracker is not available here
  const handleAddToCart = async () => {
    await tracker.customEvent('product_added_to_cart', { productId: '123' });
  };
  
  return <button onClick={handleAddToCart}>Add to Cart</button>;
}

​
Why This Matters

  • Provider setup creates the global tracker instance
  • Component access requires getting the instance via hooks/properties
  • Each component needs its own reference to the tracker
  • Same session - all components share the same underlying session

​
Vanilla JavaScript vs Framework Usage

Vanilla JavaScript (Singleton Pattern): 
// ✅ Initialize once - creates a global singleton
const tracker = HumanBehaviorTracker.init('your-api-key');

// ✅ Access the same instance anywhere in your code
function handleButtonClick() {
  tracker.customEvent('button_clicked', { button: 'cta' });
}

function handleFormSubmit() {
  tracker.customEvent('form_submitted', { form: 'contact' });
}
Framework Usage (Provider Pattern): 
// ✅ Provider creates the instance
<HumanBehaviorProvider apiKey="your-api-key">
  <App />
</HumanBehaviorProvider>

// ✅ Each component gets its own reference
function ComponentA() {
  const tracker = useHumanBehavior(); // Gets the instance
  // Use tracker...
}

function ComponentB() {
  const tracker = useHumanBehavior(); // Gets the same instance
  // Use tracker...
}
Key Difference: In vanilla JS, you can call HumanBehaviorTracker.init() multiple times and get the same instance. In frameworks, you use hooks/properties to access the instance created by the provider.

​
When to Use Custom Events

Custom events are perfect for tracking business-specific actions that automatic tracking doesn’t cover:
  • E-commerce events - Purchase completion, cart additions, checkout steps
  • Feature usage - Tool usage, feature adoption, advanced actions
  • Business milestones - Account upgrades, goal completion, achievements
  • Error tracking - Custom error states or user-reported issues

​
Framework-Specific Examples

​
React/Next.js Example

ContactForm.jsx
import { useHumanBehavior } from 'humanbehavior-js/react';
import { useState } from 'react';

function ContactForm() {
  const tracker = useHumanBehavior();
  const [formData, setFormData] = useState({ name: '', email: '', message: '' });

  const handleSubmit = async (e) => {
    e.preventDefault();
    
    try {
      // Your form submission logic
      await submitForm(formData);
      
      // Track successful form submission
      await tracker.customEvent('contact_form_submitted', {
        formType: 'contact',
        hasName: !!formData.name,
        hasEmail: !!formData.email,
        messageLength: formData.message.length
      });
      
      alert('Message sent successfully!');
    } catch (error) {
      // Track form error
      await tracker.customEvent('contact_form_error', {
        errorType: error.message,
        formType: 'contact'
      });
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      {/* Your form fields */}
      <button type="submit">Send Message</button>
    </form>
  );
}

​
Vue Example

ProductCard.vue
<template>
  <div class="product-card">
    <h3>{{ product.name }}</h3>
    <p>${{ product.price }}</p>
    <button @click="handleAddToCart">Add to Cart</button>
  </div>
</template>

<script>
export default {
  props: ['product'],
  methods: {
    async handleAddToCart() {
      try {
        // Your add to cart logic
        await this.addToCart(this.product.id);
        
        // Track the event
        await this.$humanBehavior.customEvent('product_added_to_cart', {
          productId: this.product.id,
          productName: this.product.name,
          price: this.product.price,
          category: this.product.category
        });
        
        this.$toast.success('Added to cart!');
      } catch (error) {
        await this.$humanBehavior.customEvent('add_to_cart_error', {
          productId: this.product.id,
          error: error.message
        });
      }
    }
  }
}
</script>

​
Vanilla JavaScript Example

index.html
<!DOCTYPE html>
<html>
<head>
  <script src="https://unpkg.com/humanbehavior-js@latest"></script>
</head>
<body>
  <button id="cta-button">Get Started</button>
  
  <script>
    const tracker = HumanBehaviorTracker.init('your-api-key');
    
    document.getElementById('cta-button').addEventListener('click', async () => {
      // Track the button click
      await tracker.customEvent('cta_button_clicked', {
        buttonText: 'Get Started',
        page: 'landing_page',
        section: 'hero'
      });
      
      // Your button logic here
      window.location.href = '/signup';
    });
  </script>
</body>
</html>

​
Event Naming Best Practices

Choose descriptive, consistent event names that clearly indicate the action: 
// ✅ Good: Clear action with context
await tracker.customEvent('video_started', { videoId: 'intro-tutorial' });
await tracker.customEvent('search_performed', { query: 'user documentation' });
await tracker.customEvent('feature_enabled', { feature: 'dark_mode' });

// ❌ Avoid: Vague or inconsistent naming
await tracker.customEvent('click', { button: 'video' });
await tracker.customEvent('search', { q: 'docs' });

​
Common Event Patterns

​
E-commerce Events

// Product interactions
await tracker.customEvent('product_viewed', {
  productId: '123',
  productName: 'Blue T-Shirt',
  category: 'clothing',
  price: 29.99
});

await tracker.customEvent('product_added_to_cart', {
  productId: '123',
  quantity: 2,
  totalValue: 59.98
});

// Checkout process
await tracker.customEvent('checkout_started', {
  cartValue: 99.99,
  itemCount: 3
});

await tracker.customEvent('purchase_completed', {
  orderId: 'order-456',
  total: 99.99,
  currency: 'USD',
  paymentMethod: 'credit_card'
});

​
User Engagement Events

// Feature usage
await tracker.customEvent('feature_used', {
  feature: 'advanced_search',
  searchFilters: ['category', 'price_range']
});

// Content interactions
await tracker.customEvent('article_read', {
  articleId: 'getting-started',
  readTime: 180, // seconds
  completionRate: 0.85
});

// User milestones
await tracker.customEvent('account_upgraded', {
  fromPlan: 'free',
  toPlan: 'premium',
  reason: 'team_collaboration'
});

​
Error Tracking

// Form validation errors
await tracker.customEvent('form_validation_error', {
  formName: 'signup',
  fieldName: 'email',
  errorType: 'invalid_format'
});

// API errors
await tracker.customEvent('api_error', {
  endpoint: '/api/products',
  errorCode: 500,
  userAction: 'product_search'
});

​
Advanced Properties

​
Complex Data Structures

// Nested objects
await tracker.customEvent('order_completed', {
  orderId: 'order-789',
  customer: {
    id: 'user-123',
    tier: 'premium',
    location: 'US'
  },
  items: [
    { id: 'item-1', name: 'Product A', price: 29.99 },
    { id: 'item-2', name: 'Product B', price: 19.99 }
  ],
  shipping: {
    method: 'express',
    cost: 9.99
  },
  total: 59.97
});

​
Performance Tracking

// Feature performance
await tracker.customEvent('feature_performance', {
  feature: 'image_upload',
  loadTime: 1500, // milliseconds
  fileSize: 2048000, // bytes
  success: true
});

​
Error Handling

Always wrap custom events in try-catch blocks to prevent errors from breaking your app: 
const handleButtonClick = async () => {
  try {
    // Your business logic
    await processAction();
    
    // Track success
    await tracker.customEvent('action_completed', {
      action: 'button_click',
      success: true
    });
  } catch (error) {
    // Track error
    await tracker.customEvent('action_failed', {
      action: 'button_click',
      error: error.message
    });
    
    // Handle error gracefully
    console.error('Action failed:', error);
  }
};

​
Analytics & Segmentation

  • Custom events appear in your analytics dashboard for conversion tracking
  • Use event properties for advanced segmentation and filtering
  • Combine with user identification for personalized analytics
  • Events are automatically associated with the current session and user

​
Properties & Options

Property/OptionTypeDescription
eventNamestringDescriptive name for the custom event (e.g., ‘purchase_completed’).
propertiesobjectEvent data with any key-value pairs (strings, numbers, booleans, arrays, objects).
customEvent()functionTrack a custom event with name and properties.
automaticTrackingbooleanButton, link, and form events are tracked automatically (enabled by default).
customEvent(eventName, properties) parameters:
ParameterTypeDescription
eventNamestringName of the event (required).
propertiesobjectEvent data (optional but recommended).
Common properties fields:
FieldTypeDescription
orderIdstringOrder, transaction, or reference ID.
totalnumberPurchase total, price, or value.
currencystringCurrency code (e.g., ‘USD’, ‘EUR’).
categorystringProduct category or event type.
userIdstringAssociated user ID (if different from session).
featurestringFeature or tool name.
durationnumberTime spent or duration in milliseconds.
Custom events are powerful for conversion tracking and business analytics. Combine them with user identification for comprehensive user journey analysis.