The embedded app API allows you to embed Unblu in your site as a web component instead of having the Unblu floating UI displayed over the website.
See UnbluEmbeddedAppElement for further information on the component API.
See UnbluEmbeddedApi for the API instance which you retrieve from the app element after initialization.
The typical scenario for the unblu-embedded-app component is that you have a dedicated page on your SPA or normal website where you want to integrate Unblu as the main content.
The unblu-embedded-app component defines a custom tag that you can add to the HTML of your webpage.
The JS code provided defines the web component including its tag along with attributes, properties, and functions.
Once it has been added to the DOM and configured, the app element automatically loads all of the JS needed to initialize its UI from the Unblu collaboration server.
The Unblu component API is meant to be used for actions directly related to the current visitor and their interaction with 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 security reasons, the API of the web component 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 not, an API call to end the conversation will fail with an error.
To use the unblu-embedded-app tag, you must first load the corresponding JavaScript library.
This can be done directly, integrating it as a script tag, or making it part of your ESM project in conjunction with a bundler such as webpack.
Both options are outlined in the sections below.
The easiest way to do load the JavaScript library for the unblu-embedded-app tag is to integrate it directly as a script tag.
<head>
<script src="<unblu-server>/unblu/js-api/v8/embedded/embedded-app-component.min.js"></script>
</head>
For better integration with your IDE, the unblu-embedded-app component API provides full
type definitions for IDE features such as type safety, auto-completion (IntelliSense), and in-line documentation.
The latest typedef file can be found in the Unblu public cloud:
https://unblu.cloud/unblu/js-api/v8/embedded/embedded-app-component.d.ts
The file is also included with your local Unblu server at the following location:
https://<unblu-server>/unblu/js-api/v8/embedded/embedded-app-component.d.ts
Now, WebStorm will offer you all of the typedef features when you access an UnbluEmbeddedAppElement.
typings folder to your JavaScript projecttypings folderNow, VSCode will provide you with all of the typedef features when you access an UnbluEmbeddedAppElement.
Another way of integrating the JavaScript code of the embedded-app-component is to bundle it into your existing JavaScript with a bundler, and then serve it all together with the webpage.
One such bundler is webpack.
Install the embedded-app-component as a dependency using node package manager (npm).
In your project execute the following command which will install the embedded-app-component and add it to the package.json file as a dependency.
npm install --save @unblu/embedded-app-component
The embedded-app-component's version is synchronized with the Collaboration Server version.
In order to guarantee compatibility between the two, please use the latest JS library version that is either equal to or smaller than the Collaboration Server version you are using.
To use the library in your code, import it:
import "@unblu/embedded-app-component";
The typedefs provided with the library will automatically be used by your local IDE (VSCode and WebStorm). If you use plain JavaScript with typedoc, you can do the following:
/**
*
* @type {HTMLCollectionOf<UnbluEmbeddedAppElement>}
*/
const appElements = document.getElementsByTagName("unblu-embedded-app");
In TypeScript, you can get the same result as follows:
const appElements = document.getElementsByTagName("unblu-embedded-app") as HTMLCollectionOf<UnbluEmbeddedAppElement>;
To integrate the embedded app component, place the custom tag at the desired location on your web page:
<body>
...
<unblu-embedded-app api-key="<API-KEY>"></unblu-embedded-app>
...
</body>
In order to load the Unblu UI in a unblu-embedded-app it must be configured and initialized, otherwise it will not show anything.
The minimum configuration that the Unblu Embedded Web Component needs is the Unblu API Key UnbluEmbeddedAppElement.ATTR_API_KEY/UnbluEmbeddedAppElement.apiKey. If the Unblu Collaboration Server isn't located in the same domain as the website it is integrated into, the attribute UnbluEmbeddedAppElement.ATTR_SERVER_URL or the property UnbluEmbeddedAppElement.serverUrl must also be set.
Once the configuration is done there are two ways of initializing and interacting with the embedded-app-component: automatic and manual mode.
While the automatic initialization is the best solution for simple integrations, the manual initialization allows more control and a broader API.
The automatic initialization mode is enabled by default UnbluEmbeddedAppElement.ATTR_AUTO_INIT/UnbluEmbeddedAppElement.autoInit. It only requires setting attributes on the web component's element and doesn't require any JavaScript interaction.
Automatic initialization is always triggered asynchronously. This way, the component can be configured completely without having to be re-initialized for each configuration parameter. You should therefore set the configuration attributes or properties before you set the API key, or in the same JavaScript event loop execution. If you don't, the component will be de-initialized and re-initialized several times, which creates unnecessary network requests and error messages in the logs.
Even if automatic initialization is enabled, the UnbluEmbeddedAppElement.initialize method can be called to retrieve the instance of the initialized UnbluEmbeddedApi for further API calls.
Alternatively it is possible to set the attribute UnbluEmbeddedAppElement.ATTR_AUTO_INIT, or the property UnbluEmbeddedAppElement.autoInit, to false and call the UnbluEmbeddedAppElement.initialize method manually.
The returned Promise will then resolve to the full UnbluEmbeddedApi of the web component.
Some methods of the UnbluEmbeddedApi resolve to a Conversation. This gives you access to functionality specific to this conversation. Keep in mind, however, that a conversation can only be accessed as long as it is displayed in the UI. If the visitor navigates away from the conversation, it won't be accessible by the API until it is re-opened, either via the API or by the visitor.
As many fields are properties, they directly throw errors of type UnbluApiError.
Some properties, however, trigger asynchronous actions, such as the initialization.
Where this is the case, we recommend you add a listener for the element's general error event.
In some integrations (especially on SPAs), it may be useful or desirable to integrate both the floating and the embedded 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 Visitor 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 Floating JS API is initialized while there is the embedded component, the embedded component would be detected and deinitialized.