Linker

The linker plugin simplifies the process of implementing cross-domain tracking as described in the Cross-domain Tracking guide for analytics.js.

Overview

Cross-domain tracking works by sharing a unique client ID between a source domain and a destination domain. This is a two step process:

  1. The source domain needs to ensure all URLs pointing to the destination domain contain the client ID of the source domain.
  2. The destination domain needs to know to check for the presence of a client ID in the URL once a user navigates there.

The linker plugin accomplishes this by adding a linker parameter to URLs that point to the destination domain. The linker parameter contains the client ID as well as the current timestamp and browser metadata encoded within it. The timestamp and metadata are used to avoid problems with URL sharing.

The linker parameter will look something like this:

_ga=1.199239214.1624002396.1440697407

On the destination domain, the allowLinker field is provided, which when true instructs analytics.js to check for a linker parameters in the URL. If the linker parameter is found and is valid, it extracts the client ID from the parameter and stores it.

The Linker plugin allows both automatic and manual adding of the linker parameter to URLs in links and forms on the page. In most cases, the automatic way is recommended.

Automatically adding linker parameters

To set up cross-domain auto linking on the source domain for URLs pointing to the destination domain you must require the linker plugin and call its autoLink method.

The autoLink method can be called via the command queue.

Once run, analytics.js will listen for clicks on links that point to the destination domain (or domains) and add the linker parameter to those links immediately prior to navigation starting. Waiting until a user clicks a link to add the linker parameter is necessary because linker parameters expire after two minutes.

The optional decorateForms parameter should be specified and set to true if you have forms on your site that point to the destination domain.

Usage

ga('[trackerName.]linker:autoLink', domains, [useAnchor], [decorateForms]);

Parameters

Name Type Required Description
domains Array[RexExp|string] yes An array of strings or regular expressions to match against a URL's hostname indicating which domains auto linking should apply to. If a string is passed, analytics.js will perform a substring match, meaning example.com will match links pointing to blog.example.com.
useAnchor boolean no When true, the linker parameter will be added to the anchor portion of the URL rather than the query portion.
decorateForms boolean no When true, the linker plugin will add a linker parameter to form submissions that point to destinations matching the domain parameter.

Example

// Loads the Linker plugin
ga('require', 'linker');

// Instructs the Linker plugin to automatically add linker parameters
// to all links and forms pointing to the domain "destination.com".
ga('linker:autoLink', ['destination.com'], false, true);

Manually adding linker parameters

You can manually add the linker parameter to a particular <a> or <form> element via the decorate method. This method is only needed when not using the autoLink method described above.

decorate

The decorate method can be called via the command queue.

It's important to make sure the decorate method is called as close to when the navigation will occur as possible because linker parameters expire after two minutes. Most of the time this method should be called in an event handler.

Usage

ga('[trackerName.]linker:decorate', element, [useAnchor]);

Parameters

Name Type Required Description
element HTMLElement yes The <a> or <form> element to append the linker parameter to.
useAnchor boolean no When true, the linker parameter will be added to the anchor portion of the URL rather than the query portion.

Example

// Loads the Linker plugin
ga('require', 'linker');

// Gets a reference to a link pointing to an external domain.
var destinationLink = document.getElementById('destination-link');

// Adds click handler that decorates `destinationLink`.
destinationLink.addEventListener('click', function() {
  ga('linker:decorate', destinationLink);
});

linkerParam

In addition to the decorate method, you can manually get the linker parameter that a tracker will use via the linkerParam field.

ga(function(tracker) {
  var linkerParam = tracker.get('linkerParam');
});

Configuring a site to accept linker parameters

Once a user arrives at a page on the destination domain with a linker parameter in the URL, analytics.js needs to know to look for that parameter.

You can instruct the destination page to look for linker parameters by setting the allowLinker field to true when creating the tracker:

ga('create', 'UA-XXXXXX-X', 'auto', {
  'allowLinker': true
});

Bi-directional cross-domain tracking

A user flow where users always start on the source domain and only afterward move to the destination domain in considered single-directional cross-domain tracking. The instructions above assume this type of user flow.

In cases where it's not known which domain your users will visit first, you must implement bi-directional cross-domain tracking, where each domain is configured to work as the source or the destination.

To implement bi-directional cross-domain tracking, you enable auto linking on both domains and configure them both to accept linker parameters.

On source.com:

ga('create', 'UA-XXXXX-Y', 'auto', {allowLinker: true});
ga('require', 'linker');
ga('linker:autoLink', ['destination.com']);

On destination.com:

ga('create', 'UA-XXXXX-Y', 'auto', {allowLinker: true});
ga('require', 'linker');
ga('linker:autoLink', ['source.com']);

Using a single snippet on all domains

To simplify this further, you can list all possible domains you want to track in the autoLink method, allowing you to use the same snippet of code on every domain:

ga('create', 'UA-XXXXX-Y', 'auto', {allowLinker: true});
ga('require', 'linker');
ga('linker:autoLink', ['source.com', 'destination.com']);