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 (Piwik) 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 (Piwik) 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 may be two or more domains.

  2. Generate your JavaScript tracker code. In Administration > Websites > Tracking Code, click on “Advanced: Show” link, then check the option “Enable Cross Domain linking”. 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 (Piwik) you should see the following two lines:

    _paq.push(["setDomains", ["*.domain1.com", "*.domain2.com"]]);
    _paq.push(["enableCrossDomainLinking"]);
    
  4. 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 (Piwik) website.

  5. 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!

Advanced: Handling Dynamically Generated Links

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 (Piwik) 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.”).

Any questions?

Many answers and more information about Matomo you can find here:

We are social

Follow us: