SPA Wrapper for the Customer Scripts

Created by Seb Coulthread, Modified on Tue, 23 Apr 2024 at 09:43 PM by Seb Coulthread

Using the SPA wrapper will allow you to use Page Rules with SPA websites

By default, the customer scripts don't support SPA websites with page rules. At the time of writing, no suitable native API exists to inform us when a page changes in an SPA application, as a result, the page load rules only work effectively in an MPA.

We have a limited ability to handle SPAs using card rules, as these rules are evaluated differently to page rules, however, in some cases, it is more suitable for card rules to be used, or for existing application which migrate to an SPA, to prevent the need to rewrite the widget configuration, this wrapper can be used to handle SPAs.

Whilst this wrapper allows page rules to work with an SPA, we recommend consulting your account manager first to ensure it is suitable for your requirements.

Page Change Handlers

API Hook

The wrapper script works in two modes, the first is a push based method. This allows you to tell us the page has changed via an API method called "handlePageChange". This method would usually be hooked into the routing capability of your SPA framework. For example, if you were using Vue Router, you could hook into the "afterEach" method in the Vue Router, this hook would tell the widget to re-inspect the URL and reload the widget with the new config.

Automatic Page Change Detection

If you do not have the capability to inform us when the page changes, we can attempt to detect a page change. We do this by inspecting the current URL every second, and if it changes, we will trigger a reload of the config.

This wrapper includes the ability to include or ignore query parameters in a URL. For example, if you had a page whose content is loaded based on the query parameter, you'd want to enable this to ensure we track when the query parameter changes, however, if you don't need to track query parameters as different pages, please keep this setting disabled.

Implementation

Direct Script Import on Webpage

If you are including this script directly on the website, rather than via a GTM or other insertion solution, you may use the following script:

import('https://talkative-cdn.com/spa-wrapper/1.0.0/main.js').then(() => {
  window.talkativeAdvancedWidgetApi.init({
    loaderUuid: '1371f5fe-1828-4b5c-b106-c4d8a77f5997',
    region: 'eu',
    includeQueryString: true,
    detectPageChange: true,
  });
});

This script will import the wrapper, and then use the config to load and track page change.

loaderUuid	The loader uuid is the uuid extracted from your regular chat widget import script. The UUID alone should be copied here
region	The region here is likely to be either "eu", "us", or "au". If your solution was provided by one of our delivery partners, the region might be partner specific. Please note, the region is case-sensitive, incorrect casing or spelling will cause an error
includeQueryString	This parameter accepts a boolean entry of true or false. Set to true if you want the system to evaluate query parameters. If it is set to true, the query parameters will also be sent to the server, so can be used as part of page rules.
detectPageChange	This parameter accepts a boolean entry of true or false. When set to true, the script will track the URL and when it detects a change, it will reload the config. If this is set to false, you must implement the page change API hook, more details on this can be found below.

GTM Integration Guide

At the time of writing, GTM does not support ES6 modules such as import, as such, the code has to be modified to support a format it can parse. The following code will allow you to import the script in GTM.

<script>
(function() {
    var script = document.createElement('script');
    script.src = 'https://talkative-cdn.com/spa-wrapper/1.0.0/main.js';
    script.onload = function() {
        window.talkativeAdvancedWidgetApi.init({
            loaderUuid: '1371f5fe-1828-4b5c-b106-c4d8a77f5997',
            region: 'eu',
            includeQueryString: true,
            detectPageChange: true,
        });
    };
    document.head.appendChild(script);
})();
</script>

The script entry point in GTM expects HTML, so this script must be wrapped in script tags. The config options here are detailed in the above section.

Manually Triggering a Widget Update

If you choose to hook into your own routing system, you can trigger an update of the config by calling the following JS API method.

window.talkativeAdvancedWidgetApi.handlePageChange();

This will cause the script to check the current page it is on and reload the widget.

Considerations

When using the config to automatically detect and react to page changes, the script uses a timeout to track the current URL. This is due to a lack of native browser API to hook into. Our recommendation would be to link this to your own router and trigger page changes using that, however, we recognise that in some cases this will not be possible.

If an interaction is active, the config cannot be reloaded. The script will still attempt to run the code to change the config, however, the underlying widget will refuse to reload the script. This behaviour is intentional, as it will prevent any issues with the live interaction.