Skip to main content

SPA Usage

Single Page Applications (SPAs) change content without full page reloads. Website Feedback supports SPAs in two ways:

Automatic handling – If you use an SPA router (e.g., History API), you can enable a toggle so Website Feedback automatically unloads and reloads intercepts on route changes. You typically do not need to use the APIs—Website Feedback handles it. See Single Page Application setup for details.

Manual control – The Web Feedback APIs let you unload, load, and run intercepts when the route or view changes. Use these when you need manual control (e.g., loading a different intercept on user action).

The rest of this doc covers manual control via the APIs.

Core APIs: unload, load, run​

MethodPurpose
QSI.API.unload()Removes all creatives and resets state. Use before loading intercepts for a new route.
QSI.API.load()Loads intercept scripts for the current page. Returns a Promise.
QSI.API.run()Evaluates targeting and displays creatives. Must be called after load().

Order of Execution​

The load() function is asynchronous and returns a Promise. Other JavaScript can run between load() and run(), which may delay when the intercept appears. To avoid race conditions where run() occurs before load() completes, chain them:

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

Example: Load Intercept on Tab Click​

This example loads an intercept only when the user clicks a "Feedback" tab in a sidebar:

var hasInterceptLoaded = false;

window.addEventListener("qsi_js_loaded", function() {
  if (QSI && QSI.API) {
    hasInterceptLoaded = true;
  }
});

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

function onFeedbackTabClicked() {
  if (hasInterceptLoaded) {
    QSI.API.unload();
    QSI.API.load().then(runIntercept);
  }
}

Best Practices for SPAs​

  1. Add the snippet to base index.html – When deploying to an SPA, add the Qualtrics snippet to the base index.html instead of loading it as a component.
  2. Unload before load – Call unload() before load() when switching to a new route or view to avoid stale creatives.
  3. Chain load and run – Use QSI.API.load().then(QSI.API.run) to avoid race conditions where run() occurs before load() completes.
  4. Check API readiness – Use the qsi_js_loaded event before calling any API methods.
  5. Pair with Session Recording – If using DXA Session Recording, see Pairing with Session Recording for SPA-specific behavior.

See Also​