Common Methods

Overview

Rather than constantly making HTTP calls to record events, we provide abstraction with dedicated tracking libraries in several languages – for instance, our Ruby or PHP server-side tracking libraries. If you need to record data outside of our JavaScript library, you can choose to use one (or more) of them to send data.

All of our alternative tracking libraries provide the same basic methods:

record

The record method is the most commonly used method. When a record command is executed, it records a Kissmetrics 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 Library 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. Our JavaScript API will detect anonymous visitors and set up appropriate anonymous identities for them automatically.

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.

We recommend you call identify in two scenarios:

1. When a user successfully signs up
2. 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', '<%= @user.email_address %>']);

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

Examples

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

Javascript

// Identifies the current person as "[email protected]" for future events
_kmq.push(['identify', '[email protected]']);
// Records an event "Viewed Homepage"
_kmq.push(['record', 'Viewed Homepage']);
// Records an event "Signed Up" with additional properties
_kmq.push(['record', 'Signed Up', {'Plan':'Pro', 'Amount':99.95}]);
/* Records an event "Signed Up" in the past.
 * This demonstrates how to pass the '_t' and '_d' from our
 *  specifications as regular Kissmetrics properties.
 * 1234567890 = 13 Feb 2009 23:31:30 GMT
 */
_kmq.push(['record', 'Signed Up', {'_d':1, '_t':1234567890}])
// Sets the "Gender" property to "Male" for the current person
_kmq.push(['set', {'gender':'male'}]);

PHP

<?php
 KM::identify('[email protected]');
 KM::record('Viewed Homepage');
 KM::record('Signed Up', array('Plan' => 'Pro', 'Amount' => 99.95));
 KM::record('Signed Up', array('_d' => 1, '_t' => 1234567890));
 KM::set(array('gender'=>'male'));
?>

Ruby

KMTS.record('[email protected]', 'Viewed Homepage')
KMTS.record('[email protected]', 'Signed Up', {'Plan' => 'Pro', 'Amount' => 99.95})
KMTS.record('[email protected]', 'Signed Up', {'_d' => 1, '_t' => 1234567890})
KMTS.set('[email protected]', {:gender=>'male', 'Plan Name' => 'Pro'})

Python

KM.identify('[email protected]');
KM.record('Viewed Homepage');
KM.record('Signed Up', {'Plan' : 'Pro', 'Amount' : 99.95});
KM.record('Signed Up', {'_d' : 1, '_t' : 1234567890});
KM.set({'gender' : 'male'});