How to integrate the Floating Visitor UI in single-page applications (SPAs)

Single-page applications (SPAs) have become increasingly widespread in the finance industry. However, integrating Unblu’s Floating Visitor UI in an SPA poses a number of challenges. If your customer navigates to a part of your SPA that uses a different API key, for example, or changes the language of the application, Unblu will not be aware of the fact without a page reload.

This article discusses the measures you must take to ensure that the Unblu UI works as your customers expect it to. It is aimed at developers tasked with integrating the Floating Visitor UI in customer-facing SPAs.

Background

The difficulties that arise when integrating Unblu in an SPA arise because Unblu works on the assumption that changes to configurational elements will result in a reload of the page the customer is on. In SPAs, however, this isn’t the case. Instead, the user remains on the same page, and the contents of the page are updated with data retrieved from the server, without reloading the page or transferring control to a different page.

Manual deinitialization and reinitialization

Since there are no page reloads in SPAs that would allow Unblu to update its settings as the result of a change, you must instead trigger a deinitialization and reinitialization of the Floating Visitor UI via the Visitor JS API when a user’s actions within your SPA require it.

Deinitialization

You deinitialize the Floating Visitor UI by adding the following call to your JavaScript code:

Listing 1. Deinitializing the Unblu Floating Visitor UI

unblu.api.initialize().then(initializedApi => {

    // ...
    initializedApi.deinitialize();
});

The call returns a Promise which is resolved once deinitialization is complete. At this point, Unblu can be reinitialized.

During deinitialization, the resources used by Unblu are cleaned up:

The normal UI is disposed of, as are any open popups or the like
Services, global JavaScript objects (typically on window.unblu), and DOM element listeners are removed
Cookies related to conversations and to recording are removed. Not all cookies are removed, notably the device cookie and the authentication cookie.
There is no further communication with the Unblu server:
- Polling for availability stops
- Comet polling stops
- Websockets are closed

The Unblu JavaScript is not removed from the page; doing so is not possible without navigation.

You can check the events DEINITIALIZING and DEINITIALIZED to ascertain whether the deinitialization process has completed. If you want to prevent the Unblu snippet being injected into the page again, you should remove any cookies that would result in renewed injection.

Since deinitialization requires a number of networking requests — to remove the cookies mentioned above, for example --, the process isn’t instantaneous. The performance impact on your SPA should, however, be minimal and not lead to noticeable degradation of the user experience.

Use cases for deinitialization

You should deinitialize Unblu in the following cases:

When a user navigates to a part of your SPA that results in changes to the configuration of Unblu, for examle:
- The user navigate to a part of the SPA that’s in a different named area, or that uses a different API key.
- The user changes the language in the SPA, and this change should be reflected in the Unblu UI.
Unblu is no longer required on the page because, say, the user and an agent have concluded a support session.

Reinitialization

Once you have deinitialized Unblu, you can reinitialize it if the circumstances require it, because of changes to the configuration — the named area or API key, for example. You will still have to call configure() with the appropriate parameter values.

Reinitialization uses the existing Visitor JS API method unblu.api.initialize(), which also returns a Promise. It reuses cached resources, interpreting the original JavaScript without loading it from the network again.

Resources that can’t be cached and files generated by the server such as visitor.js do have to be loaded from the network. This ensures that Unblu will always be using the latest version of the JavaScript, even if the Unblu server was updated in the meantime. Any changes to configuration and text properties will also be taken into account.