Cross-domain tracking with gtag.js

Cross-domain tracking makes it possible for Analytics to see sessions on two related sites (such as an ecommerce site and a separate shopping cart site) as a single session, rather than as two separate sessions. This is sometimes called site linking, and this technique is useful when you wish to track the entire customer journey more effectively.

Google Analytics generates a unique client ID to determine whether a user is new or returning. A user is considered returning if a hit with a matching client ID has already been sent to the same property.

Cross-domain tracking works by sharing the client ID between a source domain and a destination domain. The client ID is stored in the browser's cookies, which means it can only be accessed by pages on the same domain. If you own multiple domains and would like to treat them as a single property, you need to find a way to share a client ID across all domains you want to track.

Sharing the client ID between domains 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.

Cross-domain tracking with gtag.js 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, when a value is configured for the domains property of the linker parameter, gtag.js will check for linker parameters in the URL. If the linker parameter is found and is valid, gtag.js extracts the client ID from the parameter and stores it.

Enabling cross-domain tracking with gtag.js allows automatic and manual adding of the linker parameter to URLs in links and forms on the page.

To set up automatic cross-domain tracking on the source domain for URLs pointing to the destination domain, configure the domains property of the linker parameter in your property's config.

When configured and running, gtag.js will listen for selections on links that point to the destination domain (or domains), and it will automatically 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.)

If you have forms on your site pointing to the destination domain, set the optional decorate_forms property of the linker parameter to true.

For example, this code will append the linker parameter to any links on the page that point to the target domain 'example.com':

gtag('config', 'GA_TRACKING_ID', {
  'linker': {
    'domains': ['example.com']
  }
});

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, gtag.js needs to know to look for that parameter.

If the destination domain has been configured to automatically link domains, it will accept linker parameters by default.

If the destination domain is not configured to automatically domains, you can instruct the destination page to look for linker parameters by setting the accept_incoming property of the linker parameter to true on the destination property's config:

gtag('config', 'GA_TRACKING_ID', {
  'linker': {
    'accept_incoming': true
  }
});

Bi-directional cross-domain tracking

"Single-directional cross-domain tracking" occurs when the user flow is tracked only from one domain to the other. For example: the user starts at example-source.com and winds up at example-destination.com. 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 either the source or the destination. To implement bi-directional cross-domain tracking, enable auto linking on both domains and configure them both to accept linker parameters and automatically link domains.

On source.com, update the property's config:

gtag('config', 'GA_TRACKING_ID', {
  'linker': {
    'domains': ['example-destination.com']
  }
});

On destination.com, update the property's config:

gtag('config', 'GA_TRACKING_ID', {
  'linker': {
    'domains': ['example-source.com']
  }
});

Using a single snippet on all domains

To simplify bi-directional cross-domain tracking further, you can list all possible domains you want to track in the domains property of the linker parameter of property's config for each domain, allowing you to use the same snippet of code on every domain:

On example-1.com, update the property's config:

gtag('config', 'GA_TRACKING_ID_1', {
  'linker': {
    'domains': ['example-1.com', 'example-2.com']
  }
});

On example-2.com, update the property's config:

gtag('config', 'GA_TRACKING_ID_2', {
  'linker': {
    'domains': ['example-1.com', 'example-2.com']
  }
});