Single Page Application

About Single Page Applications

Single Page Applications (SPA) are a special type of web app. An SPA will load a single page when you enter a website and, from that point on, load all content in that page. This will appear to work like a normal website, but when switching between “pages,” the page doesn’t actually reload.

By default, deployment code runs as soon as a web page loads. However, because SPAs don’t refresh when navigating between pages, you will need the ability to specify when the project deployment code is evaluated, typically after a specified event has occurred. By using JavaScript API requests to run or load your deployment code, you can control when deployment code is evaluated.

This page outlines alternative techniques to implement deployment code using JavaScript API requests, along with some other functionality.

Implementing Manually with JavaScript API

This first method outlines how to switch your deployment code to run manually.  This means that the deployment code won’t run or evaluate the associated logic until the appropriate JavaScript API request is initiated.

To implement manually

1. Navigate to the Settings tab.
   
2. Under the Manage Project dropdown, select Project Options.
3. Enable the Manually Load Project option.
   
4. Return to the Intercepts tab, and if desired, set logic to your Intercept or the Action Set.
   
5. Place the deployment code into your website, preferably in a global header or footer so that it loads on all pages.
6. Add the appropriate JavaScript API requests based on how many times you want your website to reference the Intercept. See section below for these requests.

JavaScript API Requests

If you want Qualtrics to evaluate your project in a single instance, use these two requests:

1. This request loads the deployment code for any Intercepts and Creatives on the page. The “load” API is the same as reloading a page that has code on it.

   QSI.API.load();

2. This starts the deployment code evaluation and will make any Creative appear if it passes the display conditions.

   QSI.API.run();

If you want Qualtrics to evaluate your project code more than once on the same page, repeat the following three steps each time:

1. This request removes the deployment code for any Intercepts or Creatives present on the page.

   QSI.API.unload();

2. This loads the deployment code for any Intercepts or Creatives on the page. This is the same as reloading the page.

   QSI.API.load();

3. This starts the deployment code evaluation and will make any Creative appear if it passes the display conditions.

   QSI.API.run();

Implementing Automatically with JavaScript API

Rather than manually running your deployment code on every webpage, you can select to have your deployment code automatically run on each webpage that it’s placed on. Then, if needed, you can use JavaScript API requests to Unload and Load your deployment code.  Using these requests, you can have logic reevaluated within a single web page. This method is outlined below.

If you are using this method within a single page environment, the deployment code will automatically run on the first page, but not on your subsequent “virtual” pages, until you use the Unload and Load JavaScript API requests.

TO IMPLEMENT AUTOMATICALLY

1. Place the project code into your website, preferably in a global header or footer so that it loads on all pages.
2. Return to the Intercepts tab, and if desired, set logic to your Intercept or the Action Set.
3. Unlike in the previous section, do not select the Manually Load option for the project!
4. Use the Unload and then Load JavaScript API requests.

QSI.API.unload();

This request removes the project deployment code for any Intercepts or Creatives on the page. This is the same as reloading the page.

QSI.API.load();

This request loads the project deployment code for any defined Intercepts or Creatives and will reevaluate your Intercept Display Logic.

A Note About JavaScript API Order of Events

The Website Feedback API functions do not run synchronously. This means that the unload, load, and run functions may not always run directly after each other. There is room between each function for other non-Website Feedback functions to execute. This can potentially add a delay between each event and it may take longer for the Intercept to appear.

If you execute one of the below functions, you can prevent other events from interrupting the process of displaying your Intercept. This will ensure the best experience for your website visitors.

QSI.API.load().then(QSI.API.run);

QSI.API.load().done(QSI.API.run);

QSI.API.load(QSI.API.run);

Adding an Event Listener to Your Code

Adding an event listener to your web page will allow you to specify a function to call once the project deployment code is loaded and QSI.API is available for use. When all the Website Feedback resources have finished loading from the Initial Snippet load only, an event will be sent off called qsi_js_loaded. A website developer can catch onto this event to notify their page that Website Feedback is ready to use. This will allow a developer to program code that triggers when the code is fully loaded. The syntax for this is shown below:

window.addEventListener("qsi_js_loaded", interceptLoaded, false);

In the following example, there is a function called interceptLoaded that is defined elsewhere in the JavaScript code for the Application. This is called when the event is fired. In interceptLoaded, you must first check if QSI is defined and if QSI.API is defined. If they are, this means that the code has loaded. You can then set a flag called hasInterceptLoaded to true so you know for the rest of the session that this Intercept has been loaded and loaded correctly.

function interceptLoaded(){
        if (QSI.API) {
    hasInterceptLoaded=true;
           } else {
    hasInterceptLoaded=false;
  }
}

Continuing this example, the Website Feedback user has a SPA with an imaginary Feedback tab in a Sidebar. We want to only load the Intercept when the Feedback tab is clicked. In your sidebar, you add an onclick event. The onclick event calls profileClicked() which will unload any Intercept that has already been loaded. This is useful if you have an Intercept on a different page that you don’t want to show when the visitor navigates to the feedback page. It then loads the Intercept for this page.

As you can see below, the load API call has done(runIntercept) appended to the end of it. This is where you can determine if the Intercept has finished loading or not. Once the Intercept is fully loaded (including dependency resolver), the function specified in the done() statement will run. In this example, you call runIntercept that will then run the Intercept using QSI.API.run.

function runIntercept(){
     if (hasInterceptLoaded) {
        QSI.API.run();
     }
  }

function profileClicked() {
     if (hasInterceptLoaded) {
        QSI.API.unload();
        QSI.API.load().done(runIntercept);
     }
  }

Intercept JavaScript API

The Qualtrics JavaScript API enables adding intercept-specific event listeners to enable triggering custom code in response to different intercept states. Currently these functions are only supported by intercepts using the Info Bar, Pop Over, and Responsive Dialog creative types.

Accessing the Intercept API

Using the Intercept API requires knowing the Intercept ID of the desired Intercept. The Intercept ID can be found by following the steps on this support page. Once the Intercept ID is known, use the asynchronous function QSI.API.getIntercept('your-intercept-id') to get a Promise that will resolve to the given intercept.

QSI.API.getIntercept('your-intercept-id').then(function (interceptAPI) {
  // Use the intercept API here
});

Registering an onClose callback

To register a callback that will run when an intercept is closed, use the interceptAPI.onClose function.

QSI.API.getIntercept('your-intercept-id').then(function (interceptAPI) {
  interceptAPI.onClose(function () {
    console.log('Intercept was closed!');
  });
});

It is also possible to register multiple onClose callbacks. The callbacks will be executed in the order they are added.

QSI.API.getIntercept('your-intercept-id').then(function (interceptAPI) {
  interceptAPI.onClose(function () {
    console.log('first close handler');
  });
  interceptAPI.onClose(function () {
    console.log('second close handler');
  });
});

Callbacks can also be removed after they’ve been added.

QSI.API.getIntercept('your-intercept-id').then(function (interceptAPI) {
  var removeHandler = interceptAPI.onClose(function () {
    console.log('first close handler');
  });
  // ...later
  // Remove the handler
  removeHandler();
});