Advanced Link Tracking Plugins (deprecated)

The advanced link tracking plugin provides link tracking options with a minimum of custom coding and maintains consistent behavior as different types of tracking are enabled.

Important: The advanced link tracking plugin is deprecated. This topic is included as reference for existing implementations.

The plugin is loaded with the following properties available to be set via the configuration object:

Parameter value pairs

Several configuration points involve arrays of parameter-value pairs to specify parameters and their values. In each case, the first element of the array will contain a string specifying the name of a parameter and the second element will contain a string with the value of that parameter. You can include any number of pairs provided 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 returned value will be used to set the value of the parameter. To avoid problems with scoping, use a fully-qualified function name (typically as a property of the window object).

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:

Link titles (wt.ti)

This plugin has the following preconfigured options for link titles (wt.ti):

• By destination URL with query parameters
• By destination URL without query parameters
• By link content

A prefix is typically added to each. Each tracker has a default configuration for link titles, which can be overridden.

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 Infinity JavaScript code
• By extracting information from the parent DIV

Each tracker can use the nvMethod property to specify the method, a default can be set for all trackers at the global level, and a tracker-specific property will take precedence.

Default

The default method checks parent nodes until it finds a DIV or TABLE node with an id attribute and then populates wt.nv with that value. If no parent DIV nor TABLE has an id value, 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.

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 trackers property.

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. You can use multiple trackers, including trackers of the same type. However, this plugin will not fire multiple events for a single link click.

Some individual tracker types require or enable additional properties, but all trackers support the following properties:

Supported tracker types

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

Parameters modified with each captured link click

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:

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:

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:

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:

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: 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 host name is always considered part of the site, as are any host names 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:

If this property is omitted, onsiteDoms is defined in the base tag and it is 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: 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:

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 Oracle Infinity Tag to not fire correctly. They should be used with care, and should be tested carefully prior to deployment to production environments.

Deferred registration

By using the deferReg: true property, 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 and wait until external code calls the AdvLinkTrack.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 AdvLinkTrack.registerLinkTracking(), 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 so that some of the anchor tags that you want to track may not be present on the page at the time that the plugin first runs, which prevents the addition of an event handler for them. For example, if your site accesses a third-party service to obtain an HTML fragment to be inserted into the page or if it accesses a database to obtain a list of links to be added to the DOM. In these cases, setting deferReg to true can set up the link trackers, but then call the AdvLinkTrack.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.

Caution: Do not set this value to true unless you properly implement the external code calls.

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 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.

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:

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

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

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, typically as part of a consulting engagement executed in cooperation with this plugin's development team. If used, the function should accept three arguments:

• The filter object itself, allowing the function to access other properties of the filter as configuration points.
• An object containing the components of the destination link within the dcssip, dcsuri, dcsqry, dcsref, and hash properties of that object.
• 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.

Examples

Document download example

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 in order to capture the data-title attribute.

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

Content link example

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 is contained with the div with the class name content:

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.

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 tag.

link tracking, plugin, common tag framework

link tracking, plugin, common tag framework