Advanced Link Tracking plugin guide

The advanced link tracking plugin (version 3.0) is designed to allow a variety of link tracking options with a minimum of custom coding, and maintaining consistent behavior as different types of tracking are enabled.

This version is designed to work with the common tag framework (V11) and is not backwards compatible to prior versions. This is also subject to change prior to final release.

General Usage

The plugin is loaded in the standard way, with the following properties available to be set via the configuration object, almost all of which are optional:

Property Name Data Type Value
trackers array Required. The tracker objects to be activated. Tracker objects are described in more detail below. If no valid tracker objects are present, no link tracking will be activated.
attribCapture string or array An array or space-delimited string containing HTML data attribute names. If the element that triggers a link tracking event has this attribute, the contents of the attribute will be captured under the parameter WT.z_attrib, where ‘attrib’ is replaced by the attribute name.
attribParams string or array An array or space delimited string containing HTML data attribute names. If the element that triggers a link tracking event has this attribute, and that attribute contains a parameter override string (see below), the parameters will be captured. These values will override defaults and also values provided in globalParams or a tracker’s params property.
attribInherit boolean If set to true, then the attribCapture and attribParams properties will look for the designated attributes both on the element triggering the link click as well as on its parent node, it’s parent node, and so on to the parent document.
catchRightClicks boolean If set to true, all trackers will capture right clicks, unless the tracker’s own catchRightClicks property is set to false. False by default.
deferReg boolean This is an advanced option described later in this document under “Deferred Registration.” Defaults to false, and should not be set to true unless you know what you’re doing.
globalParams array An array of parameter/value pairs (see below) specifying what values should be assigned to those parameters. These values will override the defaults for the tracker, but not values specified in the tracker’s own params property.
hashInURI boolean If set to true, all trackers will capture the hash/anchor component of the URL as part of DCS.dcsuri, unless the tracker’s own hashInURI  property is set to false.
hashParam string If this contains a parameter name, all trackers will capture the hash/anchor component of the URL as part of the parameter named. If a different parameter is specified in the tracker’s own hashParam property, then both will be populated.
inheritParams string or array An array or space delimited string containing the names of parameters that will be inherited from the page view instead of cleared (see below).
nvMethod string Either ‘default’ to use the base tag’s method to populate WT.nv, or ‘parent_div’ to populate WT.nv based on the parent DIV tag (see below).
nvOverride string A string containing an HTML attribute name used to populate WT.nv. Used with the ‘parent_div’ method.

Parameter/Value Pairs

Several configuration points involve arrays of parameter/value pairs to specify Webtrends parameters and their values. In each of these cases, the first element of the array will contain a string specifying the name of a Webtrends parameter (WT.param, DCSext.param, or DCS.param), and the second element will contain either a string with the value of that parameter. Any number of such pairs can be included, so long as the array always contains an even number of elements, with the first of each pair designating the parameter name and the second of each pair containing its value.

As an advanced option, the second element of the pair may contain a function instead of a string. In this case, the function will be executed (with no arguments) and the return value will be used to set the value of the parameter. In these cases, best practice is to use a fully qualified function name, typically as a property of the window object, to avoid problems with scoping.

Parameter Override String

This plugin allows parameters to be set within an HTML data attribute, but this requires composing the parameter names and values into a single string that can be placed within the attribute. To do this, arrange the parameter/value pairs in the form “parameter=value”, and separate each pair with a double-semicolon. For example:

<a href=”somelink.html”
data-wtparams=”WT.first=value1;;DCSext.second=value2”>

Link Titles (WT.ti)

This plugin has three pre-configured options for link titles (the WT.ti parameter): by destination URL either with or without query parameters, or by link content. In addition, a prefix is typically added to each. Each tracker has a default configuration for link titles, but can be overridden.

Destination URL

This link title is built by concatenating the hostname (DCS.dcssip) and URI stem (DCS.dcsuri) of the destination link, and optionally adding any query parameters (DCS.dcsqry) to the end.

To configure a tracker to use destination URL to build link titles, set the title property of the tracker object to “url” to use the full URL with query parameters, or “urlnoq” for the URL with no query parameters.

Link Content

The link title option is the default for most trackers and attempts to build a meaningful label from the contents of the anchor tag. First, it checks to see if the element clicked has a data attribute containing a link title, with the attribute(s) specified in the titleAttrib property of the tracker. If not, and the anchor tag contains an image, it will pull the alt text from that image. Otherwise, or if the image has no alt text, it will extract the text within the anchor tag and use that.

Navigational Area (WT.nv)

This plugin has two pre-configured options for navigational area (the WT.nv parameter): the default method used in the main Webtrends JavaScript code, or by extracting information from the parent DIV. Each tracker can specify which method to use with the nvMethod property, while a default can be set for all trackers at the global level. A tracker-specific property will take precedence.

Default

This method checks parent nodes until it finds a DIV or TABLE node with an id attribute, then populates WT.nv with that value. If no parent DIV nor TABLE has an id, then WT.nv will be empty. If the tracker has the nvSkip property set equal to an HTML attribute name, then any nodes with that attribute defined will be ignored during this search. This mirrors the behavior of the link tracking functionality built into the A9 and A10 tags.

Parent DIV

The parent_div method checks parent nodes until it finds the first DIV node in the chain, then checks that node for an attribute matching the nvOverride directive or a class name, in that order, populating WT.nv with the first value it finds. If the first parent DIV has neither of these attributes, then WT.nv will be empty.

Tracker Objects

Each tracker is a JavaScript object with properties that assign it a unique name, define what clicks should be tracked, and outline any other relevant configuration points. An array of trackers is passed to the plugin in the tracker property as described above.

Trackers are executed in order starting from element 0 of the array. If a particular link click meets the criteria for multiple tracker objects, only the first one executed will actually fire. Any number of trackers may be used, including multiple trackers of the same type, but this plugin will not fire multiple events for a single link click.

Some individual tracker types require or enable additional properties, but the following set of properties are supported by all trackers, with the first two being required:

Property Name Data Type Value
name string Required. A unique string to identify the tracker. If not present, or is a duplicate of an earlier tracker, then the tracker will not be loaded.
type string Required. A string identifying the type of tracker. This must be one of the supported types listed below. If the string does not match an available tracker type, the tracker will not be loaded.
attribCapture string or array An array or space-delimited string containing HTML data attribute names. If the element that triggers a link tracking event has this attribute, the contents of the attribute will be captured under the parameter WT.z_attribute, where ‘attribute’ is the attribute name.
attribParams string or array An array or space delimited string containing HTML data attribute names. If the element that triggers a link tracking event has this attribute, and that attribute contains a parameter override string (see below), the parameters will be captured. These values will override defaults and also values provided in globalParams or the params property.
attribInherit boolean If set to true, then the attribCapture and attribParams properties will look for the designated attributes both on the element triggering the link click as well as on its parent node, it’s parent node, and so on to the parent document.
catchRightClicks boolean If set to true, this tracker will capture right clicks. Overrides the global catchRightClicks property.
exclude boolean If set to true, this tracker will disable link tracking for all links that match the tracker’s criteria. This will take precedence over any tracker that may also match the link – if a link meets the criteria for an exclude tracker, no event will fire regardless of any other trackers being used. Please use this option with care.
hashInURI boolean True to capture the hash/anchor component of the URL as part of DCS.dcsuri, false to omit this component. This will override the global hashInURI property.
hashParam string If this contains a parameter name, this tracker will capture the hash/anchor component of the URL as part of the parameter named. If a different parameter is specified in the global hashParam property, then both will be populated.
inheritParams string or array An array or space delimited string containing the names of parameters that will be inherited from the page view instead of cleared (see below).  Overrides the global definition entirely if present.
nvMethod string Either ‘default’ to use the base tag’s method to populate WT.nv, or ‘parent_div’ to populate WT.nv based on the parent DIV tag (see below). Takes precedence over the global default.
nvOverride string A string containing an HTML attribute name used to populate WT.nv. Used with the ‘parent_div’ method. Defaults to the ‘data-wt_name’ attribute. Takes precedence over the global default.
params array An array of parameter/value pairs (see above) specifying what values will be assigned to those parameters. These values will override the defaults for the tracker and any parameters specified in globalParams.
title string Either “url” to build link titles from the destination URL, or “urlnoq” to build link titles from the destination URL without query parameters, or “content” to build link titles from the contents of the anchor tag.
titleAttrib string or array A string or array of strings containing the HTML attribute(s) to check for text to override the normal page title. Defaults to “data-wt_title” as a single value. If an array, attributes are checked in order from element 0 onward with the first found taking precedence.
titlePrefix string The WT.ti (link title) parameter will begin with this value followed by a colon. This will override the prefix in the default WT.ti value, but will not affect anything but the prefix.

 

The supported tracker types are:

Tracker Type Description
all_links Tracks all anchor tags on the page.
attributes Link tracking enabled by an arbitrary attribute value on the link.
classes Link tracking enabled by class name of the link or an ancestor.
custom An advanced tracker described later in this document under “Custom Trackers.”
downloads Download link tracking.
ids Link tracking enabled by ID of the link or an ancestor.
javascript Tracks all links using the “javascript:” protocol.
offsite Offsite link tracking.
urls Tracks anchor tags whose destination URL matches a pattern.

 

Unless a specific tracker specifies otherwise, default behavior is to provide all data points present on the page view except that the following parameters are modified with each link click captured:

  Parameter Value
DCS.dcssip The domain of the destination of the link.
DCS.dcsuri The URI stem of the destination of the link.
DCS.dcsqry Any query parameters specified in the link destination.
DCS.dcsref The page firing the link track event.
WT.ti The prefix “Link:” followed by the destination URL. (dcssip + dcsuri + dcsqry)
WT.dl 99
WT.nv The ID attribute of the first named DIV or TABLE element encountered while walking up the DOM from the link clicked.
WT.ac Sets to empty string unless named in inheritParams.
WT.ad Sets to empty string unless named in inheritParams.
WT.mc_id Sets to empty string unless named in inheritParams.
WT.oss Sets to empty string unless named in inheritParams.
WT.oss_r Sets to empty string unless named in inheritParams.
WT.si_n Sets to empty string unless named in inheritParams.
WT.si_p Sets to empty string unless named in inheritParams.
WT.si_x Sets to empty string unless named in inheritParams.
WT.srch Sets to empty string unless named in inheritParams.
WT.tx_e Sets to empty string unless named in inheritParams.
WT.tx_s Sets to empty string unless named in inheritParams.
WT.tx_i Sets to empty string unless named in inheritParams.
WT.tx_id Sets to empty string unless named in inheritParams.
WT.tx_it Sets to empty string unless named in inheritParams.
WT.pn_sku Sets to empty string unless named in inheritParams.

 

All Links

This tracker activates link tracking for all links on the page. It uses no additional properties, builds link titles using the “content” method, and uses default parameter values.

Attributes

This allows link tracking to be activated based on an HTML attribute value on the anchor tags. This could be used to target all links with a particular data- attribute value, which can be useful in cases where a developer doesn’t wish to add class names to links to be activated.

This tracker requires one additional property:

Property Name Data Type Value
attributes object Required. This must be an object where a property name identifies the HTML attribute to be examined, and the property’s value is the value to be matched against. A property value of Boolean true will match any value.

 

For example, the following tracker would capture clicks on any link with the data-wt-linktrack attribute set to any value:

{
name:”attribute demo”,
type:”attributes”,
attributes:{‘data-wt_linktrack’:true
}

Classes

This provides a mechanism to activate link tracking for all anchor tags of a particular class, or within a node belonging to a particular class. This could be used to specify a unique class name so that web developers can activate link tracking by assigning an anchor tag or containing node to that class, or can be used to track links based on an existing class already in use within the page.

This tracker requires one additional property:

Property Name Data Type Value
classNames string or array Required. Either an array of strings or a string containing a space-delimited list of class names that will activate link tracking. If not present, the tracker will not be loaded.

 

This tracker uses the “content” method to build link titles and the default values for all parameters.

Downloads

This tracker will fire a link tracking event when a user clicks on an anchor tag with a destination that matches one of the file extensions to be tracked. This duplicates the download link tracking available in the base tag, so if this is used as a tracker, the loader file should specify “download:false”.

This tracker requires one additional property:

Property Name Data Type Value
downloadTypes string or array Required. Either an array of strings or a string containing a comma-delimited list of file extensions to track as downloads. If not present, the tracker will not be loaded.

 

This tracker uses the “content” method of building link titles, and the following parameters are altered from their default values:

    Parameter Value
WT.dl 20

 

IDs

This provides a mechanism to activate link tracking for anchor tags by specific ID, or within a node of that specific ID. This can be used to target individual links or site sections to enable link tracking.

This tracker requires one additional property:

Property Name Data Type Value
idNames string or array Required. Either an array of strings or a string containing a space-delimited list of IDs that will activate link tracking. If not present, the tracker will not be loaded.

 

This tracker uses the “content” method to build link titles and the default values for all parameters.

JavaScript

This activates link tracking for all anchor tags on the page that use the javascript: protocol in the href attribute. This tracker uses the “content” method of building link titles, and the following parameters are altered from their default values:

    Parameter Value
WT.dl 22

 

Offsite

The offsite tracker fires a link tracking event when a user clicks on an anchor tag with a destination that leads to a domain that is not part of the current site. The current hostname is always considered part of the site, as are any hostnames indicated in the onsiteDoms property assigned to the tracker. This duplicates the offsite link tracking available in the base tag, so if this is used as a tracker, the loader file should specify “offsite:false”.

This tracker allows one additional optional property:

Property Name Data Type Value
onsiteDoms string or RegExp or array One of:

·      A string containing a space-delimited list of domains

·      A string containing a single domain

·      A RegExp object that matches some number of domains

·      An array containing some combination of strings indicating single domains or RegExp objects

 

If this property is omitted, and onsiteDoms is defined in the base tag, and it’s accessible to the plugin (the base tag is not minified, or has been modified to make it accessible), then this tracker will inherit the definition from the base tag.

This tracker uses the “url” method of building link titles, and the following parameters are altered from their default values:

    Parameter Value
WT.dl 24

 

URL

This is a mechanism to activate link tracking for anchor tags based on the destination URL, such as tracking all links to a particular file server, leading to a particular directory, or which have a query parameter.

This tracker requires one additional property:

Property Name Data Type Value
URLPatterns string or array Required. Either a string or RegEx object containing the pattern to be matched, or an array of the same. If not present, the tracker will not be loaded.

 

This tracker uses the “content” method to build link titles and the default values for all parameters.

Data Validation

The plugin validates the data types for all properties defined in the loader file. If an optional property does not conform to the requirements, it is deleted and the plugin will operate with the default value. If a tracker’s required data does not confirm to the requirements, the tracker will not be loaded.

Advanced Usage

Some options available within this plugin will cause the entire plugin to fail if not used in a very precise way, or may even generate JavaScript errors that cause the Webtrends tag itself not to fire correctly. They should be used with care, and should be tested carefully prior to deployment to production environments.

Deferred Registration

By using the global property deferReg: true, the plugin will not set up any link tracking events when the plugin is first loaded. Instead, it will prepare all of the configuration options, but wait until external code calls the Webtrends.registerLinkTracking() method before it takes the final step of attaching the link tracking code to the event handlers for those links.

If this option is used, and no external code calls the Webtrends.registerLinkTracking()  method, then the plugin will never finish its setup and no link tracking events will fire.

This technique is useful in cases where a page loads some of its content dynamically, such as sites which access a third party service to obtain an HTML fragment which is inserted into the page, or sites which access a database to obtain a list of links which are then added to the DOM. In these cases, some of the anchor tags which we want to track may not be present on the page at the time that the plugin first runs, preventing us from adding an event handler to them.

In these cases, this technique may be used to set up the link trackers, but then call the Webtrends.registerLinkTracking()  method  from within a jQuery.ready method or from some other external code that can be executed after the HTML document has fully loaded.

Custom Trackers

The trackers listed above cover the most common use cases and are not difficult to implement. Error checking is also in place so that most mistakes in configuring a tracker will disable the tracker, but not generate JavaScript errors or otherwise negatively impact other trackers or other Webtrends functionality.

Some additional use cases require more complex criteria, such as tracking download links which also match a particular URL, or tracking links within a div but which don’t belong to a particular class. Custom trackers can be used to arrange these complex criteria, but the flexibility comes with a more complex implementation and less data validation. Any custom tracker should be carefully tested to ensure that they function as intended and do not generate JavaScript errors.

A custom tracker object is much like any other tracker object, supporting the various properties that apply to all trackers, but with two very important properties unique to custom trackers: an array of include filter objects, and an array of exclude filter objects. Any link that meets the criteria for one or more include filters will be within scope for the custom tracker, unless it meets the criteria for one or more of the exclude filters. A custom tracker must include at least one include filter, but may omit the array of exclude filters entirely if desired. Both must be arrays, not individual filter objects – even if the array contains only a single filter.

Property Name Data Type Value
includes Array of objects Required. An array of filter objects that describe the include criteria to use for the custom tracker.
excludes Array of objects An array of filter objects that describe the exclude criteria to use for the custom tracker.

 

Filter objects for the includes or excludes arrays are identical other than which array they are attached to. If a property is required for a given type of filter object, and that property is absent, or does not contain the data types expected (has a string instead of a RegExp, for example), this may cause JavaScript errors or unpredictable behavior. Properties of the filter objects are:

Property Name Data Type Value
type string Required. A string identifying the type of tracker. This must be one of the supported types listed above. If the string does not match an available tracker type, the entire custom tracker will be rejected.
classes array An array of strings that each indicate a class to match against. Required for the inClass type.
doms array An array of strings that each indicate a domain to consider as an onsite domain. Required for the isOnsite type, though it may be a 0-element array.
attr object An object with one or more properties where the property name corresponds to an attribute name and the property value corresponds to an attribute value. If the property is set to true, then it matches any value.
ext array An array of strings that each indicate a file extension to match against. Required for the hasFileExtension type.
ids array An array of strings that each indicate an ID to match against. Required for the inID type.
patterns array An array of RegExp objects that each indicate a pattern to match to the link’s href attribute. Required for the hasURLPattern type.
zFunc function A function that returns true if the event should be included. The function must use the correct interface and should have no side effects. See below for details.

 

The type property for each filter object must be one of the following values:

Include/Exclude Type Description
alwaysTrue Matches all links.
hasAttribute Matches if the link has a data attribute of the given name and value. Requires the attr property.
hasFileExtension Matches if the link’s href ends in a given file extension. Requires the ext property.
hasURLPattern Matches if the link’s href matches a given regex. Requires the patterns property.
inClass Matches if the link has or is within a DOM node which has a given class. Requires the classes property.
inID Matches if the link has or is within a DOM node which has a given ID. Requires the ids property.
isJS Matches if the link’s href uses the “javascript:” protocol.
isOnsite Matches if the link is considered an onsite link. Requires the doms property.
isRightClick Matches if the event was fired due to a right click.
zFunction Matches if the provided function returns true. Requires the zFunc property.

 

The properties for a filter object are listed below.

Examples of custom trackers may be found by reviewing the JavaScript code for the plugin itself, as each of the preconfigured trackers listed in the main body of the document are implemented internally with these filter objects (after data validation).

Also note that unless the catchRightClicks property is set to true, the isRightClick filter is added to the exclude array of every tracker, including custom trackers. If you wish your custom tracker to include right clicks, be sure to set catchRightClicks: true on your tracker object.

The zFunc type is a special case that should be used sparingly and with care, and only when no other option exists, generally as part of a consulting engagement executed in cooperation with this plugin’s development team. If used, the function should accept three arguments: The first is the filter object itself, allowing the function to access other properties of the filter as configuration points. The second is an object containing the components of the destination link within the dcssip, dcsuri, dcsqry, dcsref, and hash properties of that object. The third is the DOM node that triggered the event. It is important that the function used here returns a value of true or false, and does not make any other changes, as any changes could have unpredictable results and cause JavaScript errors, especially in future updates to this plugin.

Appendix 1: Examples

Document Downloads

One simple invocation would be to activate link tracking for download links, but with a desire to capture the title for each file, stored in the data-title attribute of the anchor tag like this:

<a data-title=”Test Results for X75″ href=”/documents/32a8be43-6684-4136.docx”>Results</a>

To track this, you would activate link tracking with only a single tracker:

plugins:{
advancedLinkTracking:{
trackers:[
{name:”Doc Downloads”, type:”downloads”,
attribCapture=”data-title”}
] }
}

This code would capture the data-title attribute in the WT.z_data-title parameter.

Content Links

In another example, we have a site framework that contains a top menu, left nav, and a content pane. We want to capture all offsite links, and also any link clicks within the content pane. The content pane is identifiable because it’s contained with the div with the class name content:

<div class=”content”>
<p>Various content goes here, including some links.</p>
</div>

The advanced link tracking plugin would then be invoked like this:

plugins:{
advancedLinkTracking:{
trackers:[
{name:”downloads”, type:”downloads”},
{name:”classes”, type:”classes”, classNames:”content”},
] }
}

Because the downloads tracker fires first, download links would always have WT.dl=20 (the default for download tracking), even if contained in the content section of the page.

 

Appendix 2: Parameter Priority

When processing trackers, there may be many different sources for the same parameter. These are all listed below in order, starting with the highest precedence and moving to lower precedence.

  1. Parameter override string loaded via the attribParams
  2. Parameters captured via the attribCapture
  3. The params property of the tracker object.
  4. The globalParams property of the plugin object.
  5. The default value for the specific tracker triggering the event.
  6. The default value for the link tracking plugin as a whole.
  7. Default values provided by the base Webtrends tag.