Custom Events API

Track custom events, identify users, and enrich your analytics data with Lytical's JavaScript API.

Overview

While Lytical automatically captures clicks, form submissions, pageviews, and other user interactions, sometimes you need to track events that can't be automatically detected—like completed purchases, video plays, or custom application events.

The Custom Events API lets you send these events directly from your JavaScript code, giving you complete control over what gets tracked and when.

Quick Start

Once Lytical is installed on your site, the API is available globally as window.lyt:

// Track a custom event
lyt.track('Purchase Completed', {
  product_id: 'SKU-12345',
  product_name: 'Premium Widget',
  price: 99.99,
  currency: 'USD'
});

// Identify a user
lyt.identify('user_12345', {
  email: 'user@example.com',
  plan: 'premium'
});

API Reference

lyt.track(eventName, properties)

Send a custom event with optional properties.

Parameter	Type	Description
`eventName` Required	String	The name of your custom event (e.g., "Purchase Completed")
`properties` Optional	Object	Key-value pairs of additional data to attach to the event

// Basic event
lyt.track('Newsletter Signup');

// Event with properties
lyt.track('Video Played', {
  video_id: 'abc123',
  video_title: 'Product Demo',
  duration: 120
});

lyt.identify(userId, properties)

Associate the current visitor with a known user ID from your system.

Parameter	Type	Description
`userId` Required	String	Your internal user ID (e.g., database ID, email, username)
`properties` Optional	Object	Additional user properties to store

// After user logs in
lyt.identify('user_12345', {
  email: 'jane@example.com',
  name: 'Jane Smith',
  plan: 'enterprise',
  company: 'Acme Inc'
});

lyt.addUserProperties(properties)

Add or update properties for the current user without re-identifying them.

Parameter	Type	Description
`properties` Required	Object	Key-value pairs to add to the user's profile

// Update user properties after they complete onboarding
lyt.addUserProperties({
  onboarding_completed: true,
  completed_at: new Date().toISOString()
});

lyt.reset()

Clear the current user identity. Call this when a user logs out.

// On logout
lyt.reset();

lyt.getVisitorId()

Returns the anonymous visitor ID for the current user.

const visitorId = lyt.getVisitorId();
// Returns: "v_a1b2c3d4e5f6..."

lyt.getSessionId()

Returns the current session ID.

const sessionId = lyt.getSessionId();
// Returns: "s_x1y2z3..."

lyt.isReady()

Check if Lytical has finished loading and is ready to track events.

if (lyt.isReady()) {
  lyt.track('App Loaded');
}

Common Use Cases

E-commerce Events

// Product viewed
lyt.track('Product Viewed', {
  product_id: 'SKU-001',
  product_name: 'Running Shoes',
  category: 'Footwear',
  price: 129.99
});

// Add to cart
lyt.track('Added to Cart', {
  product_id: 'SKU-001',
  quantity: 1,
  cart_total: 129.99
});

// Purchase completed
lyt.track('Purchase Completed', {
  order_id: 'ORD-12345',
  total: 149.99,
  currency: 'USD',
  items_count: 2
});

SaaS & Subscription Events

// User signed up
lyt.track('Signed Up', {
  method: 'google',
  referral_source: 'blog'
});

// Trial started
lyt.track('Trial Started', {
  plan: 'pro',
  trial_days: 14
});

// Subscription upgraded
lyt.track('Subscription Upgraded', {
  from_plan: 'starter',
  to_plan: 'pro',
  mrr_change: 50
});

Content & Engagement

// Video engagement
lyt.track('Video Played', {
  video_id: 'vid_123',
  title: 'Getting Started Guide',
  duration: 180
});

lyt.track('Video Completed', {
  video_id: 'vid_123',
  watch_time: 175
});

// Search performed
lyt.track('Search Performed', {
  query: 'pricing plans',
  results_count: 12
});

Best Practices

Use Descriptive Event Names

Name events using past tense verbs that describe what happened: "Purchase Completed", "Video Played", "Form Submitted".

Keep Properties Consistent

Use the same property names across similar events. If you use product_id in one event, don't use productId or item_id in another.

Don't Track Sensitive Data

Never include passwords, credit card numbers, social security numbers, or other sensitive personal information in event properties.

Migrating from Heap

If you're migrating from Heap, the Lytical API is designed to be familiar:

Heap	Lytical
`heap.track(name, props)`	`lyt.track(name, props)`
`heap.identify(id)`	`lyt.identify(id, props)`
`heap.addUserProperties(props)`	`lyt.addUserProperties(props)`
`heap.resetIdentity()`	`lyt.reset()`

For convenience, window.lytical is also available as an alias for window.lyt.

Creating Event Definitions

Once you're tracking custom events, you can create Event Definitions in Lytical to organize and label them for easier analysis. Go to Data → Event Definitions and:

Click "New Event Definition"
Select "Custom Event" from the quick-select buttons
Enter the custom event name you want to match (e.g., "Purchase Completed")
Add additional criteria if needed (like specific property values)
Save your definition

Lytical will automatically label all matching events, making it easy to analyze them in reports and funnels.