How can I track a single-page application (manual method)?

A traditional website (multi-page application) works in this way: every time a visitor goes from a page to a page, the page reloads in the visitor’s browser. A SPA (single-page application) 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.

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 a 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 a tag.
9. Name the tag, select the following type: Virtual page view.
10. Click Next.
11. Add:
    • In URL: {{ Page Url }}
    • In Document Title:  {{ Document title }}

    

12. In Tag triggers, click Add a 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 (tracking code).
3. Turn on Don’t track page views.
   

   

4. Click Save.
5. Navigate to Variables.
6. Click Add a variable.
7. Name the variable Document title and select the following type: Document.
   

   

8. In Document name, type: title.
   

   

9. When you’re done, click OK.
10. Navigate to Tags.
11. Click Add a tag.
12. Name the tag and choose the following type: Custom code (async).
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 a trigger.
16. Name the trigger.
17. In Event type, select History change trigger (SPA).
    

    

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.