Custom Link Tracking: Capturing User Actions

From time to time, I receive ques­tions from clients ask­ing how to track some­thing that doesn’t fall under the gen­eral cat­e­gory of “page view”—a link, a but­ton, an image, a form interaction—something that can’t eas­ily be cap­tured sim­ply by tag­ging a page with Site­Cat­a­lyst code, even using cus­tom vari­ables. After all, when the page loads, you don’t know what link users will click, what but­tons they will press, or what val­ues they will enter into forms.

Nearly always, these solu­tions involve a fea­ture built in to Site­Cat­a­lyst JavaScript code called cus­tom links (also known as Cus­tom Link Track­ing, or Link Track­ing for short). For those not famil­iar with the con­cept, Link Track­ing allows you to pass data into Site­Cat­a­lyst prac­ti­cally when­ever you want—not just when the page loads—opening the door to track link clicks, image loads, form inter­ac­tions, and nearly any­thing else that hap­pens on your site. Ever.

If you are an expe­ri­enced Site­Cat­a­lyst user, you may already be famil­iar with a form of Cus­tom Link Track­ing; file down­loads and exit links are typ­i­cally tracked auto­mat­i­cally when Site­Cat­a­lyst code is imple­mented on your site. I’ll explain in more detail later how these fea­tures work; for now, suf­fice it to say that they lever­age the same basic func­tion­al­ity that we’re about to discuss.

Why Cus­tom Link Tracking?

It almost goes with­out say­ing that every web site is a dif­fer­ent ani­mal. How­ever, this point is worth mak­ing because it is the exact rea­son why Cus­tom Link Track­ing can be so pow­er­ful. If every site fol­lowed the same basic tem­plate, and if each orga­ni­za­tion had the same KPIs and goals, then Site­Cat­a­lyst code would be able to antic­i­pate what links and other user actions you would want to track, and would pass along the data accordingly.

You may work on a lead gen­er­a­tion site, pass­ing users along to part­ner sites via links on your pages.

You may oper­ate a media site, with suc­cess being deter­mined in part by impres­sions and click-throughs of third-party advertisements.

Your site may be retail-oriented, serv­ing upsell rec­om­men­da­tions via a sleek AJAX-based over­lay on shop­ping cart pages.

Or your site may be some­thing com­pletely different.

In each of these cases, apply­ing Cus­tom Link Track­ing code to links, images, form fields, and other page ele­ments where you want to track some­thing can pro­vide the insight that page view data doesn’t. Note that “Link Track­ing” is some­thing of a mis­nomer; while track­ing link clicks is its pri­mary pur­pose, this fea­ture can be applied to nearly any­thing, and not just to links.

A great exam­ple of this is an AJAX-heavy site, which relies heav­ily on Link Track­ing because of one of the feature’s main advan­tages: while it is capa­ble of pass­ing nearly any type of Site­Cat­a­lyst data, there is one thing that it does not do. It does not count a page view. Sites that change the con­tent of a page with­out actu­ally load­ing a new page may not want to count a new page view every time the con­tent changes. For these sites, Cus­tom Link Track­ing is perfect—it will pass any­thing but a page view.

How Does Link Track­ing Work?

The nuts-and-bolts of imple­ment­ing Cus­tom Link Track­ing are actu­ally fairly sim­ple as JavaScript goes. They are explained ade­quately in our Link Track­ing white paper, avail­able from the Site­Cat­a­lyst online help site. If you find that you still have ques­tions about the tech­ni­cal aspects of Link Track­ing after read­ing that white paper, leave me a com­ment and I’ll do my best to address them.

The Link Track­ing code is typ­i­cally applied either

1. directly in an JavaScript event han­dler (usu­ally onclick, but oth­ers work as well), or
2. for more dynamic func­tion­al­ity, in a sep­a­rate func­tion called in an event handler.

Link Track­ing (includ­ing auto­matic down­load and exit Link Track­ing) is based on a func­tion built into the Site­Cat­a­lyst “s” object, called s.tl(). When called, s.tl() builds a Site­Cat­a­lyst image request con­tain­ing the Cus­tom Link Track­ing data that you choose to pass, along with data for any other vari­ables you’ve cho­sen to populate.

As an aside, for those of you with Action­Source expe­ri­ence, s.tl() is the JavaScript ver­sion of s.trackLink(). Their pur­pose and struc­ture is the same.

In the case of auto­matic down­load and exit Link Track­ing, when a page loads, Site­Cat­a­lyst inserts an s.tl() func­tion call into the onclick event han­dlers for any link where the href attribute

1. ends in one of the exten­sions spec­i­fied in the s.linkDownloadFileTypes vari­ables (for file down­loads), or
2. does not con­tain any of the strings spec­i­fied in the s.linkInternalFilters variable.

There are, essen­tially, three “types” of cus­tom links; you can spec­ify the type of link that you want to count when you make the s.tl() func­tion call. These types are:

Link Type	Descrip­tion	Des­ti­na­tion Report
o	Other/General. This is listed first because it is the most com­mon choice. Used as an all-purpose option, or when­ever you know that you don’t want the action to be con­sid­ered a file down­load or an exit link.	Site Con­tent > Links > Cus­tom Links
d	File Down­load. Use this when you want the action to be con­sid­ered a file down­load (e.g. an HTML page that con­tains the text of a length piece of documentation—it isn’t going to be tracked as a file down­load auto­mat­i­cally, but for your pur­poses it may be equiv­a­lent to down­load­ing the PDF).	Site Con­tent > Links > File Downloads
e	Exit Link. Set­ting this type will cause the action to be con­sid­ered an exit link.	Site Con­tent > Links > Cus­tom Links

The value in the “Link Type” col­umn above goes into the sec­ond argu­ment in the s.tl() func­tion call to deter­mine the type of link to count, which also deter­mines which report that will receive the data gen­er­ated by the given link click (or other action).

A Few Things Every­one Should Know About Link Tracking

You can pass just about any­thing using Link Track­ing.
As I men­tioned above, there is really only one thing that Link Track­ing won’t do for you: count a page view (and may pass, but will not count, a page name). Any other cus­tom vari­able can be passed by lever­ag­ing the s.linkTrackVars and s.linkTrackEvents vari­ables explained in the online documentation.

Want to pass pur­chase data using cus­tom links? No prob­lem. On that final pur­chase but­ton, set s.linkTrackVars="events,products,purchaseID", set s.linkTrackEvents="purchase", set each of these vari­ables and events dynam­i­cally, call the s.tl() func­tion, and away you go.

Need to grab the user’s waist size when he/she clicks the “waist size” drop-down menu on your prod­uct view page? Piece of cake. The drop-down has an onchange event han­dler, so you can pass the waist size (or any­thing else, for that mat­ter) into a prop or eVar when­ever the drop-down selec­tion changes and fire off an s.tl() func­tion call. Voila. You know what per­cent­age of users is between a 32– and a 40-inch waist.

You have a sur­vey on your site, and you’re sick of los­ing out on data from par­tial responses? Pass the response to each ques­tion into a prop and tag the “Next” but­ton with Link Track­ing code. Some­thing like s.prop1="question 1:yes" or s.prop1="question1:no" for each of the ques­tions and pos­si­ble responses should do the trick. That way, when­ever some­one answers a ques­tion, you’ve got it recorded—even if he or she aban­dons the sur­vey halfway through.

Want to cap­ture an image load as a file down­load? Easy. When you’re putting Link Track­ing into the onload event han­dler in the image tag, just make sure to set the sec­ond argu­ment in s.tl() to a ‘d’ and you’re all set.

And I could keep going. As I said, if you aren’t sure how to cap­ture data that you need after read­ing this post and the avail­able doc­u­men­ta­tion, please leave me a com­ment and I’ll address it.

Cus­tom Link Track­ing does not count a page view.
I already men­tioned this, but it war­rants men­tion­ing again here. This means that you will not see any data in your Pages report due to Link Track­ing data. Your report suite page view totals will not change when cus­tom link data is passed. How­ever, Cus­tom Link Track­ing does count vis­its and vis­i­tors. Thus, it is pos­si­ble to have more vis­its than page views. I have seen this in rare cases for sites that rely very heav­ily on this feature.

You may some­times hear Omni­ture rep­re­sen­ta­tives refer to Link Track­ing image requests as “non-page view events.” Now you know why.

Cor­re­la­tion data is only avail­able when the two vari­ables in ques­tion were passed on the same image request.
What does this have to do with Link Track­ing? Occa­sion­ally, users will com­plain that when they go to a Cus­tom Traf­fic report and break down a value in the report by Pages, they get no data. My first ques­tion is always, “Are you pass­ing the prop data on a Link Track­ing image request?” If the answer is yes, then they’ve answered their own ques­tion. If the prop is pop­u­lated using Link Track­ing, then there is no page name value for that hit. Thus, the cor­re­la­tion doesn’t have any data for page name.

The workaround is to pass the page name into another prop on every cus­tom link image request, and then enable a cor­re­la­tion between the orig­i­nal prop and the new one stor­ing the page name.

If you are using Link Track­ing on some­thing other than a link, you’ll need to tweak s.tl() slightly.
The first argu­ment in the s.tl() func­tion call is set to “this” by default, with “this” refer­ring to the href attribute of the page ele­ment that trig­gered the s.tl() call. The only prob­lem with “this” in the con­text of non-links is that anchor tags (i.e. links) are typ­i­cally the only page ele­ments that have an href attribute. There­fore, if you are tag­ging a form field, a but­ton, an image, or any­thing that isn’t a true HTML link with Cus­tom Link Track­ing code, “this” will be null. Sim­ply change it to “true” and it should work just fine.

Cus­tom Links do count as server calls.
They can answer ques­tions that nor­mal page views can­not. At the same time, use them wisely.

Even if auto­matic down­load and exit link track­ing is work­ing fine, there may be cases where you should con­sider Cus­tom Link Track­ing for file down­loads and exit links.
In this post, I have already men­tioned and explained SiteCatalyst’s auto­matic file down­load and exit link track­ing mech­a­nism. This will track the URLs of your down­loaded files and exit links, but what if you want to pass addi­tional variables—props and eVars, or events—when these links are clicked? What if you want com­plete con­trol over the val­ues of these vari­ables when users down­load a file or exit your site? The auto­matic func­tion­al­ity is a great start, and, depend­ing on your busi­ness needs, it may be enough. How­ever, if you deter­mine that it isn’t enough, Cus­tom Link Track­ing is a great way to take the reins and get the most action­able data pos­si­ble regard­ing these user inter­ac­tions with your site.

You can­not debug Link Track­ing image requests using the JavaScript Debug­ger, so get famil­iar with a packet mon­i­tor.
I rec­om­mend Tam­per­Data for Fire­fox, HTTP­Watch for IE, or Charles for both. Each of these tools will allow you to fil­ter your HTTP requests to show only Site­Cat­a­lyst image requests by includ­ing only URLs con­tain­ing the string “/b/ss/”, which is a part of every Omni­ture request.

You can tell that you are look­ing at a Link Track­ing request if you see a “pe=” para­me­ter in the image request. It should be set to “lnk_”, fol­lowed by the let­ter that you chose in the sec­ond argu­ment of s.tl(), as described above.

The s.tl() func­tion involves a built-in 500 mil­lisec­ond delay for very good rea­son.
This delay is in place to allow the s.tl() func­tion to exe­cute before the next page loads, in cases where Link Track­ing is applied to links. If the next page loads before the image request has a chance to be sent, your data will not be tracked. Depend­ing on your imple­men­ta­tion, this 500 mil­lisec­ond delay may not be nec­es­sary. For instance, AJAX calls do not involve new page loads, so there is no threat of the browser mov­ing on to the next page before the Link Track­ing request is sent. To dis­able the delay, set the first argu­ment in s.tl() to “true,” as described in #4 above.