Hotjar on Single Page Apps

Single Page Applications (SPAs) allow your users to browse different pages on your site without having to reload the page completely. In most cases, a SPA website will change the URL in the browser, even though the page is not being reloaded.

By default, Hotjar is usually able to detect and track these SPA URL changes automatically. However, if a user visits a new page on your SPA site and the URL doesn't change, or fragments are added to the URL that need to be tracked by Hotjar, then you may need to update your Hotjar settings to ensure that Hotjar will correctly track page state changes.

This article will discuss the following:

• Installing Hotjar on a Single Page Application
• What are the options for tracking URL changes?
• How do I adjust the settings for tracking URL changes?
• Troubleshooting tips for Single Page Applications

---

Installing Hotjar in Node.js

There is only one official Hotjar package created and maintained by our developers. It is called @hotjar/browser, and it’s available on NPM.

For full documentation on using the NPM package and some demonstrations of its features, please refer to our GitHub Page.

Back to top

What are the options for tracking URL changes?

There are three options available for handling URL changes:

• Track changes automatically, excluding fragments (default)
• Track changes automatically, including fragments
• Track changes manually

Track changes automatically, excluding fragments (default)

With this setting, Hotjar will monitor the URL address bar for changes to the page URL except for fragments or query strings.

For example, if a user went from www.example.com > www.example.com/about Hotjar would count this as a page change. If the user went from www.example.com to www.example.com#heading1 Hotjar would not track this as a change.

Track changes automatically, including fragments

Many sites use fragments (represented by a # character) to display page state changes. This is common with Single-Page Applications (SPAs).

For example, let's say you had an app that represented different pages with a fragment. The URL may look something like app.example.com#profile. By default, Hotjar wouldn't recognize moving to #profile as a URL change. In this case, you would want to select Track changes automatically, including fragments.

Both of the following changes would be tracked using this setting:

• www.site.com/page/ -> www.site.com/another-page/
• www.site.com/#page -> www.site.com/#anotherpage

Track changes manually

Some Single-Page Apps do not change the URL address bar at all but still have distinct pages. In this case, you will need to manually instruct Hotjar when a route change has happened using events you pass to Hotjar using JavaScript.

With this option selected, Hotjar will register these JavaScript events as page changes. It will also still continue to track URL changes from page reloads

Below are a few examples of the code snippet needed to generate a manual page change. Each page path should be unique, based on which 'page' is being shown to the user:

hj('stateChange', 'example/page1');
hj('stateChange', 'example/page2');
hj('stateChange', 'example/path/pageA');

The code will need to be added to any page that is considered a new page in your application's routing code. The second argument can be a relative or full URL.

Manual state changes should be compatible with any front-end JavaScript library. Here is an example of the code in AngularJS (1.X) ui-router:

angular.module('yourApp', []).run([
    '$rootScope',
    function ($rootScope, ...) {
        ...

    // Sets up the router to report state changes to the Hotjar script. 
        $rootScope.$on('$stateChangeSuccess',function () {
            hj('stateChange', $location.url());
        });
        
        ...
    }
]);

The above code is only an example. Since different SPAs are built with different frameworks, it's not possible to share example code for all possible sites. We recommend working with a developer to implement any code changes on your website.

Back to top

How do I adjust the settings for tracking URL changes?

The steps outlined below show how you can update the 'Tracking URL Changes' settings.

Click on Settings, then Sites & Organizations.

Click the settings cog icon to open the Site settings for the Site you would like to change.

Under Session targeting & tracking, select the tracking option that works best for your site.

Click Save Changes.

Back to top

Troubleshooting tips for Single Page Applications

Almost all issues that occur on Single Page Application (SPA) sites are solved by one or more of the following solutions:

• Send state changes manually to Hotjar and switch URL tracking to Track changes manually.
• When using Events or User Attributes for targeting, send the Event or User Attribute on every route where you want it to take effect (a route is essentially the same as a 'page' on SPAs).
• When using any sort of automatic URL tracking, be sure to target your tools based on URLs only (instead of targeting based on Events or User Attributes), or do one of the steps above.
• Consider using the Track changes automatically, including fragments setting if your site uses fragments or queries for URL changes. This is especially important when including those queries/fragments in your targeting criteria.

Back to top