The branch client app API allows you to embed Unblu Branch in your site as a web component.
See UnbluBranchClientAppElement for further information on the component API.
See UnbluBranchClientApi for the API instance which you retrieve from the app element after initialization.
The typical scenario for the unblu-branch-client-app component is that you have a dedicated page on your SPA or normal website where you want to integrate Unblu Branch as the main content.
The unblu-branch-client-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 Branch component API is meant to be used for actions directly related to the current visitor and their interaction with the Unblu Branch 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-branch-client-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-branch-client-app tag is to integrate it directly as a script tag.
<head>
<script src="<unblu-server>/unblu/js-api/v8/branch-client/branch-client-app-component.min.js"></script>
</head>
For better integration with your IDE, the unblu-branch-client-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/branch-client/branch-client-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/branch-client/branch-client-app-component.d.ts
Now, WebStorm will offer you all of the typedef features when you access an UnbluBranchClientAppElement.
typings folder to your JavaScript projecttypings folderNow, VSCode will provide you with all of the typedef features when you access an UnbluBranchClientAppElement.
Another way of integrating the JavaScript code of the branch-client-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 branch-client-app-component as a dependency using node package manager (npm).
In your project execute the following command which will install the branch-client-app-component and add it to the package.json file as a dependency.
npm install --save @unblu/branch-client-app-component
The branch-client-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/branch-client-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<UnbluBranchClientAppElement>}
*/
const appElements = document.getElementsByTagName("unblu-branch-client-app");
In TypeScript, you can get the same result as follows:
const appElements = document.getElementsByTagName("unblu-branch-client-app") as HTMLCollectionOf<UnbluBranchClientAppElement>;
To integrate the branch client app component, place the custom tag at the desired location on your web page:
<body>
...
<unblu-branch-client-app api-key="<API-KEY>"></unblu-branch-client-app>
...
</body>
In order to load the Unblu Branch UI in a unblu-branch-client-app it must be configured and initialized, otherwise it will not show anything.
The minimum configuration that the Unblu BranchClient Web Component needs is the Unblu API Key UnbluBranchClientAppElement.ATTR_API_KEY/ UnbluBranchClientAppElement.apiKey. If the Unblu Collaboration Server isn't located in the same domain as the website it is integrated into, the attribute UnbluBranchClientAppElement.ATTR_SERVER_URL or the property UnbluBranchClientAppElement.serverUrl must also be set.
Once the configuration is done there are two ways of initializing and interacting with the branch-client-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 UnbluBranchClientAppElement.ATTR_AUTO_INIT/ UnbluBranchClientAppElement.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 UnbluBranchClientAppElement.initialize method can be called to retrieve the instance of the initialized UnbluBranchClientApi for further API calls.
Alternatively it is possible to set the attribute UnbluBranchClientAppElement.ATTR_AUTO_INIT, or the property UnbluBranchClientAppElement.autoInit, to false and call the UnbluBranchClientAppElement.initialize method manually.
The returned Promise will then resolve to the full UnbluBranchClientApi of the web component.
Some methods of the UnbluBranchClientApi 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.