The linker plugin simplifies the process of implementing cross-domain measurement as described in the Cross-domain measurement guide for analytics.js.
Overview
Cross-domain measurement works by sharing a unique client ID between a source domain and a destination domain. This is a two step process:
- The source domain needs to ensure all URLs pointing to the destination domain contain the client ID of the source domain.
- 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.
autoLink
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 measurement
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 measurement. 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 measurement, where each domain is configured to work as the source or the destination.
To implement bi-directional cross-domain measurement, 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 measure 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']);