Custom Events

Human Behavior 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. Use these to track:

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

Usage

All you need to do is call customEvent() with your event name and properties.

await tracker.customEvent('button_clicked', {
  buttonName: 'signup_button',
  page: 'homepage'
});

Note: Make sure you have already initialized the tracker before attempting to use it. Following a framework guide or installing it via the CDN should walk you through this. To retrieve the tracker instance, view your framework's guide.

The current session and user is automatically associated with the event.

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'
});

Properties & Options

customEvent(eventName, properties) parameters:

Parameter	Type	Description
`eventName`	string	Name of the event (required).
`properties`	object	Event data (optional but recommended).