Kissmetrics Event Tracking Setup | Blue Frog Docs

Kissmetrics Event Tracking Setup

Configure event tracking in Kissmetrics.

Overview

Event tracking in Kissmetrics captures user actions and behaviors throughout their journey on your website or application. Unlike traditional analytics that focus on page views, Kissmetrics events provide a granular view of what users actually do - from clicking buttons to completing purchases.

Well-implemented event tracking enables you to:

  • Understand user behavior patterns
  • Build conversion funnels
  • Segment users by actions
  • Calculate feature adoption rates
  • Identify drop-off points in user journeys

This guide covers the complete event tracking implementation for Kissmetrics, including manual events, automatic tracking, and event naming best practices.

 

 

Recording Basic Events

Events are the fundamental unit of tracking in Kissmetrics. Every user action can be tracked as an event.

Simple Event Recording

Track an event without additional context:

_kmq.push(['record', 'Viewed Pricing Page']);
_kmq.push(['record', 'Clicked CTA Button']);
_kmq.push(['record', 'Downloaded Whitepaper']);

Events with Properties

Add context to events with properties that describe the action:

_kmq.push(['record', 'Viewed Product', {
  'Product Name': 'Blue Widget',
  'Product Category': 'Widgets',
  'Product Price': 29.99,
  'In Stock': true
}]);

_kmq.push(['record', 'Added to Cart', {
  'Product ID': 'SKU-12345',
  'Product Name': 'Blue Widget',
  'Quantity': 2,
  'Item Price': 29.99,
  'Cart Total': 59.98
}]);

Event Timing

Kissmetrics automatically timestamps all events. You can also track duration:

// Start timing
var startTime = new Date();

// Later, when action completes
var duration = (new Date() - startTime) / 1000;
_kmq.push(['record', 'Completed Onboarding', {
  'Duration (seconds)': duration,
  'Steps Completed': 5
}]);

 

 

Automatic Event Tracking

Kissmetrics provides helper methods for tracking common UI interactions without writing custom event handlers.

Click Tracking

Automatically track clicks on specific elements:

// Track clicks on element by ID
_kmq.push(['trackClick', 'signup-button', 'Clicked Signup Button']);

// Track clicks on element by class (first matching element)
_kmq.push(['trackClick', '.cta-button', 'Clicked CTA']);

// With properties
_kmq.push(['trackClick', 'download-btn', 'Clicked Download', {
  'Button Location': 'Header',
  'Button Color': 'Blue'
}]);

Form Tracking

Track form submissions automatically:

// Track form submission by ID
_kmq.push(['trackSubmit', 'contact-form', 'Submitted Contact Form']);

// With properties
_kmq.push(['trackSubmit', 'signup-form', 'Submitted Signup', {
  'Form Location': 'Homepage',
  'Form Type': 'Quick Signup'
}]);

Track outbound link clicks:

// Track when users click external links
_kmq.push(['trackClickOnOutboundLink', 'partner-site-link', 'Clicked Partner Link']);

 

 

Manual Event Tracking

For more control and flexibility, attach event tracking to your own event handlers.

Button Clicks

document.getElementById('upgrade-btn').addEventListener('click', function() {
  _kmq.push(['record', 'Clicked Upgrade Button', {
    'Current Plan': getCurrentPlan(),
    'Button Location': 'Settings Page',
    'User Tenure Days': calculateTenureDays()
  }]);
});

Form Submissions with Validation

document.getElementById('checkout-form').addEventListener('submit', function(e) {
  // Track before submission
  _kmq.push(['record', 'Submitted Checkout Form', {
    'Payment Method': document.querySelector('input[name="payment"]:checked').value,
    'Cart Items': getCartItemCount(),
    'Cart Total': getCartTotal(),
    'Coupon Applied': hasCoupon()
  }]);
});

AJAX Actions

function saveUserSettings(settings) {
  fetch('/api/settings', {
    method: 'POST',
    body: JSON.stringify(settings)
  })
  .then(response => {
    if (response.ok) {
      _kmq.push(['record', 'Updated Settings', {
        'Settings Changed': Object.keys(settings).join(', '),
        'Settings Count': Object.keys(settings).length
      }]);
    }
  });
}

Video Engagement

const video = document.getElementById('product-video');

video.addEventListener('play', function() {
  _kmq.push(['record', 'Started Video', {
    'Video Title': video.dataset.title,
    'Video Duration': video.duration
  }]);
});

video.addEventListener('ended', function() {
  _kmq.push(['record', 'Completed Video', {
    'Video Title': video.dataset.title,
    'Completion Rate': 100
  }]);
});

video.addEventListener('pause', function() {
  const percentWatched = (video.currentTime / video.duration) * 100;
  _kmq.push(['record', 'Paused Video', {
    'Video Title': video.dataset.title,
    'Percent Watched': Math.round(percentWatched),
    'Time Watched (seconds)': Math.round(video.currentTime)
  }]);
});

 

 

Common Event Categories

User Lifecycle Events

Track key moments in the user journey:

// Registration
_kmq.push(['record', 'Signed Up', {
  'Signup Method': 'Email',
  'Signup Source': 'Homepage Form',
  'Referrer': document.referrer
}]);

// Onboarding
_kmq.push(['record', 'Completed Onboarding', {
  'Steps Completed': 5,
  'Time to Complete': 180,
  'Skipped Steps': 0
}]);

// First Value Moment
_kmq.push(['record', 'Created First Project', {
  'Project Type': 'Marketing Campaign',
  'Time Since Signup': 45
}]);

E-Commerce Events

// Product browsing
_kmq.push(['record', 'Viewed Product', {
  'Product ID': 'SKU-123',
  'Product Name': 'Blue Widget',
  'Product Category': 'Widgets',
  'Price': 29.99
}]);

// Cart actions
_kmq.push(['record', 'Added to Cart', {
  'Product ID': 'SKU-123',
  'Quantity': 2,
  'Price': 29.99
}]);

_kmq.push(['record', 'Removed from Cart', {
  'Product ID': 'SKU-123',
  'Reason': 'Price too high'
}]);

// Checkout
_kmq.push(['record', 'Started Checkout', {
  'Cart Value': 89.97,
  'Items Count': 3
}]);

_kmq.push(['record', 'Completed Purchase', {
  'Order ID': 'ORD-12345',
  'Revenue': 89.97,
  'Items': 3,
  'Payment Method': 'Credit Card',
  'Shipping Method': 'Standard'
}]);

Subscription Events

// Trial start
_kmq.push(['record', 'Started Trial', {
  'Plan': 'Professional',
  'Trial Length Days': 14
}]);

// Subscription
_kmq.push(['record', 'Subscribed', {
  'Plan': 'Professional',
  'Billing Cycle': 'Monthly',
  'Price': 99
}]);

// Upgrade
_kmq.push(['record', 'Upgraded Plan', {
  'From Plan': 'Basic',
  'To Plan': 'Professional',
  'Revenue Impact': 50
}]);

// Cancellation
_kmq.push(['record', 'Cancelled Subscription', {
  'Plan': 'Professional',
  'Cancellation Reason': 'Too expensive',
  'Customer Lifetime Days': 120
}]);

Feature Usage Events

// Feature activation
_kmq.push(['record', 'Enabled Feature', {
  'Feature Name': 'Advanced Analytics',
  'Feature Category': 'Analytics'
}]);

// Feature usage
_kmq.push(['record', 'Used Feature', {
  'Feature Name': 'Export Data',
  'Export Format': 'CSV',
  'Records Exported': 1250
}]);

// Feature abandonment
_kmq.push(['record', 'Abandoned Feature Setup', {
  'Feature Name': 'Team Collaboration',
  'Setup Step': 'Invite Team Members',
  'Progress Percent': 60
}]);

Engagement Events

// Content interaction
_kmq.push(['record', 'Read Blog Post', {
  'Post Title': 'Analytics Best Practices',
  'Category': 'Guides',
  'Time on Page': 180,
  'Scroll Depth': 85
}]);

// Social sharing
_kmq.push(['record', 'Shared Content', {
  'Content Type': 'Blog Post',
  'Platform': 'Twitter',
  'Content Title': 'Analytics Best Practices'
}]);

// Feedback
_kmq.push(['record', 'Submitted Feedback', {
  'Feedback Type': 'Feature Request',
  'Satisfaction Score': 8
}]);

 

 

Event Naming Best Practices

Use Action-Based Names

Events should describe what the user did:

// Good
_kmq.push(['record', 'Clicked Upgrade Button']);
_kmq.push(['record', 'Completed Checkout']);
_kmq.push(['record', 'Downloaded Report']);

// Avoid
_kmq.push(['record', 'Upgrade Button']);
_kmq.push(['record', 'Checkout']);
_kmq.push(['record', 'Report']);

Be Consistent with Naming

Use a consistent format across all events:

// Past tense, Title Case
_kmq.push(['record', 'Signed Up']);
_kmq.push(['record', 'Completed Onboarding']);
_kmq.push(['record', 'Created Project']);

Use Descriptive Property Names

// Good
_kmq.push(['record', 'Purchased Product', {
  'Product Name': 'Blue Widget',
  'Product Category': 'Widgets',
  'Purchase Amount': 29.99,
  'Payment Method': 'Credit Card'
}]);

// Avoid abbreviations
_kmq.push(['record', 'Purchased Product', {
  'prod': 'Blue Widget',
  'cat': 'Widgets',
  'amt': 29.99,
  'pm': 'CC'
}]);

Create an Event Taxonomy

Organize events with prefixes for different categories:

// E-commerce events
_kmq.push(['record', 'Ecommerce - Viewed Product']);
_kmq.push(['record', 'Ecommerce - Added to Cart']);
_kmq.push(['record', 'Ecommerce - Completed Purchase']);

// Feature events
_kmq.push(['record', 'Feature - Enabled Export']);
_kmq.push(['record', 'Feature - Used Dashboard']);

// Account events
_kmq.push(['record', 'Account - Updated Settings']);
_kmq.push(['record', 'Account - Changed Password']);

 

 

Troubleshooting

Events Not Appearing in Kissmetrics

Issue: Events aren't showing up in reports.

Solutions:

  1. Verify Kissmetrics script is loaded:
    console.log(typeof _kmq); // Should be 'object'
  2. Check browser console for errors
  3. Ensure user is identified before critical events
  4. Verify event names don't have typos
  5. Check that events fire (add console.log before event):
    console.log('About to track signup');
_kmq.push(['record', 'Signed Up']);

Events Firing Multiple Times

Issue: Same event tracked multiple times per action.

Solutions:

// Bad - Event listeners added multiple times
function setupTracking() {
  button.addEventListener('click', () => {
    _kmq.push(['record', 'Clicked Button']);
  });
}
setupTracking(); // Called multiple times = multiple listeners

// Good - Check if listener already exists
if (!button.dataset.tracked) {
  button.addEventListener('click', () => {
    _kmq.push(['record', 'Clicked Button']);
  });
  button.dataset.tracked = 'true';
}

Properties Not Recording Correctly

Issue: Event properties show unexpected values.

Solutions:

  1. Verify property values before tracking:
    const props = {
  'Product Name': product.name,
  'Price': product.price
};
console.log('Event properties:', props);
_kmq.push(['record', 'Viewed Product', props]);
  2. Ensure values are correct data types (string, number, boolean)
  3. Avoid undefined or null values
  4. Check for proper variable scope

 

 

Testing Event Tracking

Manual Testing

// Test event in browser console
_kmq.push(['record', 'Test Event', {
  'Test Property': 'Test Value',
  'Timestamp': new Date().toISOString()
}]);

// Verify _kmq queue
console.log(_kmq);

Automated Testing

// Jest/testing-library example
test('tracks signup event when form submitted', () => {
  const mockKmq = [];
  window._kmq = mockKmq;

  render(<SignupForm />);

  fireEvent.submit(screen.getByRole('form'));

  expect(mockKmq).toContainEqual([
    'record',
    'Signed Up',
    expect.objectContaining({
      'Signup Method': 'Email'
    })
  ]);
});

Verify in Kissmetrics Dashboard

  1. Go to Kissmetrics dashboard
  2. Navigate to Live feed or Activity
  3. Find your test user
  4. Verify events appear with correct properties
  5. Check timestamp is accurate

 

 

Advanced Event Tracking

Conditional Event Tracking

function trackPurchase(order) {
  const baseEvent = {
    'Order ID': order.id,
    'Total': order.total
  };

  // Add conditional properties
  if (order.couponCode) {
    baseEvent['Coupon Code'] = order.couponCode;
    baseEvent['Discount Amount'] = order.discount;
  }

  if (order.isFirstPurchase) {
    baseEvent['First Purchase'] = true;
  }

  _kmq.push(['record', 'Completed Purchase', baseEvent]);
}

Event Queuing for SPA

// Queue events before Kissmetrics loads
window._kmq = window._kmq || [];

// Track immediately even if script hasn't loaded
_kmq.push(['record', 'Page Viewed']);

// Events are processed once script loads

Revenue Tracking

_kmq.push(['record', 'Completed Purchase', {
  'Order ID': 'ORD-12345',
  'Revenue': 149.99,        // Required for revenue reports
  'Product Name': 'Pro Plan',
  'Quantity': 1
}]);

// For Kissmetrics revenue reports, use 'Billing Amount' property
_kmq.push(['record', 'Billed Customer', {
  'Billing Amount': 99.99,
  'Billing Cycle': 'Monthly'
}]);
↑ Back to top
// SYS.FOOTER