Technical Implementation Overview

Hello engineers/developers! You’re probably here because someone on your team asked you to implement Kissmetrics for behavioral analytics. The purpose of this doc isn’t to explain “what is Kissmetrics” (we have a website for that) or “how to use the Kissmetrics platform” (we have a knowledgebase for that). It’s to tell you - the engineer - enough about implementing Kissmetrics that you can scope it without wanting to shoot rubber bands at the person who sent this link to you.

We’ll talk a bit about data model (so this all makes more sense), the thing you CANNOT live without doing, the most important other data your business needs to track, and how to test what you just implemented.

Data Model

The Kissmetrics data model has three components: people, events, and properties.
Understanding these concepts is vital to being able to analyze the data you are collecting.

A person is our representation of a user visiting your site or using your product or app. We first assign them a unique, anonymous identifier. Then when they provide an identity (e.g., and email address), we alias past and future behavior to that identity. This allows cross-device and cross-browser tracking - something business folks love.
Read more about Identities
A person can perform events. Events are actions. They have a name (e.g., “purchase”) an associated person who did the event, a timestamp, and properties (see next bullet point)
Read more about Events
Properties help describe both events and people. They’re arbitrary key-value pairs you want to attach to a user or event to provide more metadata for reporting.
Read more about Properties

Install the Kissmetrics JavaScript

The one thing you CANNOT do without in order to get started with Kissmetrics: Install the JavaScript snippet. Here’s how you do it:

Copy the JavaScript snippet from https://app.kissmetrics.io/setup or https://app.kissmetrics.io/settings
Paste the snippet into the <head> tag of the site(s) you need to track. If you have multiple pages and your pages inherit from a base layout, install the snippet on your base layout so you don’t need to paste it on every page.
- The snippet adds a script tag to your site that fetches our Kissmetrics JavaScript client-side library and
configures it with your API key.
- The Kissmetrics client-side library allows you to access convenience methods for tracking and
identifying users on your site.
- To prevent race condition issues, the snippet gives access to a _kmq global queue that you can safely
push tracking calls into prior to the KM library loading. Once the library loads, the queue will be
processed.
- If you need to execute arbitrary code once the KM library is loaded, you can push an arbitrary function
into the queue, e.g. _kmq.push(() => console.log(‘KM Library loaded’))

You can find complete JavaScript Library documentation here. You can also find detailed documentation on other libraries, on SDKs, and on our API in our Knowledge Base (you’re here already, but you get the idea).

Configuring Kissmetrics to track what you need

Once you have the snippet installed, you need to do three things to get your business folks the data they need: track actions & properties and identify people.

Note that Kissmetrics does track certain events by default. Here is the list of automatically tracked events.

Tracking Actions (Events)

It takes one line of code to track a custom event with Kissmetrics. Push the “record” operation into the global queue along with the event name and any properties or key-value pairs you’d like tracked:

window._kmq.push([‘record’, ‘Purchase’, { price: 10, item: ‘Hat’ }])

Example implementation:

With the KM snippet installed, an example implementation in JavaScript to fire a “Clicked button” event every time a user clicks a button with a CSS selector class of “button” using vanilla JavaScript would look like this:

document.querySelector(‘.button’).addEventListener(‘click’, e => {
  window._kmq.push([‘record’, ‘Clicked button’])
})

Now, when you click this button, you should see calls to the /e (for event) endpoint in your browser’s network tab, and you should also see the event register in the live tab in Kissmetrics.

Identifying people

It takes one line of code to identify a user with Kissmetrics. You simply push the “identify” operation into the global queue along with the person’s identity (e.g. email address) and any properties or key-value pairs you’d like to track as well:

window._kmq.push([‘identify’, ‘[email protected]’, { age: 35 }])

Example Implementation:

With the KM snippet installed, an example implementation in JavaScript to identify a user who submits a form with a CSS selector class of “form” and an email input with a CSS selector class of “email” using vanilla JavaScript would look like this:

document.querySelector(‘.form’).addEventListener(‘submit’, e => {
  e.preventDefault()
  const email = e.target.querySelector(‘.email’).value
  window._kmq.push([‘identify’, email])
})

Now, when you submit this form, you should see calls to the /a (for alias) endpoint in your browser’s network tab, and you should also see the identify call register in the live tab in Kissmetrics.

Testing your Kissmetrics implementation

We have a few ways to easily test to see if your implementation is properly capturing the data your company needs to see:

Default events are tracked as soon as the library is loaded on the page. Verify this by observing the calls to the Kissmetrics tracking servers in the network tab of your browser (via the developer console). See for the list of default events.
You can verify that Kissmetrics is receiving events events by visiting the live tab in your account at https://app.kissmetrics.io/live
If you have not implemented identify calls, events that enter the live tab will be tied to anonymous users. You can observe your own anonymous user identity by invoking KM.i() in your browser JavaScript console.

What's next?

If you’re stuck, give us a shout at [email protected]. We’ve seen thousands of implementations and can usually quickly diagnose what’s going on.
If your testing shows you what you expect, you’re good to go! Tell whoever sent you to this page that they can log in and use Kissmetrics. You can have them start configuring inside the app using these instructions.