URL API

Overview

The URL API is used alongside our Javascript Library to tag links that bring people your site.

❗️
Not to be confused with our API specifications, which lets you interact directly with our tracking servers and does not require our JavaScript Library.

Our customers use this feature to tag links for different campaigns: ad, email, and Twitter campaigns. In a nutshell, when a visitor comes to your site via one of these tagged URLs, our JavaScript Library scans the URL for special parameters and…

📘

Records an event,

Sets the visitor’s identity, and/or

Sets properties.

Preparation

For the URL API to work, the page you link to should have the JavaScript Library installed, and you should have Tagged URLs enabled in your site settings (it’s on by default).

Example

An example of a tagged URL looks like this. Assume this is a link in an email campaign:

http://yoursite.com/landing?kme=Clicked+Email+Campaign&km_variation=red+button

When someone clicks that link, the event Clicked Email Campaign will be recorded for the user with the property variation set to red button.

How It Works

Events

If your URL includes the parameter kme Kissmetrics will record an event with the value of that parameter. Anyone who goes to the following URL:

http://yoursite.com/signup?kme=Facebook+Ad

will get the event Facebook Ad recorded.

Identities

You can also pass in an identity by adding a kmi parameter. This lets you identify people coming from email messages or clicking across your sites. So you might have:

http://yoursite.com/signup?kme=Clicked+E-mail+Link&kmi=s739830572754

This will record the event Clicked E-mail for user.

🚧
Please note that anyone who clicks on that link (or visits that URL) will be identified as s739830572754. It’s not a good idea to include the identity when you make the URL public (when more than one person has access to it). For privacy reasons, we recommend not identifying by a user's email address in this way.

If you don’t know who might end up clicking the URL, you can leave off the kmi parameter and let our JavaScript Library handle assigning identities to new and returning users.

Properties

Any URL parameter with the prefix km_ will be set as a property for the user. So if you have three different links in an email that all point to http://test.com/offer, you can differentiate which link was most effective by setting up a property to record exactly which link was used. For example:

http://test.com/offer?kme=Clicked+Link&kmi=john.smith&km_Link+Location=top
http://test.com/offer?kme=Clicked+Link&kmi=john.smith&km_Link+Location=middle
http://test.com/offer?kme=Clicked+Link&kmi=john.smith&km_Link+Location=bottom

All three links will record the event Clicked Link for the user john.smith but each will set the same property Link Location to different values (top, middle, or bottom). This lets you report on all the people who Clicked Link and segment this population by which Link Location was used.