Kissmetrics Data Layer | Blue Frog Docs

Kissmetrics Data Layer

Set up user properties in Kissmetrics.

Overview

The Kissmetrics data layer consists of user properties and event properties that enrich your analytics data. A well-structured data layer enables you to segment users, personalize experiences, and gain deeper insights into user behavior and business outcomes.

Unlike traditional analytics platforms that focus solely on page views and sessions, Kissmetrics centers on people. By properly identifying users and setting relevant properties, you can track the complete customer journey from first touch to conversion and beyond.

This guide covers how to implement user identification, manage user properties, and handle identity resolution in Kissmetrics.

 

 

User Identification

User identification is the foundation of Kissmetrics tracking. It associates all events and properties with a specific person, enabling person-based analytics.

Basic Identification

Identify a user as soon as you know who they are:

// Identify by email (most common)
_kmq.push(['identify', 'user@example.com']);

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

// Or identify by any unique identifier
_kmq.push(['identify', 'customer-abc-789']);

When to Identify Users

After Registration:

function handleRegistration(user) {
  // Identify the new user
  _kmq.push(['identify', user.email]);

  // Set initial properties
  _kmq.push(['set', {
    'Signup Date': new Date().toISOString(),
    'Signup Source': 'Website',
    'Plan': 'Free'
  }]);

  // Track the signup event
  _kmq.push(['record', 'Signed Up']);
}

After Login:

function handleLogin(user) {
  // Identify the user
  _kmq.push(['identify', user.email]);

  // Update last login
  _kmq.push(['set', {
    'Last Login': new Date().toISOString()
  }]);

  // Track login event
  _kmq.push(['record', 'Logged In']);
}

On Page Load (for authenticated users):

// If user is already logged in
document.addEventListener('DOMContentLoaded', function() {
  if (window.currentUser) {
    _kmq.push(['identify', window.currentUser.email]);
  }
});

Choosing the Right Identifier

Email Address (Recommended for most use cases):

  • Stable across sessions
  • Human-readable in reports
  • Works well for B2C applications
_kmq.push(['identify', 'user@example.com']);

User ID (For systems where emails can change):

  • Immutable identifier
  • Better for B2B with multiple email changes
  • Requires mapping to view user details
_kmq.push(['identify', 'usr_a1b2c3d4']);

Important: Use the same identifier type consistently across your entire application.

 

 

Setting User Properties

User properties are attributes that describe a person. They persist across sessions and can be used for segmentation and analysis.

Basic Property Setting

_kmq.push(['set', {
  'Plan Type': 'Enterprise',
  'Company': 'Acme Inc',
  'Role': 'Admin',
  'Account Created': '2024-01-15',
  'Monthly Spend': 499
}]);

Property Types and Examples

Account Information:

_kmq.push(['set', {
  'Account ID': 'acct_12345',
  'Plan Type': 'Professional',
  'Billing Cycle': 'Annual',
  'MRR': 99,
  'Seats': 25,
  'Account Status': 'Active'
}]);

User Profile Data:

_kmq.push(['set', {
  'First Name': 'Jane',
  'Last Name': 'Smith',
  'Title': 'Marketing Director',
  'Department': 'Marketing',
  'Company Size': '50-200',
  'Industry': 'Technology'
}]);

Behavioral Properties:

_kmq.push(['set', {
  'Last Login': new Date().toISOString(),
  'Total Logins': 47,
  'Feature Usage Score': 85,
  'Days Since Last Activity': 2,
  'Favorite Feature': 'Dashboard'
}]);

Lifecycle Properties:

_kmq.push(['set', {
  'Lifecycle Stage': 'Customer',
  'Customer Since': '2023-06-15',
  'Days as Customer': 245,
  'Renewal Date': '2025-06-15',
  'At Risk': false
}]);

Dynamic Property Updates

Update properties as they change throughout the user journey:

// When user upgrades
function handleUpgrade(newPlan) {
  _kmq.push(['set', {
    'Plan Type': newPlan.name,
    'MRR': newPlan.price,
    'Upgrade Date': new Date().toISOString()
  }]);

  _kmq.push(['record', 'Upgraded Plan', {
    'New Plan': newPlan.name,
    'Previous Plan': oldPlan.name
  }]);
}

// When user completes onboarding
function completeOnboarding() {
  _kmq.push(['set', {
    'Onboarding Complete': true,
    'Onboarding Completed Date': new Date().toISOString(),
    'Days to Onboard': 3
  }]);
}

// Incrementing counters
function trackFeatureUsage(feature) {
  // Record the event
  _kmq.push(['record', 'Used Feature', {
    'Feature Name': feature
  }]);

  // Update usage count (requires server-side or manual tracking)
  const newCount = getUserFeatureCount(feature) + 1;
  _kmq.push(['set', {
    [`${feature} Usage Count`]: newCount
  }]);
}

 

 

Identity Aliasing

Aliasing connects multiple identifiers to the same person, crucial for tracking users before and after they identify themselves.

How Aliasing Works

When a user first visits your site, Kissmetrics assigns them an anonymous ID. After they sign up or log in, you identify them with an email or user ID. Aliasing connects these identities so all their activity appears under one person.

Automatic Aliasing

In most cases, Kissmetrics handles aliasing automatically when you call identify():

// User browses anonymously
// Kissmetrics assigns anonymous ID: km_abc123

// User signs up
_kmq.push(['identify', 'user@example.com']);

// Kissmetrics automatically aliases km_abc123 to user@example.com
// All previous anonymous activity now belongs to user@example.com

Manual Aliasing

For advanced cases where automatic aliasing doesn't work:

// Connect two different identifiers
_kmq.push(['alias', 'user@example.com', 'user_12345']);

// Now events tracked with either identifier appear under the same person

Common Aliasing Scenarios

Email Change:

function handleEmailChange(oldEmail, newEmail) {
  // Alias the new email to the old one
  _kmq.push(['alias', newEmail, oldEmail]);

  // Update the email property
  _kmq.push(['set', {
    'Email': newEmail
  }]);

  // Now you can identify with either email
  _kmq.push(['identify', newEmail]);
}

Merging Accounts:

function mergeAccounts(primaryEmail, secondaryEmail) {
  // Alias secondary to primary
  _kmq.push(['alias', secondaryEmail, primaryEmail]);

  // All activity from both accounts now appears under primaryEmail
}

 

 

Clearing Identity

Clear a user's identity when they log out to prevent data leakage between users on shared devices:

function handleLogout() {
  // Clear the identity
  _kmq.push(['clearIdentity']);

  // Additional logout logic
  window.location.href = '/login';
}

This ensures the next user on the same device starts with a fresh anonymous identity.

 

 

Data Layer Best Practices

Property Naming Conventions

Use Descriptive Names:

// Good
_kmq.push(['set', {
  'Plan Type': 'Enterprise',
  'Monthly Recurring Revenue': 499
}]);

// Avoid
_kmq.push(['set', {
  'pt': 'ent',
  'mrr': 499
}]);

Use Consistent Capitalization:

// Title Case (recommended for Kissmetrics)
_kmq.push(['set', {
  'First Name': 'Jane',
  'Last Login Date': '2024-03-15'
}]);

Use Consistent Data Types:

// Always use ISO 8601 for dates
_kmq.push(['set', {
  'Signup Date': '2024-03-15T10:30:00Z' // Good
  // Not: '3/15/2024' or '15-Mar-2024'
}]);

// Use numbers for numeric values
_kmq.push(['set', {
  'Revenue': 99.99,  // Good
  'Age': 35          // Good
  // Not: 'Revenue': '$99.99' or 'Age': '35'
}]);

// Use booleans for true/false values
_kmq.push(['set', {
  'Is Premium': true,  // Good
  // Not: 'Is Premium': 'yes' or 'Is Premium': 1
}]);

Property Organization

Create a property taxonomy:

// Account properties
_kmq.push(['set', {
  'Account - ID': 'acct_123',
  'Account - Type': 'Business',
  'Account - Status': 'Active'
}]);

// User properties
_kmq.push(['set', {
  'User - First Name': 'Jane',
  'User - Role': 'Admin',
  'User - Department': 'Sales'
}]);

// Subscription properties
_kmq.push(['set', {
  'Subscription - Plan': 'Pro',
  'Subscription - MRR': 99,
  'Subscription - Start Date': '2024-01-01'
}]);

Performance Considerations

Batch Property Updates:

// Good - Single call with multiple properties
_kmq.push(['set', {
  'Plan': 'Pro',
  'MRR': 99,
  'Seats': 10,
  'Status': 'Active'
}]);

// Avoid - Multiple calls
_kmq.push(['set', { 'Plan': 'Pro' }]);
_kmq.push(['set', { 'MRR': 99 }]);
_kmq.push(['set', { 'Seats': 10 }]);
_kmq.push(['set', { 'Status': 'Active' }]);

Set Properties Before Events:

// Properties set before the event will be included
_kmq.push(['set', { 'Plan': 'Enterprise' }]);
_kmq.push(['record', 'Upgraded']);

 

 

Troubleshooting

Properties Not Appearing

Issue: Properties aren't showing up in Kissmetrics.

Solutions:

  1. Verify user is identified before setting properties
  2. Check property names for typos
  3. Ensure Kissmetrics script loaded before setting properties
  4. Check browser console for errors
// Correct order
_kmq.push(['identify', 'user@example.com']);
_kmq.push(['set', { 'Plan': 'Pro' }]);

// Wrong order - properties may not be set
_kmq.push(['set', { 'Plan': 'Pro' }]);
_kmq.push(['identify', 'user@example.com']);

Duplicate User Profiles

Issue: Same user appears as multiple people in Kissmetrics.

Solutions:

  1. Use consistent identifier (always email or always user ID)
  2. Ensure aliasing is working correctly
  3. Call identify on every page load
  4. Check for identifier changes (e.g., email updates)

Identity Persisting After Logout

Issue: New users see previous user's identity.

Solutions:

function handleLogout() {
  _kmq.push(['clearIdentity']);
  // Clear other session data
  localStorage.clear();
  sessionStorage.clear();
}

 

 

Testing Your Data Layer

Verify Identity

// In browser console
console.log(_kmq);
// Should show queued identify command

// Check for Kissmetrics cookie
document.cookie.split(';').filter(c => c.includes('km_'));

Verify Properties

Check Kissmetrics dashboard:

  1. Go to People section
  2. Find your test user
  3. Verify all properties appear correctly
  4. Check property values and data types

Test Aliasing

  1. Visit site in incognito mode (anonymous)
  2. Perform actions
  3. Sign up/login (identify)
  4. Check that pre-signup actions appear in user timeline

 

 

Example: Complete Data Layer Implementation

// On page load
(function() {
  // Initialize Kissmetrics
  var _kmq = _kmq || [];

  // If user is logged in, identify them
  if (window.currentUser) {
    _kmq.push(['identify', window.currentUser.email]);

    // Set/update user properties
    _kmq.push(['set', {
      'First Name': window.currentUser.firstName,
      'Last Name': window.currentUser.lastName,
      'Plan Type': window.currentUser.plan,
      'Account Created': window.currentUser.createdAt,
      'Last Login': new Date().toISOString(),
      'Total Logins': window.currentUser.loginCount
    }]);
  }
})();

// On signup
function handleSignup(userData) {
  _kmq.push(['identify', userData.email]);

  _kmq.push(['set', {
    'First Name': userData.firstName,
    'Last Name': userData.lastName,
    'Signup Date': new Date().toISOString(),
    'Signup Source': userData.source,
    'Plan': 'Free',
    'Account Status': 'Active'
  }]);

  _kmq.push(['record', 'Signed Up', {
    'Source': userData.source,
    'Referrer': document.referrer
  }]);
}

// On plan upgrade
function handleUpgrade(planData) {
  _kmq.push(['set', {
    'Plan Type': planData.name,
    'MRR': planData.price,
    'Billing Cycle': planData.cycle,
    'Upgrade Date': new Date().toISOString(),
    'Account Status': 'Paying'
  }]);

  _kmq.push(['record', 'Upgraded to Paid', {
    'Plan': planData.name,
    'Price': planData.price,
    'Billing Cycle': planData.cycle
  }]);
}

// On logout
function handleLogout() {
  _kmq.push(['record', 'Logged Out']);
  _kmq.push(['clearIdentity']);

  window.location.href = '/login';
}
↑ Back to top
// SYS.FOOTER