Troubleshoot page overlay issues

1. It doesn’t work at all

  • Make sure the page you want to view in Page Overlay has the Matomo (Piwik) tracker code on it.
  • If you use Browser extensions to block scripts such as Adblock plus or Ghostery, disable them when using Overlay feature. Similarly make sure your browser passes the Referrer field (some extensions or browser settings can disable this).
  • If other JavaScript code in your website contains errors, the Page Overlay Java Script might not work.
  • Maybe your website uses jquery in a very old or hacked version. Page Overlay uses jquery and if it detects that your website is already using it, it will try to use your implementation.
  • If you get an error “Refused to display ‘https://example.com/’ in a frame because it set ‘X-Frame-Options’ to ‘deny’.”, then your website sends the HTTP header X-FRAME-OPTIONS to SAMEORIGIN (or DENY) and this prevents Matomo from iframing your website for the Overlay report. To fix this problem, on your website(s) do not send the X-FRAME-OPTIONS HTTP Header.
  • Showing the sidebar requires the page to be opened in a frame. If your website has a frame buster, that will break Page Overlay. But you can still use it without the sidebar by using the config option overlay_disable_framed_mode.
  • Page Overlay depends on the Transitions plugin. That means that Overlay only works if Transitions is enabled too. (Obviously, the Overlay plugin needs to be enabled too.)
  • Page Overlay tries to load scripts and data from the URL you pass to the Matomo tracker. If you have a restrictive mod_proxy setup or there’s another reason why this doesn’t work, use the method setAPIUrl(apiUrl) of the Matomo tracker to let it know from which URL it should load the scripts and the data. The parameter apiUrl has to point to the root directory of piwik, e.g. http://piwik.example.org/ or https://example.org/piwik/. The call to setAPIUrl has to be made before calling trackPageView.

Since redirects are not tracked in Matomo, links that point to URLs that will redirect to a different URL can’t be annotated in Page Overlay. The most common case when this happens is when a navigation includes a category that shows a submenu after clicking it and redirects to the first subcategory.

3. I get the error “The Page Overlay session couldn’t be launched yet”

Usually, the website notifies the sidebar of its location. This error means that the notification is not sent.
Possible causes are:

  • If Matomo is currently loaded over SSL, Page Overlay will try to load the website over SLL too. If your website doesn’t support https, that is your problem. You can use Matomo over http and the website will be loaded over http as well.
  • The page you open in Page Overlay needs to have the Matomo tracker in it.
  • If the page you want to view in Page Overlay contains a redirect, the session can’t be launched.

4. I have multiple domains and it doesn’t show all data

Matomo Page Overlay can handle URLs with http or https and with or without www. If you have different domains, it will record the pages as different actions and Page Overlay will only show you the following pages for one domain. To avoid this, you can use the Java Script tracker method setCustomUrl() to track pageviews for only one domain by replacing alias domains with the main domains in Java Script.

5. I have a high traffic website and it takes a long time until the bubbles appear

If you see “loading following pages…” in the lower right for a long time, that means that your Matomo server can’t find the following pages quickly. To find these pages, Overlay uses the Transitions in the background. Therefore, speeding up Transitions is identical to speeding up Page Overlay.

To solve your problem, please take a look at the FAQ about speeding up Transitions.