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. You do not need to register or pre-declare an event name — dashboards populate automatically the first time an event is sent.

Calling from anywhere (no tracker instance)

If you don't have the tracker instance in scope (utility modules, auth callbacks, etc.), use sendEventGlobally. It routes to the same singleton created by HumanBehaviorTracker.init(...).

import { sendEventGlobally } from 'humanbehavior-js';

await sendEventGlobally('invite_sent', {
  recipientCount: 3,
  channel: 'email'
});

Returns Promise<boolean> | null — null means the global tracker has not been initialized yet.

Reserved event names

Names prefixed with $ are reserved for events dispatched automatically by the SDK — do not use them for custom events:

Reserved name	Emitted by
`$page_viewed`	Automatic pageview tracking
`$click`	Automatic click tracking
`$rageclick`	Rapid repeated clicks on the same spot
`$deadclick`	Clicks that produce no UI change
`$form_submitted`	Form submission tracking

If you need to track a pageview manually (e.g. in a framework that does not emit popstate/pushState), call tracker.trackPageView() instead of sending $page_viewed yourself.

Automatic properties

Every custom event is enriched with automatic context before it's sent: current URL, pathname, referrer, UTM parameters, viewport size, user agent, and the active sessionId / endUserId. You only need to include the properties unique to your event.

To exclude specific automatic properties, pass propertyDenylist at init:

HumanBehaviorTracker.init(API_KEY, {
  propertyDenylist: ['utm_content', 'referrer']
});

Attaching persistent properties

If a property should be attached to every event for the rest of the session or user lifetime, set it once instead of passing it on every call.

// Attached to every event for this session only
tracker.setSessionProperty('experiment_variant', 'B');
tracker.setSessionProperties({ pricingTier: 'pro', locale: 'en-US' });

// Attached to every event for this user (persists across sessions)
tracker.setUserProperty('plan', 'premium');
tracker.setUserProperties({ company: 'Acme', role: 'admin' });

// Only set if not already set (e.g. first-touch attribution)
tracker.setOnce('first_campaign', 'spring_launch', 'user');

Removing and clearing:

tracker.removeSessionProperty('experiment_variant');
tracker.removeUserProperty('plan');

tracker.clearSessionProperties();
tracker.clearUserProperties();

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

tracker.customEvent(eventName, properties) parameters:

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

Related methods:

Method	Purpose
`tracker.trackPageView(url?)`	Manually record a pageview (SPAs that don't trigger `pushState`).
`sendEventGlobally(name, props)`	Send a custom event without the tracker instance in scope.
`tracker.setSessionProperty(k, v)` / `setSessionProperties(obj)`	Attach a property to every event in this session.
`tracker.setUserProperty(k, v)` / `setUserProperties(obj)`	Attach a property to every event for this user across sessions.
`tracker.setOnce(k, v, 'session' \| 'user')`	Set only if not already set — useful for first-touch attribution.

Custom Events

On this page