API Methods

We offer an API for several languages. You can use one (or more) of them to send data; our databases will consolidate data from any API you use. All of our APIs provide the same basic methods: record, set, identify and alias, which are described below. For more general information on people, properties and events please see People, Events and Properties.

`record`

The record method is the most commonly used method. When a record command is executed, it records a KISSmetric event. It takes two parameters:

The name of the event to record as a string
An (optional) Hash of properties for the event

If you do not pass in a name, calling record is identical to calling set. See below for examples.

Our JavaScript API has additional methods to let you record events after a certain trigger: when an element gets clicked, or when a form is submitted.

`set`

The set method lets you set properties on a person without recording an event. It takes a Hash of properties to set. See below for examples.

`identify`

The identify method allows you to set the identity of the current person using your site. The Javascript API will set an anonymous identity for you automatically, but for the server-side APIs, you must call identify on each page view.

identify only takes a single argument, the identity of the person. This identity can be any string value you want, like a user id, login, e-mail address, or an existing cookie you have already set. Ideally, you want it to be a strong identifier (such as an e-mail address) that will be consistent across sessions, browsers, etc.

Of course before a user signs in you won’t know what their identity is. If you need to track this kind of anonymous activity you can create an anonymous identity (which you might randomly generate and store in a cookie so you can re-use it for the user). Then once a user does sign in and their identity is accessible it is simple to associate the anonymous identity with their named identity using alias (see below).

We recommend you call identify in two scenarios:

When a user successfully signs up
When a user successfully logs in, either through cookies or through a login page

Here’s an example of an identify call in a Ruby app that obtains the current visitor’s username. This may not work for your particular site, but should give you an idea of how to structure the API call.

_kmq.push(['identify', '<%=SessionDetails.UserName%>']);

For more information on how to handle identities, please refer to this Identity Management guide.

`alias`

Alias is used to associate one identity with another. This most likely will occur if a user is not signed in yet, you assign them an anonymous identity and record activity for them and they later sign in and you get a named identity. It may be useful to associate the new identity that the user had while they were anonymous, to the actual signed in user. alias may also be used if the identity for a user changes, for example, if the user changes their email, and this is what was used for their identity.

alias simply takes two arguments which are the two identities that you need to tie together. So if you call alias with the identities bob and bob@bob.com KISSmetrics will tie together the two records and will treat the identities bob and bob@bob.com as the same person. It’s OK to call this more than once with the same pair of identities. It’s also OK if a person has more than one alias. Also, which identity you pass in first is not important (either order works the same).

Once you trigger an event with the newly aliased identity, the alias will appear in the list of Customer IDs set for that person.

Note: The KISSmetrics Javascript API performs auto-aliasing automatically between an anonymous identity and a named identity. You should only need to call _kmq.push('identify', some_identity) and the Javascript API takes care of the aliasing. However, if you are not using the Javascript API you may need to use this functionality. You may also need to use this command if there are two possible identities someone can use to log in like, for example, a username and an email address.

See below for examples.

Examples

Below are some examples for the standard API. Please see APIs for supported languages.

Javascript

_kmq.push(['identify', 'bob@bob.com']);
_kmq.push(['record', 'Viewed Homepage']);
_kmq.push(['record', 'Signed Up', {'Plan':'Pro', 'Amount':99.95}]);
_kmq.push(['set', {'gender':'male'}]);
_kmq.push(['alias', 'bob', 'bob@bob.com']);

PHP

KM::identify('bob@bob.com');
KM::record('Viewed Homepage');
KM::record('Signed Up', array('Plan' => 'Pro', 'Amount' => 99.95));
KM::set(array('gender'=>'male'));
KM::alias('bob', 'bob@bob.com');

Ruby

KM.identify('bob@bob.com');
KM.record('Viewed Homepage');
KM.record('Signed Up', {'Plan' => 'Pro', 'Amount' => 99.95});
KM.set({:gender=>'male'});
KM.alias('bob', 'bob@bob.com');

Python

KM.identify('bob@bob.com');
KM.record('Viewed Homepage');
KM.record('Signed Up', {'Plan' : 'Pro', 'Amount' : 99.95});
KM.set({'gender' : 'male'});
KM.alias('bob', 'bob@bob.com');

More Information

Please see API Tips for more information.

Filed under APIs

KISSmetrics