How to track a single-page application

Analytics + Tag Manager

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 Add new variable.
  4. Name the variable Document title and select the following type: Document.
  5. In Document name, type: title.
  6. When you’re done, click OK.
  7. Navigate to Tags.
  8. Click Add new tag.
  9. Name the tag, select the following type Piwik PRO virtual page view.
  10. Click Next.
  11. Add:
    • In URL: {{ Page Url }}
    • In Document Title:  {{ Document title }}
  12. In Tag triggers, click Add new trigger.
  13. Name the trigger.
  14. In Event type, select History change trigger (SPA).
  15. Keep Wait 1 second before firing the tag turned on. It helps to match page URLs with page titles in single-page applications.
  16. In Event conditions, optionally adjust conditions. For more, see this article.
  17. Click OK.
  18. Click Save for the tag.
  19. Test your tag in debug mode
  20. When you’re happy how the tag works, click Publish.

Alternative setup for slow-loading sites

If your single-page application loads the first page slowly, page titles for this page can be inaccurate. We recommend that you set up a manual page view tracking for your single-page application instead.

To set up manual page tracking, follow these steps:

  1. Go to Tag Manager > Tags.
  2. On the left, choose the following tag: Piwik PRO tag.
  3. Turn on Don’t track page views.
    Don't track page views in Piwik PRO
  4. Click Save.
  5. Navigate to Variables.
  6. Click Add new variable.
  7. Name the variable Document title and select the following type: Document.
    Document variable in Piwik PRO
  8. In Document name, type: title.
    Document variable in Piwik PRO
  9. When you’re done, click OK.
  10. Navigate to Tags.
  11. Click Add new tag.
  12. Name the tag and choose the following type: Custom asynchronous tag.
  13. Click Next.
  14. In Tag code, add the following code:
    <script>
    setTimeout(function() {
      _paq.push(['setCustomUrl', {{ Page Url }}]);
      _paq.push(['setDocumentTitle', {{ Document title }}]);
      _paq.push(['trackPageView']);
    }, 1000);
    </script>

    In this code, you can change the following parameters:

    • 1000 // This is the timeout value in milliseconds. Adjust it to the loading time of your site.
  15. In Tag triggers, click Add new trigger.
  16. Name the trigger.
  17. In Event type, select History change trigger (SPA).
    A history change trigger in Piwik PRO
  18. Keep Wait 1 second before firing the tag turned on. It helps to match page URLs with page titles in single-page applications.
  19. Click OK.
  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.
  2. Navigate to Reports.
  3. On the left, click Pages.
  4. View the report.

Was this article helpful?

Technical support

If you still have some questions, visit our community.
There’s always someone ready to help!

Related articles

Back to help center