When you are using Usabilla for Websites on a web page which is a Single Page Application you’ll need to add some code to the default Usabilla Installation snippet to take full advantage of all the additional targeting options that can be added to Single Page Applications. This article outlines how you get the most of your Usabilla for Websites targeting when you have a Single Page Application (SPA).
Preparing your SPA
First, it is good to have a common understanding of what a SPA is. A SPA is defined as web pages on websites where the content is loaded dynamically without a traditional full page load.
A Single Page Application (SPA) is a website that loads all of the resources required to navigate throughout the site on the first page load. As the user clicks links and interacts with the page, subsequent content is loaded dynamically using AJAX for example.
It is considered a best practice that the web page updates the URL in the browser bar to emulate traditional page navigation. Although the URL is updated a new full page load will not happen within a SPA.
Similar to many other technologies like tag managers and analytics codes, the default Usabilla installation snippet is optimized for the use with traditional websites where the whole page is loaded when the user navigates through pages. Many functionalities are based on the premise that the snippet code is run every single time the user loads a new page. However, for websites where you have a single page application the site loads the content of a page dynamically without a full page load.
As you are probably aware this has consequences for software with features that depend on code being loaded every single time the user interacts with the website. This is also the case for Usabilla, which means for example that page views must be tracked manually as new content is loaded and that some Usabilla targeting options don’t work as expected.
Adding the SPA code
To make sure that you have all the targeting options when your website is a SPA we’ve created a small piece of JavaScript that adds additional targeting options to your Usabilla installation when your website is a SPA. You add the code in a separate <script> tag that is executed after the normal Usabilla code.
// Variables used globally for storing the values
var customObj = {};
var customObjString = "";
var searchString = "";
var searchStringClean = "";
var fullUrl = "";
var cleanUrl ="";
var pageCounter = 0;
var fragmentString = "";
/** EXECUTED ON LOAD
* Use the updateUsblCustomVar function for the inital:
* - updating of Custom Variables
* - adding of variables to the customObj
* - sending of the customObj to Usabilla
* Add EventListener to window to check the hash for any changes
*/
updateUsblCustomVar();
window.addEventListener("hashchange",updateUsblCustomVar());
/**
* Function that updates the custom variables when the hash of the browser changes.
* http://caniuse.com/#search=hashchange
* Browser Support for Hashchange : IE8 and up, Chrome all versions , Firefox all versions, Safari all versions.
*/
function updateUsblCustomVar() {
if (fullUrl === window.location.href) {
return;
}
searchString = window.location.search;
searchStringClean = searchString.replace("?", "");
customObjString = searchStringClean.split("&");
fullUrl = window.location.toString();
cleanUrl = fullUrl.replace(window.location.search, "");
fragmentString = window.location.hash.substring(1);
for (i = 0; i < customObjString.length; i++) {
var param = customObjString[i].split("=");
if (!param || !param[0] || !param[1]){
continue;
}
var paraName = param[0].valueOf();
var paramValue = param[1].valueOf();
customObj[paraName] = paramValue;
}
pageCounter++;
customObj.pageCount = pageCounter;
customObj.fragment = fragmentString;
customObj.page = cleanUrl;
customObj.pageFull = fullUrl;
window.usabilla_live('data', {
'custom': customObj
});
}
The additional code works on the premise that you update the URL in the browser bar to emulate traditional page navigation. When you change the URL in the browser bar an onHashChange event occurs that allows us to track any changes on the page. When a change occurs the additional code sends several values of the page as Custom Variable to Usabilla. Using Custom Variables to send data to Usabilla allows the rechecking of values without reloading the whole Usabilla button.
Parameters
The SPA code by default checks any parameters that you have in your web pages URL. If you have any additional parameters that you want to send to Usabilla you’ll need to create them and add them. The SPA code also tracks the amount of page clicks that session, the base URL, and the full URL. These targeting options do not require any additional setup from you as a Usabilla user.
If you’re not using any URL parameters we advise that you send Custom Variables using a Tag Manager with a Data Layer to add similar targeting to your SPA. More information about using a Data Layer can be found here.
Setting up a Campaign in SPA
Since we’re sending most of the data that is used for targeting using the Custom Variables functionality you’ll need to take this into account when setting up a campaign. When setting up a Usabilla Campaign on a SPA you will only be able to use a subset of the default targeting options. Most of the default targeting options will be moved to the Custom JavaScript Value Trigger option. Below you’ll find a short overview of the basic targeting option that uses the Custom JavaScript Value Trigger when using the SPA code:
- Any parameters that are found in the URL (name = searchString)
- Specific parameters (use your own defined parameter name)
- The Full URL (name = fullUrl)
- The domain (name = cleanUrl)
- The Page count (name = pageCounter)
To use these Custom JavaScript Value Triggers you simply add the name or the Custom Variable and the value that you want to use as targeting.
The other targeting options remain and are still available as they would normally. Do keep in mind that they still work based on the page load. This means for example that “time on page” targeting start counting as soon as the button is loaded instead of when the content changes in the SPA.
Checklist
To make your life a little easier we've compiled a checklist that you can use to check your web page before adding the Usabilla SPA code:
- Make sure that your Single Page Application updates the URL in the browser bar to emulate traditional navigation
- Make sure that you load the additional code after the Usabilla Snippet is loaded.
- Make sure that you either have your SPA parameters in the URL or have data available in the Data Layer
If you have any questions, feedback or suggestions, feel free to contact Usabilla Support. Do keep in mind that the SPA Code mentioned in this article is still in Alpha and that we cannot guarantee full support or official updates.