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:
Property | Data type | Description |
---|---|---|
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 typically be captured by a custom parameter. |
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 and its parent node, its parent node, and so on to the parent document. |
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. |
catchRightClicks
|
boolean | If set to true , all trackers will capture right clicks, unless the tracker’s own catchRightClicks property is set to false . The default value is false . |
deferReg
|
boolean | If set to true , deferred registration is used. The default value is false .
Caution: Do not set this value to |
globalParams
|
array | An array of parameter-value pairs 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. |
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 |
nvMethod
|
string |
|
nvOverride
|
string | A string containing an HTML attribute name used to populate wt.nv . Used with the parent_div method. |
trackers
|
array | (Required) Specifies the tracker objects to be activated. If no valid tracker objects are present, link tracking will not be activated. |
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:
<a href="example.html"
data-wtparams="wt.first=value1;ext.second=value2">
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:
Property | Data type | Description |
---|---|---|
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 typically be captured by a custom parameter. |
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. |
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, the parameters will be captured. These values will override defaults and also values provided in globalParams or the params property. |
catchRightClicks
|
boolean | If set to true , this tracker will capture right clicks. This property 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. Be careful when using this property. |
hashParam
|
string | If this property contains a parameter name, the 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. This property overrides the corresponding global definition (if specified). |
name
|
string | (Required) A unique string to identify the tracker. If the name property is not specified or it is a duplicate of an earlier tracker, then the tracker is not loaded. |
nvMethod
|
string | Specify one of the following to set the nv method:
|
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 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 | Specifies one of the following ways to build link titles:
|
titleAttrib
|
string or array | A string or array of strings containing the HTML attributes 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. |
type
|
string | (Required) A string identifying the type of tracker. If the specified string does not match a supported tracker type, the tracker is not loaded. |
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 |
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 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
Parameter | Description |
---|---|
wt.ac
|
Sets to empty string unless named in inheritParams |
wt.ad
|
Sets to empty string unless named in inheritParams |
wt.dl
|
99 |
wt.mc_id
|
Sets to empty string unless named in inheritParams |
wt.nv
|
The ID attribute of the first named DIV or TABLE element encountered while walking up the DOM from the link clicked |
wt.oss
|
Sets to empty string unless named in inheritParams |
wt.oss_r
|
|
wt.pn_sku
|
Sets to empty string unless named in inheritParams |
wt.si_n
|
|
wt.si_p
|
|
wt.si_x
|
|
wt.srch
|
|
wt.ti
|
The prefix Link: followed by the destination URL. |
wt.tx_e
|
Sets to empty string unless named in inheritParams |
wt.tx_i
|
|
wt.tx_id
|
|
wt.tx_it
|
|
wt.tx_s
|
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 | Data type | Description |
---|---|---|
attributes
|
object | 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 value of 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 | Data type | Description |
---|---|---|
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 | Data type | Description |
---|---|---|
downloadTypes
|
string or array |
(Required) An array of strings or a string containing a comma-delimited list of file extensions to track as downloads. This tracker uses the |
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 | Data type | Description |
---|---|---|
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: 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:
Property | Data type | Description |
---|---|---|
onsiteDoms
|
|
One of the following:
|
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:
Property | Data type | Description |
---|---|---|
URLPatterns
|
string or array | (Required) Either a string or RegExp 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 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:
Property | 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 RegExp. 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. |
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:
<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.
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.
- Parameter override string loaded via the
attribParams
- Parameters captured via the
attribCapture
- The
params
property of the tracker object - The
globalParams
property of the plugin object - The default value for the specific tracker triggering the event
- The default value for the link tracking plugin as a whole
- Default values provided by the base tag.