How to track a single-page application

Available from version 12.0.0

There are two main design patterns for websites: a multi-page application and a single-page application (also called SPA). The first one works traditionally — every time a visitor goes from a page to a page, the page reloads in the visitor’s browser. The second one loads at the beginning of the visit, and then dynamically gets the data from the server as the visitor moves through the website, without the need for a page reload.

A multi-page application is easy to track because the tracking code loads each time a visitor changes a page. A single-page application is more difficult to track because, in most cases, the tracking code loads one time and doesn’t load again when a visitor explores the website.

So if we want to track a single-page application, we need to use a mechanism that will notice when a visitor changes a page and will send that information to Piwik PRO. For that, we’ll need a custom variable, a history change trigger, and a virtual page view tag.

A custom variable will help us get information about the page title.

A history change trigger will do an awesome job of firing the tag when a hash in the page URL changes or when the `history` object in the browser changes. So this trigger will notice changes that the tracking code can’t notice in single-page applications.

A virtual page view tag will capture and send information about the change to Piwik PRO. With its help, data about a page URL and page title will appear in the page report and the page title report.

Note: This method will work for single-page applications where the page URL changes and where the page URL fragment (aka hash) changes.

Set up tracking for a single-page application

To set up tracking for a single-page application, follow these steps:

  1. Go to Menu > Tag Manager.
  2. Navigate to Variables.
  3. Click + Create new variable.
  4. Name the variable Document title and click OK.
  5. In Variable type, select Document.
  6. A document variable in Piwik PRO.
  7. In Document name, type: title.
  8. A document variable in Piwik PRO.
  9. When you’re done, click Save.
  10. Navigate to Tags.
  11. Click + Create new tag.
  12. Name the tag, select the Piwik PRO Virtual Page View tag, and click Save.
  13. Add:
    • In URL: {{ Page Url }}
    • In Document Title{{ Document title }}
    • In Referrer URL: leave it blank
    Setting a virtual page view tag in Piwik PRO.
  14. In Tag triggers, click + New trigger.
  15. Name the trigger.
  16. In Event type, select History change trigger (SPA).
  17. History change trigger in Piwik PRO.
  18. In Trigger conditions, optionally adjust conditions. For more, see this article.
  19. Click Save for the trigger.
  20. Click Save for the tag.
  21. Test your tag in debug mode.
  22. When you’re happy how the tag works, click Publish.

View a report

After the tag starts to collect data from your single-page application, you’ll see it in reports. Each change will be reported as a page view with a page URL and page title.

To view a report, follow these steps:

  1. Go to Menu > Analytics (new).
  2. Navigate to Reports.
  3. On the left, click Pages.
  4. View the report.
A virtual page view in Piwik PRO.
Was this article helpful?

Technical Support

If you have any questions, drop us a line at

We’re happy to help!