Kissmetrics Troubleshooting

Overview

This guide helps you diagnose and resolve common Kissmetrics tracking issues. Kissmetrics provides person-based analytics for understanding individual user behavior across your product.

Debug Mode

Check Kissmetrics Loading

Verify Kissmetrics is loaded correctly:

// Check if _kmq exists
if (typeof _kmq !== 'undefined') {
  console.log('Kissmetrics loaded successfully');
  console.log('_kmq queue:', _kmq);
} else {
  console.error('Kissmetrics not loaded');
}

// Check if main script is loaded
if (typeof KM !== 'undefined') {
  console.log('Kissmetrics main script loaded');
} else {
  console.log('Kissmetrics main script not yet loaded (loads async)');
}

Monitor Network Requests

// Monitor Kissmetrics requests
const observer = new PerformanceObserver((list) => {
  list.getEntries().forEach((entry) => {
    if (entry.name.includes('kissmetrics') ||
        entry.name.includes('trk.kissmetrics.io')) {
      console.log('Kissmetrics request:', entry.name);
    }
  });
});

observer.observe({ entryTypes: ['resource'] });

Common Issues

Tracking Not Working

Symptoms: Tracking code installed but no data appears in Kissmetrics.

Solutions:

1. Verify API key is correct:

// Check your API key in the script
// Should be in the Kissmetrics snippet
var _kmk = 'YOUR_API_KEY';

// Or check the tracking URL
// Should include your API key

2. Verify script installation:

<!-- Kissmetrics tracking code -->
<script type="text/javascript">
  var _kmq = _kmq || [];
  var _kmk = _kmk || 'YOUR_API_KEY';
  function _kms(u){
    setTimeout(function(){
      var d = document, f = d.getElementsByTagName('script')[0],
      s = d.createElement('script');
      s.type = 'text/javascript'; s.async = true; s.src = u;
      f.parentNode.insertBefore(s, f);
    }, 1);
  }
  _kms('//i.kissmetrics.io/i.js');
  _kms('//scripts.kissmetrics.io/' + _kmk + '.2.js');
</script>

3. Check network requests:

   • Open DevTools → Network tab
   • Filter by "kissmetrics"
   • Look for requests to trk.kissmetrics.io
   • Should see tracking requests

4. Verify _kmq queue:

// Check if _kmq is defined and is an array
if (Array.isArray(_kmq)) {
  console.log('_kmq is ready');
  console.log('Queue length:', _kmq.length);
} else {
  console.error('_kmq is not an array');
}

5. Test tracking:

// Send test event
_kmq.push(['record', 'Test Event', { test: true }]);

// Check Network tab for outgoing request

Events Not Appearing

Symptoms: Events aren't showing up in Kissmetrics reports.

Solutions:

1. Verify event syntax:

// Correct event tracking
_kmq.push(['record', 'Button Clicked']);

// With properties
_kmq.push(['record', 'Purchase', {
  'Item': 'Widget Pro',
  'Price': 99.99,
  'Currency': 'USD'
}]);

// Test event
_kmq.push(['record', 'Test Event']);

2. Check event name spelling:
   • Event names are case-sensitive
   • Use consistent naming
   • Avoid special characters

// Good event names
_kmq.push(['record', 'Signup Completed']);
_kmq.push(['record', 'Video Played']);

// Inconsistent (creates separate events)
_kmq.push(['record', 'signup completed']);  // Different case
_kmq.push(['record', 'Signup_Completed']);  // Different format

3. Wait for data processing:

   • Events can take up to 2 hours to appear in reports
   • Check "Live" view for recent events
   • Verify time range in reports

4. Ensure identify is called:

// Must identify user before recording events
_kmq.push(['identify', 'user@example.com']);
_kmq.push(['record', 'Event Name']);

// Won't work well without identify:
// _kmq.push(['record', 'Event Name']);

User Identity Issues

Symptoms: Users not being identified or tracked correctly.

Solutions:

1. Call identify with user ID:

// Identify user (email or user ID)
_kmq.push(['identify', 'user@example.com']);

// Or with user ID
_kmq.push(['identify', 'user_12345']);

// Verify in console
setTimeout(function() {
  if (typeof KM !== 'undefined' && KM.i) {
    console.log('Kissmetrics Identity:', KM.i());
  }
}, 2000);

2. Set user properties:

// Set properties after identify
_kmq.push(['identify', 'user@example.com']);
_kmq.push(['set', {
  'Name': 'John Doe',
  'Email': 'user@example.com',
  'Plan': 'Premium',
  'Signup Date': new Date().toISOString()
}]);

3. Don't switch identities mid-session:

// ❌ Bad: Switching identities
_kmq.push(['identify', 'user1@example.com']);
_kmq.push(['record', 'Event 1']);
_kmq.push(['identify', 'user2@example.com']);  // Don't do this
_kmq.push(['record', 'Event 2']);

// ✓ Good: One identity per session
_kmq.push(['identify', 'user@example.com']);
_kmq.push(['record', 'Event 1']);
_kmq.push(['record', 'Event 2']);

4. Clear identity on logout:

// Clear identity when user logs out
_kmq.push(['clearIdentity']);

// Will generate new anonymous identity

Properties Not Showing

Symptoms: Event or user properties missing from reports.

Solutions:

1. Set properties correctly:

// Set user properties
_kmq.push(['set', {
  'Email': 'user@example.com',
  'Plan': 'Premium',
  'Total Spend': 299.99
}]);

// Set event properties
_kmq.push(['record', 'Purchase', {
  'Product': 'Widget',
  'Price': 99.99,
  'Quantity': 1
}]);

2. Check property types:

// Valid property types
_kmq.push(['set', {
  'String Property': 'value',
  'Number Property': 123,
  'Boolean Property': true,
  'Date Property': new Date().toISOString()
}]);

// Avoid complex types
// Don't use: functions, objects, arrays (use JSON.stringify for arrays)

3. Use consistent property names:

// Good: Consistent naming
_kmq.push(['set', { 'Email': 'user@example.com' }]);
_kmq.push(['set', { 'Email': 'new@example.com' }]);  // Updates Email

// Bad: Inconsistent (creates separate properties)
_kmq.push(['set', { 'Email': 'user@example.com' }]);
_kmq.push(['set', { 'email': 'new@example.com' }]);  // Different property

Alias Not Working

Symptoms: User identities not being merged correctly.

Solutions:

1. Use alias to connect identities:

// When user signs up, connect anonymous ID to email
_kmq.push(['identify', 'user@example.com']);
_kmq.push(['alias', 'user_12345', 'user@example.com']);

// This connects the email to the user ID

2. Alias timing:

// Call alias at signup, not login
// Signup:
_kmq.push(['identify', 'user@example.com']);
_kmq.push(['alias', 'user_12345', 'user@example.com']);

// Login (later):
_kmq.push(['identify', 'user_12345']);
// Don't call alias again

Debugging Techniques

Comprehensive Health Check

// Complete Kissmetrics diagnostic
function kmHealthCheck() {
  console.group('Kissmetrics Health Check');

  // 1. Check if _kmq exists
  if (typeof _kmq === 'undefined') {
    console.error('❌ _kmq not defined');
    console.groupEnd();
    return;
  }
  console.log('✓ _kmq loaded');

  // 2. Check if KM object exists
  if (typeof KM !== 'undefined') {
    console.log('✓ KM object loaded');

    // Get current identity
    if (KM.i) {
      console.log('Current identity:', KM.i());
    }
  } else {
    console.log('○ KM object not yet loaded (may load async)');
  }

  // 3. Test tracking
  _kmq.push(['record', 'Health Check Test', {
    timestamp: new Date().toISOString()
  }]);
  console.log('✓ Test event queued');

  console.groupEnd();
}

kmHealthCheck();

Monitor Queue

// Log all Kissmetrics commands
const originalPush = _kmq.push;
_kmq.push = function() {
  console.log('Kissmetrics command:', arguments[0]);
  return originalPush.apply(this, arguments);
};

Test Events

// Test event tracking
function testKissmetricsEvents() {
  console.log('Testing Kissmetrics...');

  // 1. Identify
  _kmq.push(['identify', 'test@example.com']);
  console.log('✓ Identify sent');

  // 2. Set properties
  _kmq.push(['set', { 'Test Property': 'Test Value' }]);
  console.log('✓ Properties set');

  // 3. Record event
  _kmq.push(['record', 'Test Event', { test: true }]);
  console.log('✓ Event recorded');

  console.log('Check Network tab for requests to trk.kissmetrics.io');
}

testKissmetricsEvents();

Browser-Specific Issues

Safari ITP (Intelligent Tracking Prevention)

// Kissmetrics uses first-party cookies
// Less affected by ITP than third-party cookies
// Ensure proper domain configuration

Ad Blockers

// Detect if Kissmetrics is blocked
setTimeout(function() {
  if (typeof _kmq === 'undefined' || typeof KM === 'undefined') {
    console.warn('Kissmetrics may be blocked by ad blocker');
    // Consider server-side tracking fallback
  }
}, 3000);

Content Security Policy (CSP)

<!-- Add Kissmetrics domains to CSP -->
<meta http-equiv="Content-Security-Policy"
      content="script-src 'self' https://i.kissmetrics.io https://scripts.kissmetrics.io 'unsafe-inline';
               img-src 'self' https://trk.kissmetrics.io;
               connect-src 'self' https://trk.kissmetrics.io;">

Data Quality Issues

Duplicate Events

// Prevent duplicate event tracking
let eventTracked = {};

function trackOnce(eventName, properties) {
  const key = eventName + JSON.stringify(properties);

  if (!eventTracked[key]) {
    _kmq.push(['record', eventName, properties]);
    eventTracked[key] = true;

    // Clear after 5 seconds
    setTimeout(() => delete eventTracked[key], 5000);
  }
}

// Use for critical events
trackOnce('Purchase', { order_id: '12345', amount: 99.99 });

Bot Traffic

// Filter bot traffic
if (!/bot|crawler|spider/i.test(navigator.userAgent)) {
  _kmq.push(['record', 'Page View']);
} else {
  console.log('Bot detected - not tracking');
}

Getting Help

Check Kissmetrics Status

Visit Kissmetrics status page for service status.

Contact Support

If issues persist:

1. Collect debug information:

   • Browser and version
   • API key
   • Console errors/warnings
   • Network request screenshots

2. Contact Kissmetrics Support:

   • Email: support@kissmetrics.io
   • Documentation: kissmetrics.io/support
   • Include all debug information

3. Community:

   • Kissmetrics Community Forum
   • Search for similar issues

Best Practices

Regular Testing

// Create test function
function testKissmetrics() {
  console.group('Kissmetrics Tests');

  // 1. Identify user
  _kmq.push(['identify', 'test_user_' + Date.now()]);
  console.log('✓ User identified');

  // 2. Set properties
  _kmq.push(['set', { test_prop: true }]);
  console.log('✓ Properties set');

  // 3. Record event
  _kmq.push(['record', 'Test Event']);
  console.log('✓ Event recorded');

  console.groupEnd();
}

testKissmetrics();

Monitor in Production

// Log Kissmetrics errors
window.addEventListener('error', function(e) {
  if (e.message && e.message.includes('kissmetrics')) {
    console.error('Kissmetrics error:', e);
    // Send to error tracking service
  }
});

Testing Checklist

• Kissmetrics script loaded successfully
• API key is correct
• _kmq queue is functioning
• Events tracking correctly
• User identification working
• Properties being set
• No console errors
• Network requests successful
• Data appearing in reports (may take up to 2 hours)