The KISSmetrics Asynchronous Loading API optimizes the loading of the KISSmetrics JavaScript in a way that does not affect your site’s loading times. It prevents problems with loading the KISSmetrics JavaScript from affecting your users. It also allows you to put the Javascript snippet higher in your page, which makes it more likely for your events to be tracked; if a user leaves the page before KISSmetrics can load, KISSmetrics can’t track anything. This is modeled after Google Analytics Asynchronous Tracking, so if you’ve seen or used this, the KISSmetrics version will look very similar.
There are two components to the Asynchronous Javascript API. The first is an updated script snippet that attempts to load the JavaScript asynchronously with your page. This means if our script is slow loading it shouldn’t affect the load time of your page. The second part is the implementation of a queue of API commands, called _kmq. _kmq is a native JavaScript array that lets you use push() to queue up API calls. Once the KISSmetrics JavaScript has loaded, it executes any queued API calls in _kmq. It then replaces _kmq with a custom object that has the same push() method, but this one immediately makes the API calls.
Essentially, you can start calling _kmq.push(...) before our script even loads and you don’t have to worry about any race conditions. Also if our script fails to load for some reason your users won’t experience any JavaScript errors, because the API calls will just sit in the _kmq array without being executed.
Using the Asynchronous API is very simple. The basic format is:
_kmq.push(['funcName', arg1, arg2, ...]);For example:
_kmq.push(['identify', 'user@domain.com']);
_kmq.push(['record', 'Viewed Homepage', {'Campaign':'Print'}]);You can also pass in function objects, which will be executed once the KISSmetrics API is loaded:
_kmq.push(function(){KM.record('My Event')});This can be useful if you want to record a series of events or if you have conditionals that need to be executed first.
If you are just looking to track every page view on your site we recommend Google Analytics. With KISSmetrics we recommend tracking only significant pages with specifically named events. You can use the Event Library to do this, or you can add a record command to your pages:
_kmq.push(['record', 'Viewed Signup']);So when the browser executes the line _kmq.push(['record', 'Viewed Signup']);, your event is recorded.
If you are just looking to track every click on your your site we recommend Crazy Egg. With KISSmetrics we recommend tracking only significant elements. To accomplish this, you can use trackClick. The trackClick function has logic to ensure that data is sent to KISSmetrics reliably. Running the trackClick function sets up the element to record an event only when the visitor has clicked on the element.
trackClick takes two parameters: the HTML ID or CSS class of the element you are tracking, and the name of the event to record when someone clicks said element:
<script>
_kmq.push(['trackClick', ELEMENT_ID_OR_CLASS, EVENT_NAME]);
</script>For example, you might have a invite link you want to track:
// EXAMPLE 1
<a href="invite.php" id="invite_link">Invite your friends!</a>
<script>
_kmq.push(['trackClick', 'invite_link', 'Invite Friends Clicked']);
</script>Notice that the code uses the id attribute from the link (invite_link). You can also pass in an Element object instead of the id. You can also track all the clicks on any element for a given CSS class by prepending a the CSS class with a .. For example, if you want to track clicks an any element with the CSS class play_button you can do:
// EXAMPLE 2
_kmq.push(['trackClick', '.play_button', 'Play Button Clicked']);This method will work on buttons, <div>s, links, images, or any other HTML element. It will still fire all of your existing onclick events. You can also pass in properties via an additional argument:
_kmq.push(['trackClick', 'invite_link', 'Invite Friends Clicked', {
'color':'red'
}]);The default method of tracking clicks by KISSmetrics works well for most cases. However, if you are trying to track a click on an outbound link (a link to a different website), it is possible for the browser to change pages before it has a chance to send the data to KISSmetrics. For these cases, there is an alternative function available: trackClickOnOutboundLink:
<a href="http://othersite.com" id="link1">Visit Other Site</a>
<script>
_kmq.push(['trackClickOnOutboundLink', 'link1', 'Visited Other Site']);
</script>This method is not used by default because it:
document.locationThis works fine for the majority of cases. However, there are some edge cases where a delay or redirecting via document.location may be unacceptable. For this reason we recommend you test your site if you use this method to ensure that it doesn’t interfere with your user’s experience.
You can use the trackSubmit function to track when a form is submitted. (you can also call trackForm which is identical to trackSubmit). The trackSubmit function has logic to ensure that data is sent to KISSmetrics before the browser changes pages (with a failsafe in place in case something goes wrong). Running the trackSubmit function sets up the element to record an event only when the visitor has submitted the form
trackSubmit takes two parameters: the HTML ID or CSS class of the <form> you are tracking, and the name of the event to record when someone submits said form:
<script>
_kmq.push(['trackSubmit', ELEMENT_ID_OR_CLASS, EVENT_NAME]);
</script>For example, you might have a signup form you want to track:
<form id="signup_form">
... </form>
<script>
_kmq.push(['trackSubmit', 'signup_form', 'Sign Up Form Submitted']);
</script>Notice that the code uses the id attribute from the form (signup_form). You can also pass in an Element object instead of the id. You can also track all the form submissions for all forms with a given CSS class by prepending a the CSS class with a .. For example, if you want to track form submits an any form with the CSS class invite_form you can do:
_kmq.push(['trackSubmit', '.invite_form', 'Invite Form Submitted']);It will still fire all of your existing onsubmit events.
You can also pass in properties via an additional argument:
_kmq.push(['trackSubmit', 'signup_form', 'Sign Up Form Submitted', {
'variation': 'single page'
}]);Note: our code does not validate the contents of the form. If a visitor fills out a form incorrectly and submits it, we will still count that as a submit event. Certain events like Signups could be tracked more accurately by using a server-side API to record the event when an entry is created in your database.
If you have the Form Fields setting turned on in the JavaScript Settings page, KISSmetrics will automatically pass in all non-sensitive form fields as properties when you call trackSubmit (and for any forms you are tracking via the Wizard). KISSmetrics automatically skips all password, hidden and textarea fields as well as sensitive fields (credit card info and social security numbers).
You can force KISSmetrics to ignore a field by adding the CSS class .km_ignore to the element. You can force KISSmetrics to include a field by including the CSS class .km_include.
If KISSmetrics determines that one of your form fields is a field that can be used for an identity (such as e-mail field, username, or login field) KISSmetrics will automatically call identify with the value of that field. We recommend you use trackSubmit on your signup and sign-in forms.
For reference, we will use an <input> as an identity if its ID attribute is one of the following:
useridloginusernameemailIf the ID includes _, that will also work. So user_id, user_name, and e_mail will also be used as identities.
Maybe you have a Flash game or custom video player and you would like to track every time clicks an element or completes an event within your Flash SWF. Assuming you have access to the ActionScript source code you can use Flash’s External Interface to make calls to the Javascript API.
The KISSmetrics JavaScript contains functions that facilitate A/B testing. Please refer to the A/B Testing page.
KISSmetrics tries to guess the best domain name to set your cookies on. However, sometimes it might not be the domain you want. To specify a cookie domain you can define the variable KM_COOKIE_DOMAIN before the KISSmetrics Javascript is included. This might look like:
<script type="text/javascript">
var KM_COOKIE_DOMAIN = "www.mysite.com";
var _kmq = _kmq || [];
...
</script>Alternatively, if you have put the JavaScript code on several of your subdomains, then you’ll not want to limit yourself to just the ‘www’ subdomain:
<script type="text/javascript">
var KM_COOKIE_DOMAIN = ".mysite.com";
var _kmq = _kmq || [];
...
</script>The function KM.i() will return the visitor’s KISSmetrics ID, in case you need to pass that along to another function.
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>If the current page is SSL-enabled, KISSmetrics will automatically detect this and transfer all data via HTTPS.
We do not recommend that you host the JavaScript yourself. If you have a specific use case, please contact us.