kissmetrics

The Kissmetrics Developer Hub

Welcome to the kissmetrics developer hub. You'll find comprehensive guides and documentation to help you start working with kissmetrics as quickly as possible, as well as support if you get stuck. Let's jump right in!

Knowledge Base    

Identities

How to set up identities?

  1. Kissmetrics tracks people.

  2. People can be represented with usually at least 2 different names in their lifetime as a customer. One when they are first anonymous; another when they become known through signing up, logging in, or installing your app.

  3. Kissmetrics has two techniques to connect these different names to represent the same person: alias and identify.

Anonymous Identities

If the JavaScript Library has never seen a visitor before, it will create a randomized identity for them to attribute all of that person’s events to the same browser. This lets you track this particular person’s activity across sessions.

The generated ID is Base64 encoded, so the IDs are generated with only these characters: a-z, A-Z, 0-9, +, /, and =.

How to Identify and Alias Users

Identifying

The function KM.i() will return the visitor’s Kissmetrics ID, in case you need to pass that along to another function.

Remember to wrap this in a callback function to ensure the JavaScript library has loaded before you try to fetch this information:

<script type="text/javascript">
_kmq.push(function()
  { alert(KM.i()) } // Display an alert box with your current KM identity
);
</script>

Aliasing

Method URL:

Parameters (GET)

Parameters

Format

Necessary?

Description

_k

string

yes

Your API Key

_p

255 char string

yes

One of the person's identities

_n

255 char string

yes

Another of the person's identities

Example

http://trk.kissmetrics.io/a?_k=api-key&_p=User+12345&_n=bob%40bob.com

This tells us that events done by User 12345 and events done by [email protected] were done by the same person. If you log events or properties to either ID, they all refer back to the same one person.

❗️

Alert:

Calling alias is not reversible, and should be used with some caution

When to Alias

There are only a handful of scenarios where it is appropriate to directly call alias:

  • You implement Kissmetrics using more than one source of data: combining data from an external KM integration, server-side libraries, and/or our JavaScript library.

  • You are identifying people by their email address, and they update their email address within your app.

  • You change your tracking schema to identify people…say, from email address to username.

Notes

  • After calling alias, the new alias does not appear in a person’s list of Customer IDs unless the new alias has triggered an event or has properties set on it.

  • It’s fine to call alias more than once with the same pair of identities.

  • It’s natural if a person has more than one alias.

  • The order you pass the two arguments does not matter.

Batching

Aliasing with Kissmetrics is now done in batches. Every 6 hours users who have had alias calls called on them are aliased together.

This means if you alias 2 users together and then look up that user, you will see two distinct users if the aliases have not been processed yet.

It won't necessarily take 6 hours for aliasing to occur, it could be aliased immediately or up to 6 hours depending on where you are in the cycle.

The Identify call triggers aliasing, so this affects both Aliasing users and Identifying users.

Updated about a year ago

Identities


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.