KISSmetrics has a concept of an identity to represent a person. Every event needs to be associated with an identity of the person who performed the event. A person can have several identities throughout their visits to your site. They most likely start as an anonymous visitor (represented by a unique, randomly-generated string) before proceeding to identify themselves when creating an account on your site.
KISSmetrics identities allow you to combine all of the “uniques” that originate from a single person. Suppose a person visits your site from three devices: home, work, and mobile device. Most analytics solutions consider these as three “unique” visits, but with proper identity management in KISSmetrics, we’ll recognize the three visits as having originated from one person. When you know that two different identities represent the same person, you can connect them through a process called aliasing.
Here, we discuss the two different kinds of identities–anonymous and named–and how they interact with each other.
Anonymous identities represent a person before you know their actual identity. Please remember that each person should be given a unique id. You may be tempted to identify people as "anonymous", or "no name", or "your_identifier_here", or by some other non-unique factor like their demographic information. This will only group together multiple people as one “person” in your KISSmetrics account, and your numbers will be inaccurate.
Our JavaScript API assigns random IDs to unknown visitors. It is a randomly-generated string, stored as a first party cookie km_ai. The value is currently URL-encoded. For example, our a sample anonymous ID can look like this: 5tyjk0zrrtnz5xdmcjzhso4bdyau=.
The JavaScript function KM.i() will return the visitor’s current KISSmetrics ID, in case you need to pass that along to your server. Since the KISSmetrics script loads asynchronously, you’ll want to make sure that our script has loaded before you try to call KM.i(). To ensure that is the case, you can wrap your call to KM.i() within a function, then push that function onto the _kmq array. Once the KM script has loaded, it will go through the _kmq array, executing your function.
<script type="text/javascript">
_kmq.push(function()
{ alert(KM.i()) } // Display an alert box with your current KM identity
);
</script>Our server-side APIs do not provide the ability to save the visitor’s identity for the duration of the session. When using one of our server-side APIs exclusively, you will need to generate and store (most likely as cookies) anonymous IDs for your visitors.
If you happen to be using one of the server-side APIs in conjunction with the JavaScript API, we highly recommend using the anonymous ID that the JavaScript automatically sets. As long as the identity remains consistent across the various APIs you use, your data should be consistent. In these cases, you can retrieve the KM identity that the JavaScript API - refer to the above section.
If your site collects additional information that helps identify your users, we recommend using Named identities. A named identity can be any unique string you want to pass us: an email address, user name, Facebook ID, or a unique ID from your own database. It should be a strong identifier that can stay consistent across sessions and different browsers.
The two most common places to identify your users are after they have successfully signed up or logged in.
When a person transitions from being anonymous to being named, the two IDs should be aliased together. See the next section on Connecting Two Identities with Alias.
Once the visitor can be identified (after a successful signup or log-in event), make a JavaScript API call:
_kmq.push(['identify', named_identity ]);
// Replace named_identity with code that gets the identity you want to useEvery application is different. We don’t know what identity you want to use, or what your variables are called. We ask that you customize the identify command so that you pass us the string you want to use.
Below are two examples of what the replacement code would look like in a real scenario. Remember, these are only for demonstration purposes and may not work in your application – they are here to show you what the syntax would look like. Suppose you have a Ruby app that stores the visitor’s username in the session details. Your identify call might look like one of the two below:
// EXAMPLE #1
_kmq.push(['identify', '<%=SessionDetails.UserName%>']);
// EXAMPLE #2
_kmq.push(['identify', <%= @identity.to_json %>]);An identify call will automatically alias a visitor’s anonymous ID with the new named identity.
There is no harm in calling identify several times with the same identity.
You can retrieve the named KM identity from the km_ni cookie. The value is currently URL-encoded. Again, you can also call KM.i() to get your current ID - refer to the section above.
Our server-side APIs do not provide the ability to save the visitor’s identity for the duration of the session. When using one of our server-side APIs exclusively, you will need to ensure that your API calls are attributed to the right identity.
In Ruby and Python:
KM.identify(named_identity);
# Replace named_identity with code that gets the identity you want to use
KM.record('Signed Up'); # identify, then record the desired eventIn PHP:
<?php
KM::identify(named_identity);
// Replace named_identity with code that gets the identity you want to use
KM::record('Signed Up'); // identify, then record the desired event
?>Unlike the JavaScript API, you will need to manually connect/alias an anonymous identity with its matching named identity when using a server-side API. See the next section for details.
The alias command connects two identities to represent them as the same person in your reports. It is used to connect one person’s anonymous identity with a named identity. It can also be used when a visitor’s identity changes–for example, if you are using the email address as the named identity, and the visitor updates their email address, alias lets you update their identity accordingly.
In order for the alias to appear in your reports, please record at least one event with the newly aliased identity.
Here are examples of the alias command:
In JavaScript:
_kmq.push(['alias', 'bob', 'bob@bob.com']);In Ruby and Python:
KM.alias('bob', 'bob@bob.com');In PHP:
<?php
KM::alias('bob', 'bob@bob.com');
?>If you are using our JavaScript API, there are some things that happen automatically:
identify is called for an anonymous visitor, the anonymous and named identities are aliased together.However, if you call identify twice for the same browser, we do not automatically alias the two named identities together. We recognize this scenario as two different people accessing the same computer, and keep them as two separate people in our databases. Please refer to this article for a deeper exploration of this scenario.
Filed under Getting Started