URL API

• Preparation
  • Example
• How It Works
  • Events
  • Identities
    • Example with Mass-mailers
  • Properties
• URL Builder

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…

1. Records an event,
2. Sets the visitor’s identity, and/or
3. 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&
  kmi=user%40domain.com&km_variation=red+button.

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

Note: @ is URL-encoded as %40 to safely send the symbol as part of a URL.

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 using the user’s email address. So you might have:

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

This will record the event Clicked E-mail for user bob@bob.com. (@ is URL-encoded as %40 to safely send the symbol as part of a URL.)

Please note that anyone who clicks on that link (or visits that URL) will be identified as bob@bob.com. 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).

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.

Example with Mass-mailers

From the example above, we mentioned that your mass-mailer may provide a variable for substituting in the recipient’s email address, something like {recipient.email}. If so, you can build out the URL like this:

http://yoursite.com/signup?kme=Clicked+E-mail+Link&kmi={recipient.email}

So that the mailer will substitute in the real email address for each link generated:

http://yoursite.com/signup?kme=Clicked+E-mail+Link&kmi=bob%40bob.com
http://yoursite.com/signup?kme=Clicked+E-mail+Link&kmi=carl%40carl.com

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.

URL Builder

Here is a form to help you quickly build URLs. The URL field is the only required field. Events, identities, and properties are all optional, depending on how much Kissmetrics information this particular URL will provide.

See the next section “How It Works” for several examples.

Again, the URL is the only required field. You can create URLs to trigger an event without properties, or to only set the visitor’s identity, or to only set properties, or to trigger an event with properties, and so on.

All of the possible combinations are here:

• URL + event only
• URL + event + identity
• URL + event + identity + properties
• URL + identity only
• URL + identity + properties
• URL + properties only