How do I accurately measure the same visitor across multiple domain names (cross domain linking)?

Cross domain tracking makes it possible for Matomo (Piwik) to record the same visitor on two related websites, for example an Ecommerce website and a separate shopping cart website, as a single visit.

Why is setting up cross domain needed for accurate visitor tracking across domains? Matomo uses a visitor ID to record visit data. Visitor ID values are stored in cookies on the web domain of the visit. These cookies are first party cookie and can only be accessed on the specific domain name that they were created, so other domain names cannot access these cookies and the visitor ID. So when you need to track your visitors across different domains, the visitor ID must be forwarded from one domain to the other domain using a special mechanism which we call Cross domain linking, described in detail below.

To setup accurate cross domain tracking, follow these steps:

  1. Configure your domain names as Alias URLs for your Matomo website. Login to Matomo and click on Administration > Websites > Manage. Edit your website, and specify all your domain names in the Alias URLs field. There must be two or more domains for cross domain to work.

  2. Generate your JavaScript tracker code. In Administration > Websites > Tracking Code, click on “Advanced: Show” link, then check the option “Enable Cross Domain linking” (If this checkbox is not clickable, please check you have defined at least two Alias URLs for this website). This will also automatically check the box “In the ‘Outlinks’ report, hide clicks to known alias URLs”.

  3. Check your generated JavaScript tracker code is valid. In the generated Tracking code in Matomo you should see the following two lines:

    _paq.push(["setDomains", ["*.domain1.com", "*.domain2.com"]]);
_paq.push(["enableCrossDomainLinking"]);

Please note that cross domain linking won’t work when cookies are disabled.

  1. Paste this JavaScript tracker code into all your websites to be measured across domains. In the example above, you need to add the JavaScript tracker code to domain1.com and domain2.com. It is important to add the code to all your domains specified as Alias URLs on your Matomo website.

  2. Check that the Cross Domain linking is working correctly. Go to your domain1.com and click on a link to your domain2.com. If Cross Domain linking is enabled and working, the URL of domain2.com will contain a new parameter &pk_vid=. This pk_vid parameter will contain a string of data which includes the Visitor ID. This way the current visitor ID is forwarded to the page of the different domain. Similarly when a user clicks from domain2.com to domain1.com, the domain1.com URL will also have this new pk_vid parameter.

You have successfully configured Cross Domain linking: congratulations!

Tag Manager Instructions

To setup cross domain tracking using Tag Manager, follow these steps:

1/ Enable Cross Domain Linking
Login to Matomo and click on Tag Manager > Variables and edit the Matomo Configuration variable.
Scroll down the page and tick the option to enable Cross Domain Linking.


tagmanager-cross-domain-linking


2/ Add the domain names to include in your Cross Domain Linking
While still editing the Matomo Configuration variable. Scroll down to the “Domains” section and specify all your domain names in the available fields you want to include. Once the changes have been made, click the Update button to save.
tag-domain-alias


3/ Paste the Tag Manager Tracking code into your websites
You can find the Tag Manager tracking code from Tag Manager > Install Code.
The Tag Manager tracking code needs to be added to all the websites you have listed within the “Domains” section of your Matomo Configuration variable in step 2.

4/ Check that the Cross Domain linking is working correctly
Go to your domain1.com and click on a link to your domain2.com. If Cross Domain linking is enabled and working, the URL of domain2.com will contain a new parameter &pk_vid=. This pk_vid parameter will contain a string of data which includes the Visitor ID. This way the current visitor ID is forwarded to the page of the different domain. Similarly when a user clicks from domain2.com to domain1.com, the domain1.com URL will also have this new pk_vid parameter.

You have successfully configured Cross Domain linking in Tag Manager: congratulations!

Note: the feature below is available since Matomo 3.3.1.

The cross domain detection feature works by adding the pk_vid query parameter to every link on the page when it is loaded. This is only done once, so if your webpage or webapp adds links dynamically to the page through JavaScript, they will not have this query parameter added to the URLs.

This doesn’t mean cross domain detection for such links is impossible, but it does mean you’ll have to do a little more work.

First, in your JavaScript that generates the link, get the pk_vid=... query parameter to use by calling the Matomo tracker’s getCrossDomainLinkingUrlParameter method:

var crossDomainQueryParam;
_paq.push([ function() { crossDomainQueryParam = this.getCrossDomainLinkingUrlParameter(); }]);

Then make sure this value is appended to the link URL:

// NOTE: this example uses jquery, which you may not use in your website/webapp.
//       how you add the query parameter will depend on how your link is generated.
var $linkToAdd = $('<a>my new link</a>')
    .attr('href', 'http://myotherdomain.example.com/page.html?' + crossDomainQueryParam);

$('body').append($linkToAdd);

Notes:

  • You can add the query parameter to the link at any time, as long as it is added before it is clicked/visited.
  • You need to append the query parameter to all links on domain1.com going to domain2.com, and on all links on domain2.com linking to domain1.com (see the list item 5. above: “Check that the Cross Domain linking is working correctly.”).

Goal funnel conversion across multiple domains

When you enable cross-domain tracking using the instructions above, you’ll be able to track your conversion funnels and funnel steps across your multiple domains.

A/B tests across domains

When running an A/B test, you can only run it on one domain. It won’t work to run an A/B test on multiple domains (because the A/B test variations are stored in the local storage or first party cookies on the domain, and are not shared across domains).

However you can still use cross-domain tracking with A/B testing when for example you run a A/B test on one of the domains, and on another domain you trigger Goal conversions. The A/B test will be able to use these cross-domain goal conversions into account in the calculation of the A/B test’s success metrics.

Cross-domain tracking and Roll-Ups

When you create a Roll-Up and aggregate several websites together, it is not possible to use cross-domain tracking. Cross-domain tracking only works within one Website in Matomo (one Website having multiple domain names).

Previous FAQ: Tracking mini-sites separately to give users specific permissions