Blog Post:From time to time, I receive questions from clients asking how to track something that doesn't fall under the general category of "page view"—a link, a button, an image, a form interaction—something that can't easily be captured simply by tagging a page with SiteCatalyst code, even using custom variables. After all, when the page loads, you don't know what link users will click, what buttons they will press, or what values they will enter into forms. Nearly always, these solutions involve a feature built in to SiteCatalyst JavaScript code called custom links (also known as Custom Link Tracking, or Link Tracking for short). For those not familiar with the concept, Link Tracking allows you to pass data into SiteCatalyst practically whenever you want—not just when the page loads—opening the door to track link clicks, image loads, form interactions, and nearly anything else that happens on your site. Ever. If you are an experienced SiteCatalyst user, you may already be familiar with a form of Custom Link Tracking; file downloads and exit links are typically tracked automatically when SiteCatalyst code is implemented on your site. I'll explain in more detail later how these features work; for now, suffice it to say that they leverage the same basic functionality that we're about to discuss.

Why Custom Link Tracking?

It almost goes without saying that every web site is a different animal. However, this point is worth making because it is the exact reason why Custom Link Tracking can be so powerful. If every site followed the same basic template, and if each organization had the same KPIs and goals, then SiteCatalyst code would be able to anticipate what links and other user actions you would want to track, and would pass along the data accordingly. You may work on a lead generation site, passing users along to partner sites via links on your pages. You may operate a media site, with success being determined in part by impressions and click-throughs of third-party advertisements. Your site may be retail-oriented, serving upsell recommendations via a sleek AJAX-based overlay on shopping cart pages. Or your site may be something completely different. In each of these cases, applying Custom Link Tracking code to links, images, form fields, and other page elements where you want to track something can provide the insight that page view data doesn't. Note that "Link Tracking" is something of a misnomer; while tracking link clicks is its primary purpose, this feature can be applied to nearly anything, and not just to links. A great example of this is an AJAX-heavy site, which relies heavily on Link Tracking because of one of the feature's main advantages: while it is capable of passing nearly any type of SiteCatalyst data, there is one thing that it does not do. It does not count a page view. Sites that change the content of a page without actually loading a new page may not want to count a new page view every time the content changes. For these sites, Custom Link Tracking is perfect—it will pass anything but a page view.

How Does Link Tracking Work?

The nuts-and-bolts of implementing Custom Link Tracking are actually fairly simple as JavaScript goes. They are explained adequately in our Link Tracking white paper, available from the SiteCatalyst online help site. If you find that you still have questions about the technical aspects of Link Tracking after reading that white paper, leave me a comment and I'll do my best to address them. The Link Tracking code is typically applied either
  1. directly in an JavaScript event handler (usually onclick, but others work as well), or
  2. for more dynamic functionality, in a separate function called in an event handler.
Link Tracking (including automatic download and exit Link Tracking) is based on a function built into the SiteCatalyst "s" object, called s.tl(). When called, s.tl() builds a SiteCatalyst image request containing the Custom Link Tracking data that you choose to pass, along with data for any other variables you've chosen to populate. As an aside, for those of you with ActionSource experience, s.tl() is the JavaScript version of s.trackLink(). Their purpose and structure is the same. In the case of automatic download and exit Link Tracking, when a page loads, SiteCatalyst inserts an s.tl() function call into the onclick event handlers for any link where the href attribute
  1. ends in one of the extensions specified in the s.linkDownloadFileTypes variables (for file downloads), or
  2. does not contain any of the strings specified in the s.linkInternalFilters variable.
There are, essentially, three "types" of custom links; you can specify the type of link that you want to count when you make the s.tl() function call. These types are:
Link Type Description Destination Report
o Other/General. This is listed first because it is the most common choice. Used as an all-purpose option, or whenever you know that you don't want the action to be considered a file download or an exit link. Site Content > Links > Custom Links
d File Download. Use this when you want the action to be considered a file download (e.g. an HTML page that contains the text of a length piece of documentation—it isn't going to be tracked as a file download automatically, but for your purposes it may be equivalent to downloading the PDF). Site Content > Links > File Downloads
e Exit Link. Setting this type will cause the action to be considered an exit link. Site Content > Links > Custom Links
The value in the "Link Type" column above goes into the second argument in the s.tl() function call to determine the type of link to count, which also determines which report that will receive the data generated by the given link click (or other action).

A Few Things Everyone Should Know About Link Tracking

You can pass just about anything using Link Tracking. As I mentioned above, there is really only one thing that Link Tracking won't do for you: count a page view (and may pass, but will not count, a page name). Any other custom variable can be passed by leveraging the s.linkTrackVars and s.linkTrackEvents variables explained in the online documentation. Want to pass purchase data using custom links? No problem. On that final purchase button, set s.linkTrackVars="events,products,purchaseID", set s.linkTrackEvents="purchase", set each of these variables and events dynamically, call the s.tl() function, and away you go. Need to grab the user's waist size when he/she clicks the "waist size" drop-down menu on your product view page? Piece of cake. The drop-down has an onchange event handler, so you can pass the waist size (or anything else, for that matter) into a prop or eVar whenever the drop-down selection changes and fire off an s.tl() function call. Voila. You know what percentage of users is between a 32- and a 40-inch waist. You have a survey on your site, and you're sick of losing out on data from partial responses? Pass the response to each question into a prop and tag the "Next" button with Link Tracking code. Something like s.prop1="question 1:yes" or s.prop1="question1:no" for each of the questions and possible responses should do the trick. That way, whenever someone answers a question, you've got it recorded—even if he or she abandons the survey halfway through. Want to capture an image load as a file download? Easy. When you're putting Link Tracking into the onload event handler in the image tag, just make sure to set the second argument 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 capture data that you need after reading this post and the available documentation, please leave me a comment and I'll address it. Custom Link Tracking does not count a page view. I already mentioned this, but it warrants mentioning again here. This means that you will not see any data in your Pages report due to Link Tracking data. Your report suite page view totals will not change when custom link data is passed. However, Custom Link Tracking does count visits and visitors. Thus, it is possible to have more visits than page views. I have seen this in rare cases for sites that rely very heavily on this feature. You may sometimes hear Omniture representatives refer to Link Tracking image requests as "non-page view events." Now you know why. Correlation data is only available when the two variables in question were passed on the same image request. What does this have to do with Link Tracking? Occasionally, users will complain that when they go to a Custom Traffic report and break down a value in the report by Pages, they get no data. My first question is always, "Are you passing the prop data on a Link Tracking image request?" If the answer is yes, then they've answered their own question. If the prop is populated using Link Tracking, then there is no page name value for that hit. Thus, the correlation doesn't have any data for page name. The workaround is to pass the page name into another prop on every custom link image request, and then enable a correlation between the original prop and the new one storing the page name. If you are using Link Tracking on something other than a link, you'll need to tweak s.tl() slightly. The first argument in the s.tl() function call is set to "this" by default, with "this" referring to the href attribute of the page element that triggered the s.tl() call. The only problem with "this" in the context of non-links is that anchor tags (i.e. links) are typically the only page elements that have an href attribute. Therefore, if you are tagging a form field, a button, an image, or anything that isn't a true HTML link with Custom Link Tracking code, "this" will be null. Simply change it to "true" and it should work just fine. Custom Links do count as server calls. They can answer questions that normal page views cannot. At the same time, use them wisely. Even if automatic download and exit link tracking is working fine, there may be cases where you should consider Custom Link Tracking for file downloads and exit links. In this post, I have already mentioned and explained SiteCatalyst's automatic file download and exit link tracking mechanism. This will track the URLs of your downloaded files and exit links, but what if you want to pass additional variables—props and eVars, or events—when these links are clicked? What if you want complete control over the values of these variables when users download a file or exit your site? The automatic functionality is a great start, and, depending on your business needs, it may be enough. However, if you determine that it isn't enough, Custom Link Tracking is a great way to take the reins and get the most actionable data possible regarding these user interactions with your site. You cannot debug Link Tracking image requests using the JavaScript Debugger, so get familiar with a packet monitor. I recommend TamperData for Firefox, HTTPWatch for IE, or Charles for both. Each of these tools will allow you to filter your HTTP requests to show only SiteCatalyst image requests by including only URLs containing the string "/b/ss/", which is a part of every Omniture request. You can tell that you are looking at a Link Tracking request if you see a "pe=" parameter in the image request. It should be set to "lnk_", followed by the letter that you chose in the second argument of s.tl(), as described above. The s.tl() function involves a built-in 500 millisecond delay for very good reason. This delay is in place to allow the s.tl() function to execute before the next page loads, in cases where Link Tracking 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. Depending on your implementation, this 500 millisecond delay may not be necessary. For instance, AJAX calls do not involve new page loads, so there is no threat of the browser moving on to the next page before the Link Tracking request is sent. To disable the delay, set the first argument in s.tl() to "true," as described in #4 above.
Author: Date Created:March 12, 2009 Date Published: Headline:Custom Link Tracking: Capturing User Actions Social Counts: Keywords: Publisher:Adobe Image:https://blogs.adobe.com/digitalmarketing/wp-content/uploads/no-image/no-image.jpg

From time to time, I receive questions from clients asking how to track something that doesn’t fall under the general category of “page view”—a link, a button, an image, a form interaction—something that can’t easily be captured simply by tagging a page with SiteCatalyst code, even using custom variables. After all, when the page loads, you don’t know what link users will click, what buttons they will press, or what values they will enter into forms.

Nearly always, these solutions involve a feature built in to SiteCatalyst JavaScript code called custom links (also known as Custom Link Tracking, or Link Tracking for short). For those not familiar with the concept, Link Tracking allows you to pass data into SiteCatalyst practically whenever you want—not just when the page loads—opening the door to track link clicks, image loads, form interactions, and nearly anything else that happens on your site. Ever.

If you are an experienced SiteCatalyst user, you may already be familiar with a form of Custom Link Tracking; file downloads and exit links are typically tracked automatically when SiteCatalyst code is implemented on your site. I’ll explain in more detail later how these features work; for now, suffice it to say that they leverage the same basic functionality that we’re about to discuss.

Why Custom Link Tracking?

It almost goes without saying that every web site is a different animal. However, this point is worth making because it is the exact reason why Custom Link Tracking can be so powerful. If every site followed the same basic template, and if each organization had the same KPIs and goals, then SiteCatalyst code would be able to anticipate what links and other user actions you would want to track, and would pass along the data accordingly.

You may work on a lead generation site, passing users along to partner sites via links on your pages.

You may operate a media site, with success being determined in part by impressions and click-throughs of third-party advertisements.

Your site may be retail-oriented, serving upsell recommendations via a sleek AJAX-based overlay on shopping cart pages.

Or your site may be something completely different.

In each of these cases, applying Custom Link Tracking code to links, images, form fields, and other page elements where you want to track something can provide the insight that page view data doesn’t. Note that “Link Tracking” is something of a misnomer; while tracking link clicks is its primary purpose, this feature can be applied to nearly anything, and not just to links.

A great example of this is an AJAX-heavy site, which relies heavily on Link Tracking because of one of the feature’s main advantages: while it is capable of passing nearly any type of SiteCatalyst data, there is one thing that it does not do. It does not count a page view. Sites that change the content of a page without actually loading a new page may not want to count a new page view every time the content changes. For these sites, Custom Link Tracking is perfect—it will pass anything but a page view.

How Does Link Tracking Work?

The nuts-and-bolts of implementing Custom Link Tracking are actually fairly simple as JavaScript goes. They are explained adequately in our Link Tracking white paper, available from the SiteCatalyst online help site. If you find that you still have questions about the technical aspects of Link Tracking after reading that white paper, leave me a comment and I’ll do my best to address them.

The Link Tracking code is typically applied either

  1. directly in an JavaScript event handler (usually onclick, but others work as well), or
  2. for more dynamic functionality, in a separate function called in an event handler.

Link Tracking (including automatic download and exit Link Tracking) is based on a function built into the SiteCatalyst “s” object, called s.tl(). When called, s.tl() builds a SiteCatalyst image request containing the Custom Link Tracking data that you choose to pass, along with data for any other variables you’ve chosen to populate.

As an aside, for those of you with ActionSource experience, s.tl() is the JavaScript version of s.trackLink(). Their purpose and structure is the same.

In the case of automatic download and exit Link Tracking, when a page loads, SiteCatalyst inserts an s.tl() function call into the onclick event handlers for any link where the href attribute

  1. ends in one of the extensions specified in the s.linkDownloadFileTypes variables (for file downloads), or
  2. does not contain any of the strings specified in the s.linkInternalFilters variable.

There are, essentially, three “types” of custom links; you can specify the type of link that you want to count when you make the s.tl() function call. These types are:

Link Type Description Destination Report
o Other/General. This is listed first because it is the most common choice. Used as an all-purpose option, or whenever you know that you don’t want the action to be considered a file download or an exit link. Site Content > Links > Custom Links
d File Download. Use this when you want the action to be considered a file download (e.g. an HTML page that contains the text of a length piece of documentation—it isn’t going to be tracked as a file download automatically, but for your purposes it may be equivalent to downloading the PDF). Site Content > Links > File Downloads
e Exit Link. Setting this type will cause the action to be considered an exit link. Site Content > Links > Custom Links

The value in the “Link Type” column above goes into the second argument in the s.tl() function call to determine the type of link to count, which also determines which report that will receive the data generated by the given link click (or other action).

A Few Things Everyone Should Know About Link Tracking

You can pass just about anything using Link Tracking.
As I mentioned above, there is really only one thing that Link Tracking won’t do for you: count a page view (and may pass, but will not count, a page name). Any other custom variable can be passed by leveraging the s.linkTrackVars and s.linkTrackEvents variables explained in the online documentation.

Want to pass purchase data using custom links? No problem. On that final purchase button, set s.linkTrackVars="events,products,purchaseID", set s.linkTrackEvents="purchase", set each of these variables and events dynamically, call the s.tl() function, and away you go.

Need to grab the user’s waist size when he/she clicks the “waist size” drop-down menu on your product view page? Piece of cake. The drop-down has an onchange event handler, so you can pass the waist size (or anything else, for that matter) into a prop or eVar whenever the drop-down selection changes and fire off an s.tl() function call. Voila. You know what percentage of users is between a 32- and a 40-inch waist.

You have a survey on your site, and you’re sick of losing out on data from partial responses? Pass the response to each question into a prop and tag the “Next” button with Link Tracking code. Something like s.prop1="question 1:yes" or s.prop1="question1:no" for each of the questions and possible responses should do the trick. That way, whenever someone answers a question, you’ve got it recorded—even if he or she abandons the survey halfway through.

Want to capture an image load as a file download? Easy. When you’re putting Link Tracking into the onload event handler in the image tag, just make sure to set the second argument 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 capture data that you need after reading this post and the available documentation, please leave me a comment and I’ll address it.

Custom Link Tracking does not count a page view.
I already mentioned this, but it warrants mentioning again here. This means that you will not see any data in your Pages report due to Link Tracking data. Your report suite page view totals will not change when custom link data is passed. However, Custom Link Tracking does count visits and visitors. Thus, it is possible to have more visits than page views. I have seen this in rare cases for sites that rely very heavily on this feature.

You may sometimes hear Omniture representatives refer to Link Tracking image requests as “non-page view events.” Now you know why.

Correlation data is only available when the two variables in question were passed on the same image request.
What does this have to do with Link Tracking? Occasionally, users will complain that when they go to a Custom Traffic report and break down a value in the report by Pages, they get no data. My first question is always, “Are you passing the prop data on a Link Tracking image request?” If the answer is yes, then they’ve answered their own question. If the prop is populated using Link Tracking, then there is no page name value for that hit. Thus, the correlation doesn’t have any data for page name.

The workaround is to pass the page name into another prop on every custom link image request, and then enable a correlation between the original prop and the new one storing the page name.

If you are using Link Tracking on something other than a link, you’ll need to tweak s.tl() slightly.
The first argument in the s.tl() function call is set to “this” by default, with “this” referring to the href attribute of the page element that triggered the s.tl() call. The only problem with “this” in the context of non-links is that anchor tags (i.e. links) are typically the only page elements that have an href attribute. Therefore, if you are tagging a form field, a button, an image, or anything that isn’t a true HTML link with Custom Link Tracking code, “this” will be null. Simply change it to “true” and it should work just fine.

Custom Links do count as server calls.
They can answer questions that normal page views cannot. At the same time, use them wisely.

Even if automatic download and exit link tracking is working fine, there may be cases where you should consider Custom Link Tracking for file downloads and exit links.
In this post, I have already mentioned and explained SiteCatalyst’s automatic file download and exit link tracking mechanism. This will track the URLs of your downloaded files and exit links, but what if you want to pass additional variables—props and eVars, or events—when these links are clicked? What if you want complete control over the values of these variables when users download a file or exit your site? The automatic functionality is a great start, and, depending on your business needs, it may be enough. However, if you determine that it isn’t enough, Custom Link Tracking is a great way to take the reins and get the most actionable data possible regarding these user interactions with your site.

You cannot debug Link Tracking image requests using the JavaScript Debugger, so get familiar with a packet monitor.
I recommend TamperData for Firefox, HTTPWatch for IE, or Charles for both. Each of these tools will allow you to filter your HTTP requests to show only SiteCatalyst image requests by including only URLs containing the string “/b/ss/”, which is a part of every Omniture request.

You can tell that you are looking at a Link Tracking request if you see a “pe=” parameter in the image request. It should be set to “lnk_”, followed by the letter that you chose in the second argument of s.tl(), as described above.

The s.tl() function involves a built-in 500 millisecond delay for very good reason.
This delay is in place to allow the s.tl() function to execute before the next page loads, in cases where Link Tracking 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. Depending on your implementation, this 500 millisecond delay may not be necessary. For instance, AJAX calls do not involve new page loads, so there is no threat of the browser moving on to the next page before the Link Tracking request is sent. To disable the delay, set the first argument in s.tl() to “true,” as described in #4 above.