Unblu Floating JS API

Unblu Floating JS API

The Floating JS API is an optional add-on to the Unblu Floating UI site integration. It allows JavaScript access to the local floating Unblu integration.

Introduction

The Floating JS API allows you to load, access, and control Unblu within your website. The API directly accesses and communicates with the loaded Unblu code. Any interaction with the API is reflected in the Unblu Floating visitor UI. For example, if a conversation is opened via the API, it will also be visible in the visitor UI.

For security reasons, the JS API can only ever do things the current visitor has the right to do. For example, if a visitor is allowed to end a conversation, this may be done via the API. If they aren't, an API call to end the conversation will fail with an error.

The Floating JS API is intended for actions directly connected to the current visitor and their use of the Unblu UI. This includes things like automatically starting a conversation, or starting a call within a conversation that the visitor is already part of.

For actions that require rights beyond those the local visitor has, or that should be independent of the visitor's UI, consider using the Unblu WebAPI, either directly in JS or via custom REST services provided by your own server.

Integrating Unblu on a website

In general, the Floating Visitor UI may be integrated into a website in three different ways:

  1. Snippet only: The Unblu snippet script is added to the head of the website. In this case this API isn't present and can't be used.
  2. JS API only: The API script is added to the head of the website. When the API is initialized it loads the snippet and other parts of Unblu.
  3. Snippet and JS API: Both the snippet and the Unblu API are added to the header of the website. This is great if you always want to have Unblu loaded but don't always want to use the API. Here the API connects to a loaded Unblu integration.

Integration with Floating Visitor UI

In some integrations (especially on SPAs), it may be useful or desirable to integrate both the floating and the embedded visitor UI, depending on a visitor's location on your website. When using the unblu-embedded-app component together with the Unblu Floating UI without re-loading the webpage, you must integrate the Unblu Floating UI using the Floating JS API. Furthermore, you should not inject the Unblu snippet into the webpage - using the Secure Flow Manager, for example - as this would lead to a double injection.

When both JavaScript libraries are included on a page, they can detect each other and de-initialize the other one during their own initialization. If Unblu is integrated with the Floating JS API on some pages, and with the embedded component on others, when the visitor navigates to a page with the Unblu embedded component, the component will detect the floating integration and deinitialize it. Conversely, if the visitor navigated back to a page with the Floating JS API, the embedded component would be detected and deinitialized.

Installation

The Unblu Floating JS API can either be included as a global script or can be loaded into a bundler.

Global scope

Simply add the script tag to the head of your website.

<script src="<unblu-server>/unblu/js-api/v7/floating/floating-api.min.js"></script>
<script>
//After the api script has been loaded it may be accessed in the global scope
window.unblu.api.initialize().then(api => {
// use the api
});
</script>

Adding type definitions to the IDE

For better integration in IDEs, like type safety, auto-completion (IntelliSense) and in-line documentation, the Unblu Floating JS API provides full type definitions. The latest typedef file can be found in the public cloud under:

https://unblu.cloud/unblu/js-api/v7/floating/floating-api.d.ts

Alternatively, you can obtain it from your local server at:

https://<unblu-server>/unblu/js-api/v7/floating/floating-api.d.ts

IDEA WebStorm
  1. Download the typedefs and store them locally
  2. Open the WebStorm Project and go to: Preferences -> Languages & Frameworks -> JavaScript -> Libraries
  3. Press Add...
  4. In the dialog, give the library a name, e.g. unblu-floating-api
  5. Add the downloaded typedefs as file using the (+) button.
  6. WebStorm will now give you all the typedef features when accessing window.unblu.api
Microsoft VSCode
  1. Download the typedefs and store them locally
  2. Add a new folder typings to you JavaScript project
  3. Copy the downloaded typedefs to the folder.
  4. VSCode will now give you all the typedef features when accessing window.unblu.api

Using the API with a bundler like webpack and npm

Install the floating-js-api as a dependency using node package manager (npm). In your project, execute the following command which will install the floating-js-api and add it to the package.json file as a dependency.

npm install --save @unblu/floating-js-api

The floating-js-api's version is synchronized with the Collaboration Server version. To guarantee compatibility between the two, use the latest JS library version that is either equal to or smaller than the Collaboration Server version you are using.

Once installed you can use it like so:

import unblu from "floating-js-api";

const api = await unblu.api.initialize();
// use the visitor API

The typedefs provided with the library will automatically be used by the local IDE (VSCode and WebStorm).

Usage

Configuration & initialization

You must configure (if the snippet hasn't been added to the page) and initialize the API before you can use it. See UnbluStaticApi for more details.

Central classes

Once the API has been initialized, the UnbluApi will be returned. This is the central class for all high level API actions.

Some methods of the UnbluApi resolve to a Conversation, which provides access to the functionality specific to this conversation. Keep in mind, however, that a conversation can only be accessed as long as it is also displayed in the UI. If the visitor decides to navigate away from the conversation, it won't be accessible by the API anymore until it is re-opened, either via API or manually by the visitor.

Error handling

Whenever an API call fails, the Promise returned by the API will be rejected with an UnbluApiError. Use the error's UnbluApiError.type and UnbluApiError.detail to get more information on its cause.