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:

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

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

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.

Note:useAnchor is not supported for forms because IE v6 to v11
and Edge strip off anchors in forms.

decorate

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.

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.