Skip to main content
caution
You are reading documentation for an outdated version. Here’s the latest one!

Link click tracking

Link click tracking adds click event listeners to all link elements.

Link clicks are tracked as self describing events. Each link click event captures the link’s href attribute. The event also has fields for the link’s id, classes, and target (where the linked document is opened, such as a new tab or new window).

Here is the JSON schema for a link click event.

Link click events are automatically tracked once configured.

Install plugin​

Tracker DistributionIncluded
sp.js✅
sp.lite.js❌

Download:

Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)

Note: The links to the CDNs above point to the current latest version. You should pin to a specific version when integrating this plugin on your website if you are using a third party CDN in production.

Turn on link click tracking like this:

window.snowplow('addPlugin',
  "https://cdn.jsdelivr.net/npm/@snowplow/browser-plugin-link-click-tracking@3/dist/index.umd.min.js",
  ["snowplowLinkClickTracking", "LinkClickTrackingPlugin"]
);

snowplow('enableLinkClickTracking');

Use this method once and the tracker will add click event listeners to all link elements.

An optional parameter is pseudoClicks. If this is not turned on, Firefox will not recognize middle clicks. If it is turned on, there is a small possibility of false positives (click events firing when they shouldn't). Turning this feature on is recommended:

snowplow('enableLinkClickTracking', { pseudoClicks: true });

This is its signature (where ? is an optional property):

snowplow('enableLinkClickTracking', {
  options?: FilterCriterion,
  pseudoClicks?: boolean,
  trackContent?: boolean
  context?: SelfDescribingJson[]
});

The enableLinkClickTracking method only tracks clicks on links that exist when the page has loaded. If new links can be added to the page after then that you wish to track, use refreshLinkClickTracking. This will add Snowplow click listeners to all links which do not already have them (and which match the denylist, allowlist, or filter function you specified when enableLinkClickTracking was originally called). Use it like this:

snowplow('refreshLinkClickTracking');

Configuration​

Control which links to track using the FilterCriterion object.

Where FilterCriterion is an object:

interface FilterCriterion {
    /** A collection of class names to include */
    allowlist?: string[];
    /** A collector of class names to exclude */
    denylist?: string[];
    /** A callback which returns a boolean as to whether the element should be included */
    filter?: (elt: HTMLElement) => boolean;
}

You can control which links are tracked using the second argument. There are three ways to do this: a denylist, an allowlist, and a filter function.

Denylist​

This is an array of CSS classes which should be ignored by link click tracking. For example, the below code will stop link click events firing for links with the class "barred" or "untracked", but will fire link click events for all other links:

snowplow('enableLinkClickTracking', {
  options: {
    denylist: ['barred', 'untracked']
  }
});

// If there is only one class name you wish to deny,
// you should still put it in an array
snowplow('enableLinkClickTracking', { options: { 'denylist': ['barred'] } });

Allowlist​

The opposite of a denylist. This is an array of the CSS classes of links which you do want to be tracked. Only clicks on links with a class in the list will be tracked.

snowplow('enableLinkClickTracking', {
  options: {
    'allowlist': ['unbarred', 'tracked']
  }
});

 // If there is only one class name you wish to allow,
 // you should still put it in an array
snowplow('enableLinkClickTracking', { options: { 'allowlist': ['unbarred'] } });

Filter function​

You can provide a filter function which determines which links should be tracked. The function should take one argument, the link element, and return either 'true' (in which case clicks on the link will be tracked) or 'false' (in which case they won't).

The following code will track clicks on those and only those links whose id contains the string "interesting":

function myFilter (linkElement) {
  return linkElement.id.indexOf('interesting') > -1;
}

snowplow('enableLinkClickTracking', { options: { 'filter': myFilter } });

Another optional parameter is trackContent. Set it to true if you want link click events to capture the innerHTML of the clicked link:

snowplow('enableLinkClickTracking', { trackContent: true });

The innerHTML of a link is all the text between the a tags. Note that if you use a base 64 encoded image as a link, the entire base 64 string will be included in the event.

Each link click event will include (if available) the destination URL, id, classes and target of the clicked link. (The target attribute of a link specifies a window or frame where the linked document will be loaded.)

Context

enableLinkClickTracking can also be passed an array of custom context entities to attach to every link click event as an additional final parameter.

Link click tracking supports dynamic context entities. Callbacks passed in the context argument will be evaluated with the source element passed as the only argument. The self-describing JSON context object returned by the callback will be sent with the link click event.

A dynamic context could therefore look something like this for link click events:

let dynamicContext = function (element) {
  // perform operations here to construct the context
  return context;
};

snowplow('enableLinkClickTracking', { context: [dynamicContext] });

See this page for more information about tracking context entities.

You can manually track individual link click events with the trackLinkClick method. This is its signature:

snowplow('trackLinkClick, {
    /** The target URL of the link */
    targetUrl: string;
    /** The ID of the element clicked if present */
    elementId?: string;
    /** An array of class names from the element clicked */
    elementClasses?: Array<string>;
    /** The target value of the element if present */
    elementTarget?: string;
    /** The content of the element if present and enabled */
    elementContent?: string;
});

Of these arguments, only targetUrl is required. This is how to use trackLinkClick:

snowplow('trackLinkClick', {
  targetUrl: 'http://www.example.com',
  elementId: 'first-link',
  elementClasses: ['class-1', 'class-2'],
  elementTarget: '',
  elementContent: 'this page'
});