Documentation

Unblu 6 (latest)

This is the main Unblu documentation site.

In the following sections we will introduce you to the Unblu product suite, how it works and how to get started using it.

1. Introduction

1.1. Overview

Unblu is a software suite that lets agents and advisors at your firm engage and interact with your website visitors, customers or clients through multiple online channels, enabling a level of help, advice and relationship-building that was previously only possible face-to-face.

1.2. Why Unblu?

Unblu software is designed specifically with the requirements of financial institutions in mind.

  • Unlike most screen-sharing and co-browsing solutions, with Unblu, website visitors and clients never have to download any extra software to their computers. This greatly enhances security.

  • All communication channels are fully secured.

  • All data resides either on your own infrastructure or in a secure cloud in Switzerland, subject to Swiss financial data regulations.

1.2.1. Capabilities

With Unblu your agents and advisors can:

  • Provide help on-demand to website visitors through text chat, video and voice.

  • Securely conduct and keep track of long-running conversations and relationships with clients via text chat, video and voice through your website or through a dedicated mobile app.

  • Co-browse with website visitors and mobile app users, seeing what they see on their screen, providing valuable context when helping them navigate your website or other online resources.

  • Securely share documents with visitors and clients.

1.3. How does Unblu Work?

Unblu consists of a central software installation (the server) that handles the communication and collaboration between the various parties. The server can be installed on-premises or accessed as a cloud service.

1.3.1. Visitors

Visitors to you public website as well as known clients using web or mobile apps are connected through the server to agents and advisors at your firm.

1.3.2. Agents

Agents can use the built-in web app or custom mobile apps to interact with visitors. Unblu also enables supervisors to organize teams of agents and assign incoming visitor requests to area experts.

All aspects of both visitor- and agent-side interfaces are flexible and fully customizable, allowing integration with your existing web infrastructure while also enabling interaction though other channels such as custom mobile apps, custom web apps and external messenger services.

1.4. Basics

In this section we will discuss the basic concepts underlying the Unblu system and take a look at some of the key elements of the product.

1.4.1. Conversation

The central organizing concept within the Unblu system is that of the conversation. A conversation in Unblu refers to a communication/collaboration session between a visitor and an agent. A conversation may involve text chat, voice and video and co-browsing of websites and documents.

Depending on your specific use-case, a conversation may be short-lived, as between an anonymous website visitor and a support agent, or it may be long-running, as between a client and a trusted advisor. For more information see Conversations.

1.4.2. Visitor

In Unblu terminology visitor refers to any client, customer or potential customer that engages with your firm online. The term originates from the idea of a website visitor but we generalize this concept so that it can include:

  • Anonymous visitors to your public corporate site.

  • Signed-in users on your service site (for example, e-banking).

  • Clients with whom your representatives have long-running relationships.

1.4.2.1. Visitor Interface

The point of contact with the visitor is called the visitor interface. The default and most commonly used one is the Individual UI. This is a web component that comes out-of-the-box as part of Unblu. It is deployed by integrating its component code with your existing website. It can also be customized to suit your branding and the functionality you wish to expose.

The screenshot below depicts an example of an Unblu-enabled site. Notice that the site includes a launcher button in the bottom right corner:

screen visitor launcher

Clicking on the launcher button opens the Individual UI. From here the visitor can begin interacting with an agent at your firm. In this example we see the visitor using text chat to ask for assistance:

screen visitor need assistance

The Individual UI also supports video, voice and co-browsing. We will see how these work in later sections. In addition, Unblu also supports custom extensions to the Individual UI using the JS API, custom mobile apps built with the Visitor Mobile SDK and external messaging services via the External Messenger Integration. See Front End Interfaces and Integrations for more details.

1.4.3. Agent

The agent is the person who represents your firm and interacts with the visitor. This can be:

  • A help desk agent who assists website visitors on-demand.

  • An agent who engages with existing e-banking customers to provide information about products or processes at your institution.

  • A relationship manager who has an established relationship with a client and who periodically provides in-depth financial advice.

1.4.3.1. Agent Desk

The Agent Desk is the default interface that Unblu provides for agents. It is a conventional web app served by the Unblu server. Here we see that the message from the visitor appears in the queue of the agent desk, to wait for an agent to pick it up.

screen agent queue

An agent picks up the conversation from the queue and responds to the visitor.

screen agent how help

Here we see a text chat interaction. The Agent Desk also supports video, voice and co-browsing. We will see how these work in later sections.

In addition to the web-based Agent Desk, some agent-side task can be supported via custom mobile apps built with the Agent Mobile SDK. See also, Front End Interfaces and Integrations.

1.4.3.2. Teams and Supervisor

Agents can be organized into teams with specific people designated as supervisors. Supervisors manage teams and allocate incoming requests to area specialists. Unblu provides specific interfaces for these functions. For example, here we see the Agent Monitor part of the Agent Desk:

screen agent monitor
1.4.3.3. Administrators and Accounts

In addition to agents and supervisors, Unblu also defines the roles of administrator (or admin) and super-administrator (or super-admin).

A single Unblu installation can support multiple tenants or accounts. An admin is responsible for a single account and has rights to configure that account. A super-admin is responsible for the entire Unblu installation and has even more rights,relating to configuring and running the server as a whole.

Unblu provides interfaces for all of these configuration and administration tasks. (see Configuration). For example, here is the Account Settings page:

screen account settings

1.4.4. Text Chat

Text Chat in Unblu refers to the text-based messaging between visitor and agent provided by the Unblu system itself. This medium of communication is used to support two distinct features of the Unblu product: Live Chat and Secure Messenger, which we will discuss in the next section.

Text Chat should be distinguished from other text-based communication mechanisms that may be integrated into Unblu through the External Messenger Integration.

1.4.5. Voice and Video

Voice and Video refers to the real-time audio/video connection between visitor and agent provided by the Unblu system. In terms of product features, Video and Voice comprises a single feature of its own.

1.4.6. Co-browsing

Co-browsing refers to the functionality that enables visitors and agents to simultaneously view the same web page or electronic document. This category comprises three distinct product features:

Embedded Co-browsing

Enables the visitor to share with the agent the Unblu-enabled page that they are on.

Universal Co-browsing

Enables the visitor or agent to share and simultaneously view a third-party website (not Unblu-enabled).

Document Co-browsing

Enables the visitor or agent to share and simultaneously view an electronic document.

1.5. Technical Capabilities

In the previous section we gave a brief overview of the main concepts on which Unblu is based and saw examples of the key user interfaces. In this section we will explore the key technical communication and collaboration capabilities that the Unblu system offers. They are:

  • Text chat

  • Video call

  • DOM capture co-browsing

  • Rendered co-browsing

Note that these capabilities are defined in terms of the technologies used to implement them and do not align precisely with the set of Unblu product features as seen from a business user’s perspective. Later we will see how the product features are constructed from the technical capabilities. here we examine the capabilities themselves.

1.5.1. Text Chat

Text chat refers to the text messaging functionality of Unblu that provides real-time text communication between visitor and agent. In the previous section we saw the most common example of this: where the visitor is using the standard visitor interface and the agent is using the agent desk. In other cases either or both parties might use mobile apps or the visitor might use an external messenger service. In all these cases the same basic text chat functionality is leveraged.

The text chat capability is employed as part of three distinct product features: Live Chat, LiveView Chat and Secure Messenger.

1.5.2. Video Call

Video call refers to the real-time audio/video communications capability of Unblu. In the previous section we saw the most common example of this: where the visitor is using the standard visitor interface and the agent is using the agent desk. In other cases either or both parties might use mobile apps. In all these cases the same basic video call functionality is leveraged. This capability uses the TokBox external service to provide the audio/video link.

The video call capability is considered a distinct product feature called Video & Voice.

1.5.3. DOM Capture Co-browsing

DOM capture co-browsing refers to the capability that allows visitors to an Unblu-enabled website to co-browse on that site with an agent. This capability mirrors the visitor webpage by employing Javascript code that copies the structure of that page’s document object model, and other context information, and transmits it to the agent browser where it is reconstructed. Note that by definition this mechanism can only function on a webpage that has already been instrumented with Unblu code, hence it only applies to the website of the Unblu customer. To support co-browsing of arbitrary third-party websites, rendered co-browsing is required.

The DOM-capture co-browsing technology is used as part of two products features: Embedded Co-browsing and LiveView Chat.

1.5.4. Rendered Co-browsing

Rendered co-browsing refers to a technique for providing co-browsing of third-party websites and documents by visitor and agent. It works by rendering the website or document in a headless browser on the Unblu server and streaming the resulting video simultaneously to both visitor and agent browsers. The browser instance on the server is called headless because it is a process without a user interface. A separate headless browser instance is required for each visitor-agent co-browsing session. The part of the server responsible for spawning and managing the headless browsers is called the Rendering Service.

This technology is used for two product features: Universal Co-browsing and Document Co-browsing.

1.6. Product Features

In the previous section we looked at the technical communication and collaboration capabilities of Unblu. In this section we will explain the product features enabled by these capabilities.

The product features offered as part of Unblu are:

  • Live Chat

  • LiveView Chat

  • Secure Messenger

  • Video & Voice

  • Embedded Co-browsing

  • Universal Co-browsing

  • Document Co-browsing

As customer of Unblu you can choose to license all of these features or just a subset.

1.6.1. Live Chat

Live chat enables visitors to communicate with agents on-demand using Unblu’s text chat capability. The live chat feature is designed specifically for situations where the relationship between visitor and agent is anonymous and conversations are relatively short. A typical use-case would be a help desk scenario. This feature is compatible with

1.6.2. LiveView Chat

LiveView Chat combines text chat with DOM capture co-browsing. With this feature the agent and visitor can chat via text messaging as with Live Chat, but, in addition, the visitor’s page is automatically visible to the agent as soon as the visitor starts the conversation. This provides valuable context to the agent, enabling much more effective help and assistance.

1.6.3. Secure Messenger

Secure Messenger uses the same text chat capability as Live Chat but in a different way. With secure messenger the system is configured to support long-running relationships between an advisor and a client visitor keeping a continuous conversation history.

1.6.4. Embedded Co-Browsing

Embedded co-browsing uses the DOM Capture co-browsing capability to allow a visitor share her view of the the Unblu-enabled website itself (that is, your firm’s website) with the agent. The difference between embedded co-browsing and the co-browsing in LiveView is that in this case the visitor can choose to pro-actively share the view from her browser and can end the co-browsing session without ending any communication on other channels (Live Chat or Video & Voice, for example)

Here is what embedded co-browsing looks like from the visitor’s perspective. Notice the green border that indicates to the visitor that the page is being co-browsed with the agent:

visitor embedded

And here is what it looks like to the agent:

agent embedded

See Embedded Co-Browsing for more details.

1.6.5. Video & Voice

In addition to text chat, Unblu can also provide a Video & Voice communication channel. Here you can see the voice and video controls enabled on the standard visitor interface:

visitor video voice enabled

Here is what a video session looks like from the visitor’s perspective:

screen visitor video call

and from the agent’s perspective:

screen agent video call

See Video & Voice for more details.

1.6.6. Universal Co-Browsing

Universal co-browsing uses the rendered co-browsing capability to let either party (depending on configuration) share their view of any site on the web.

Here is what universal co-browsing looks like from the visitor’s perspective:

visitor embedded

And here is what it looks like to the agent:

agent embedded

See Universal Co-Browsing for more details.

1.6.7. Document Co-Browsing

Document co-browsing also uses the rendered co-browsing capability but in this case it is to allow the parties to simultaneously view a document (a PDF, for example) that on party or the other has uploaded.

Here is what the document co-browsing interface looks like for the visitor:

screen visitor document

And here is what it looks like for the agent:

screen agent document

2. Architecture

2.1. Overview

The details of your Unblu setup will differ depending on which deployment model and which optional elements you choose. However, the underlying architecture of the system is essentially the same across all variants.

In this section we will explain this common architecture at an abstract level and then examine how it is actually implemented for each deployment model and how the various optional pieces fit in.

2.2. Elements of the System

An Unblu installation can be divided into the following principal components:

  • Unblu server

  • Rendering service

  • Database

  • External services

  • Front end interfaces and integrations

  • Back end integrations

The following diagram shows how these pieces fit together:

Produced by OmniGraffle 7.11.2 2019-09-10 07:33:51 +0000 Canvas 1 Layer 1 Company Network Mobile Visitor Unblu Server Back End Integration Web API Webhooks Agent on Mobile Agent Front End Integration Agent Mobile SDK Internal Company Systems Database Rendering Service External Service TokBox Service Company Website Web Visitor External Service Unblu Cloud TURN Server Agent on Web Rendered Co-Browsing Video & Voice Agent Front End Built-in Agent Desk Admin Interface Config Interface Visitor Front End Integration Individual UI JS API Visitor Front End Integration Visitor Mobile SDK SecureFlow Asset Upload
Figure 1. Basic System Components

2.2.1. Unblu Server

This is the main server component. It performs the following major functions:

  • User authentication and authorization

  • Managing the communication between the visitor interface and the agent desk via chat, video and voice.

  • Managing embedded co-browsing.

  • Mediating universal and document co-browsing.

  • Managing the configuration settings.

  • Serving the web-based agent desk and admin interface.

  • Providing client and server integration APIs

The specifics of the Unblu server setup depend on the deployment model. For details see Unblu Server.

2.2.2. Rendering Service

The rendering service is required for universal co-browsing and document co-browsing. If universal or document co-browsing are not licensed, then this component will not be present. The rendering service works by spawning a headless browser instance for each co-browsing session and then streaming the visual rendering of the webpage or document simultaneously to both agent and visitor. See Rendering Service.

2.2.3. Database

The database holds all the persistent data needed by the Unblu server including conversation history and other system state (see Database). See Database.

2.2.4. External Services

To support some features (video/voice, universal and document co-browsing) Unblu relies on two additional components: TokBox and the TURN server. These are external cloud services to which the Unblu Server connects. These do not reside on your infrastructure. See External Services.

2.2.5. Front End Interfaces and Integrations

The Unblu front end includes multiple types of interfaces and integration points for both visitors and agents. They include: * Interfaces that are already built-in to the product: Agent Desk, Visitor Desk, Admin Interface, Config Interface. * Pre-built components that require integration: Visitor Individual UI. * APIs and SDKs for building your interfaces: JS API, Visitor and Agent Mobile SDK, External Messenger API.

2.2.6. Back End Integrations

Unblu also supports custom integrations on the back end using the Web API and Webhooks as well as chatbot integration using the Bot API. See Back End Integrations.

2.3. Deployment Models

Unblu supports four different deployment models:

  • Unblu Financial Cloud service

  • On-premises cluster

  • On-premises application server

  • Standalone on local machine

2.3.1. Unblu Financial Cloud

The Unblu Financial Cloud is Unblu’s cloud service offering. With this service, you receive an account as a tenant on an Unblu system running on our own infrastructure in a secure data center in Switzerland. Under the hood, the cloud set up is a clustered deployment similar to one that a customer might have on-premises (see below), except that all management and maintenance of the system is handled by Unblu.

2.3.1.1. Getting Started with Cloud

The Unblu delivery team can help get you up and running on the Unblu Financial Cloud. For details see Cloud Onboarding.

2.3.2. On-Premises Cluster

In this model the Unblu system is installed on your in-house Kubernetes or OpenShift cluster and managed by your company.

For Unblu 5 and later, the cluster deployment is the recommended on-premises deployment model. The application server deployment model that was used for previous versions (see below) is still functional in Unblu 5 and later, but is deprecated. See Recommendations.
2.3.2.1. Kubernetes and OpenShift

Unblu supports all recent versions of the open-source Kubernetes cluster orchestration system as well as the commercial OpenShift variant of Kubernetes. All references to Kubernetes therefore apply to OpenShift as well. Where differences exist, these are noted.

2.3.2.2. About Kubernetes

Kubernetes is a cluster orchestration system designed to simplify the deployment of applications across multiple machines in a cluster. To do this a number of abstractions are employed to insulate the Kubernetes user from the details of the implementation. A quick review of these may help with later discussion of how the Unblu cluster works.

Node

The abstraction representing the physical machine (i.e. a computer). In practice a node may be either a real physical machine or a virtual machine. From the Kubernetes point-of-view this distinction is hidden by the abstraction. Nodes are building blocks of the cluster in the sense that a "cluster" is so-called because it is a cluster (an interconnected group) of nodes.

Container

An lightweight environment for isolating running processes within a single physical or virtual machine. Kubernetes uses container technology (like Docker, for example) to organize the running processes in the cluster.

Pod

The essential abstraction used within Kubernetes to enable scalability. A pod is a component that holds one or more containers and constitutes the unit which can be replicated to scale up performance within a cluster. Applications are written to be deployed within pods so that multiple replicas of a pod can be spawned to increase computing power. When more performance is needed the Kubernetes admin can increase the number of pods and Kubernetes takes care of spreading these running processes across the available compute nodes.

2.3.2.3. Cluster System Overview

The following diagram gives an overview of the organization of an on-premises cluster deployment:

Produced by OmniGraffle 7.11.2 2019-09-10 08:43:41 +0000 Canvas 1 Layer 1 Kubernetes Cluster Company Network Kubernetes Pod Replica Set Kubernetes Single Pod Mobile Visitor Agent on Mobile Agent Front End Integration Agent Mobile SDK Internal Company Systems Database External Service TokBox Service Company Website Web Visitor External Service Unblu Cloud TURN Server Agent on Web Universal and Document Co-Browsing Video and Voice Visitor Front End Integration Individual UI / JS API Visitor Front End Integration Visitor Mobile SDK Zookeeper Kafka Prometheus Alert Manager Ingress Proxy Unblu Server SecureFlow Asset Upload Grafana * Includes Agent Front End Built-In and Back End Integration Collaboration Server* Rendering Service chromecast chromecast chromecast
Figure 2. Cluster System Components
2.3.2.4. Getting Started with On-Premises Cluster

The installation of Unblu on a Kubernetes cluster requires that you get access to the install scripts from the Unblu delivery team. For details see Cluster Deployment.

2.3.3. On-Premises Application Server

In this model the Unblu server is deployed on a Java application server (like Tomcat) using your own infrastructure, managed by your company. Additionally, the rendering service (if present) runs on a Docker engine, either on the same machine or a separate one.

This is the legacy deployment model for pre-Unblu 5. For Unblu 5 and later this model is available but not recommended.

The following diagram gives an overview of the organization of an on-premises application server deployment:

Produced by OmniGraffle 7.11.2 2019-09-10 07:50:24 +0000 Canvas 1 Layer 1 Company Network Docker Engine Application Server Mobile Visitor Agent on Mobile Agent Front End Integration Agent Mobile SDK Internal Company Systems Database Rendering Service External Service TokBox Service Company Website Web Visitor External Service Unblu Cloud TURN Server Agent on Web Universal and Document Co-Browsing Video and Voice Visitor Front End Integration Individual UI JS API Visitor Front End Integration Visitor Mobile SDK Unblu Server Back End Integration Web API Webhooks Agent Front End Built-In Agent Desk Admin Interface Config Interface SecureFlow Asset Upload
Figure 3. Application Server System Components
2.3.3.1. Getting Started with On-Premises Application Server

The installation of Unblu on an application server requires the deployment of the Unblu war file, which is available from the Unblu delivery team. For details see Application Server Deployment.

2.3.4. Standalone

The standalone deployment allows you to install an Unblu server quickly to your local machine. This can be useful in a number of scenarios including, testing, demos or development.

2.3.4.1. Getting Started with Standalone

To install Unblu in standalone mode you will use the same war file as is used in application server deployment. In this case, however, the file doubles as an executable jar file. When run it unpacks itself and deploys Unblu into an embedded application server. For details see Standalone Deployment.

2.4. Unblu Server

The Unblu Server is the central component of the Unblu installation. It manages company and user accounts, coordinates all communication (text chat, video, voice), manages co-browsing, serves the agent desk and admin web interfaces and provides the connection points for API integrations (client and server).

2.4.1. Differences Across Deployment Models

The details of the Unblu Server architecture depend on whether your installation is a cluster deployment or an application server deployment. For general information on these this topic see Deployment Models. Here we will cover the specifics of how the Unblu server differs across the models.

2.4.1.1. Cluster Architecture

In the earlier, more abstract depiction (Basic System Components) the Unblu server appears as a single component. In the diagram below we see that in a cluster deployment it is composed of a number of separate entities within the cluster.

Produced by OmniGraffle 7.11.2 2019-09-10 08:10:41 +0000 Canvas 1 Layer 1 Kubernetes Cluster Company Network Kubernetes Pod Replica Set Kubernetes Single Pod Mobile Visitor Agent on Mobile Agent Front End Integration Agent Mobile SDK Internal Company Systems Database External Service TokBox Service Company Website Web Visitor External Service Unblu Cloud TURN Server Agent on Web Universal and Document Co-Browsing Video and Voice Visitor Front End Integration Individual UI / JS APIe Visitor Front End Integration Visitor Mobile SDK Zookeeper Kafka Prometheus Alert Manager Ingress Proxy Unblu Server SecureFlow Asset Upload Grafana * Includes Agent Front End Built-In and Back End Integration Unblu server* Rendering Service chromecast chromecast chromecast
Figure 4. Unblu Server Cluster System Components

Unblu uses the Kubernetes cluster orchestration system (both Kubernetes itself and the OpenShift variant of Kubernetes are supported). In this system a components are deployed in units called pods. Components that require modest resources typically may consist of a single pod while components that require more computing resource can be deployed as multiple replicas of a pod. Some components consist of a fixed number of replicas. Others can be scaled by adding additional replicas as needed. For more details see Deployment Models.

The Unblu Server consist of the following components, each deployed in one or more pods.

2.4.1.1.1. Unblu Server Components
Collaboration Server

The core of the Unblu server functionality. This component typically consists of two or more pods.

This component can be scaled by allocating more pods. This ability to increase capacity on demand is one of the key reasons that the cluster model is recommended over the application server model (the other reason is the similar ability to scale the Rendering Service. See also, Recommendations)
Kafka

A data streaming and messaging platform that is used to synchronize across the multiple Unblu server core pods in the cluster. The Kafka component is always composed of three pods. See Kafka.

Zookeeper

A system for sharing configuration data across the individual Unblu server pods. The Zookeeper component is always composed of three pods. See Zookeeper.

Prometheus

A metrics collection and alerting system that is used to monitor the cluster. It typically occupies a single pod in the cluster. See Prometheus.

Grafana

Grafana provides visualization of the metrics collected by Prometheus. It typically occupies a single pod in the cluster. See Grafana

Alert Manager

Provides alerts to an external observation service to enable tracking of server behavior. It typically occupies a single pod in the cluster. See Alert Manager

Kubernetes Ingress (OpenShift Route)

Incoming requests from agent or visitor web clients are handled by a load balancer which then distributes the request among the Unblu server pods. This component can also be configured to act as a cache. The load balancer and cache can be either external to the cluster or deployed as one or more pod within the cluster.

Proxy

This component provides the SecureFlow Manager with access to upload resources from your Unblu enabled website. It typically consists of one pod.

2.4.1.2. Application Server Architecture

In the earlier, more abstract depiction (Basic System Components) the Unblu Server appears as a single component. In the diagram below we see that in an application server deployment it is implemented as a Unblu Server component running within an application server.

Produced by OmniGraffle 7.11.2 2019-09-10 08:44:17 +0000 Canvas 1 Layer 1 Company Network Docker Engine Application Server Mobile Visitor Agent on Mobile Agent Front End Integration Agent Mobile SDK Internal Company Systems Database Rendering Service External Service TokBox Service Company Website Web Visitor External Service Unblu Cloud TURN Server Agent on Web Universal and Document Co-Browsing Video and Voice Visitor Front End Integration Individual UI / JS API Visitor Front End Integration Visitor Mobile SDK Unblu Server Back End Integration Web API / Webhooks Agent Front End Built-In Agent Desk Admin Interface Config Interface SecureFlow Asset Upload
Figure 5. Unblu Server Application Server System Components

Unblu supports most standard Java application servers (Tomcat, JBoss/WildFly, Jetty, GlassFish, Oracle WebLogic, IBM WebSphere, etc.). For more details see Deployment Models.

2.5. Rendering Service

The rendering service is used to support the universal and document co-browsing features (if your installation does not support one or both of these features, the rendering service will not be present).

When a visitor and agent start a universal or document co-browsing session, the rendering service creates a dedicated headless browser instance (i.e., a browser without a visible user interface shell) for that session. The browser process is used to produce a video rendering of the target document or website which is then streamed to both visitor and agent. One such headless browser instance is spawned for each individual visitor-agent co-browsing session.

2.5.1. Differences Across Deployment Models

The details of the rendering service architecture depend on whether your installation is a cluster deployment or an application server deployment. For general information on these this topic see Deployment Models. Here we will cover the specifics of how the Unblu server differs across the models.

2.5.1.1. Cluster Model

In the cluster model each headless browser instance is run within a separate a Kubernetes pod. As more sessions are started more pods are deployed. The Kubernetes system allocates the pods appropriately across the cluster automatically, spreading the processing load across the available compute resources.

If a customer finds that the rendering service is hitting resource limits regularly, additional compute nodes can be added to the cluster easily. One key advantage of the clustering model over the application server model with respect to the rendering service is precisely this ability to scale the capacity of the system horizontally. This is one of the reasons that the cluster deployment is the recommended setup for Unblu.

In the earlier diagram (Basic System Components) the rendering service appears as a single component. In the diagram below we see that in a cluster deployment it is composed of a number of separate pods, each running a single headless browser.

Produced by OmniGraffle 7.11.2 2019-09-10 08:43:08 +0000 Canvas 1 Layer 1 Kubernetes Cluster Company Network Kubernetes Pod Replica Set Kubernetes Single Pod Mobile Visitor Agent on Mobile Agent Front End Integration Agent Mobile SDK Internal Company Systems Database External Service TokBox Service Company Website Web Visitor External Service Unblu Cloud TURN Server Agent on Web Universal and Document Co-Browsing Video and Voice Visitor Front End Integration Individual UI / JS API Visitor Front End Integration Visitor Mobile SDK Zookeeper Kafka Prometheus Alert Manager Ingress Proxy Unblu Server SecureFlow Asset Upload Grafana * Includes Agent Front End Built-In and Back End Integration Unblu server* Rendering Service chromecast chromecast Hexagon chromecast
Figure 6. Rendering Service Cluster System Components

2.5.2. Application Server Model

In the application server model the rendering service spawns each headless browser in a dedicated Docker container running on a Docker Engine on the same machine as the Unblu server running in the application server. As more sessions are started more containers are deployed within the Docker Engine.

If a customer finds that the rendering service is hitting resource limits regularly, the server can be scaled vertically (i.e., more memory and disk space can be added) but unlike the clustering case, horizontal scaling is not possible. This is one of the disadvantages of the application server model in comparison to the clustering model and one of the reasons that cluster deployment is the recommended setup for Unblu.

In the earlier diagram (Basic System Components) the rendering service appears as a single component. In the diagram below we see that in an application server deployment it is composed of a number of docker engine holding a number of containers, each running a single headless browser.

Produced by OmniGraffle 7.11.2 2019-09-10 08:36:18 +0000 Canvas 1 Layer 1 Company Network Docker Engine Application Server Mobile Visitor Agent on Mobile Agent Front End Integration Agent Mobile SDK Internal Company Systems Database Rendering Service External Service TokBox Service Company Website Web Visitor External Service Unblu Cloud TURN Server Agent on Web Universal and Document Co-Browsing Video and Voice Visitor Front End Integration Individual UI / JS API Visitor Front End Integration Visitor Mobile SDK Unblu Server Back End Integration Web API / Webhooks Agent Front End Built-In Agent Desk Admin Interface Config Interface SecureFlow Asset Upload
Figure 7. Rendering Service Application Server System Components

2.6. Database

The Unblu requires an RDBMS to store all persistent data.

2.6.1. Database Location

The database is external to the Unblu Server: In a cluster deployment it is outside the Unblu cluster and in an application server deployment it is outside the application server (usually on a separate machine). In many cases customers can benefit from leveraging the existing database infrastructure of their organization.

2.6.2. Supported Databases

Unblu requires a conventional RDBMS, i.e., a SQL-based DB. The supported systems are:

  • Oracle 11.2g or later

  • Microsoft SQL Server 2012 or later

  • MySQL 5.5 or later

  • PostgreSQL 9.1.22 or later

  • MariaDB 10.1 or later

2.6.3. Stored Data

The database is used to store all persistent data required by the Unblu system. This includes

Configuration Data
  • Users

  • Teams

  • Named areas,

  • API keys

  • Canned responses

  • Conversation templates

  • Tenant accounts

  • Configuration settings

Operational Data
  • Conversation state data

  • Text messages exchanged during conversations

  • Documents shared during document co-browsing

It is important to note that personally identifiable information is often stored in the Unblu database. Customers should take this into account when deciding upon the deployment details of the database.

2.6.4. Deployment

For details on deploying the database and connecting it to the Unblu Server, see Deployment > Database.

2.7. External Components

2.7.1. TokBox

To support voice and video Unblu relies on an external service called TokBox. To enable voice and video, the Unblu server must be configured to connect to this service. This configuration does not involve any additional installation on the server side and is identical across deployment models. See Deployment > TokBox.

2.7.1.1. Data Security

All video and voice calls through the Unblu system traverse the TokBox service. This includes both the actual video and audio streams as well as signalling data used to establish connections. However, all data is always encrypted, both in transit and at rest (see TokBox Security).

2.7.1.2. Archiving

TokBox supports encrypted archiving of voice and video sessions. The service can be configured to automatically upload archive data to your own premises as required.

2.7.1.3. Administration

The TokBox service is provided through Unblu. Unblu handles the account relationship with TokBox to provide you with seamless experience. TokBox usage is billed through Unblu.

2.7.2. TURN Server

To support universal co-browsing and document co-browsing Unblu requires a connection to A TURN server. The recommended approach is to use the Unblu cloud TURN server service. See Deployment > TURN server.

The TURN server is used to provide a video steaming connection between the rendering service on the one hand and the agent and visitor clients on the other. A TURN server is a standard mechanism for creating such connections between endpoints that are each behind their own firewall. It does this by providing a common location external to the two communicating parties to which each can establish an outbound connection. The TURN server then provides bridge creating the end-to-end connection.

2.7.2.1. Data Security

All video traffic related to universal and document co-browsing traverses the TURN server. However, all data is always encrypted.

2.7.2.2. No Archiving

Universal and document co-browsing sessions are ephemeral. They are not archived.

2.7.2.3. Administration

The Unblu cloud TURN server is configured and administered by Unblu. Its operation is transparent to you as a customer. There is no charge for data transmitted during universal or document co-browsing.

2.8. Front End Interfaces and Integrations

Unblu provides a number of interfaces and interface integration points for both visitors and agents. This includes the built-in web interface available out-of the box that is used by agents and administrators, the Individual UI web component intended for integration with your website and APIs and SDKs that enable additional interface channels.

The following section summarizes both the built-in front end interfaces and the front end integrations that are available for both visitors and agents.

2.8.1. Visitor-Side Integrations

2.8.1.1. Individual UI

On the visitor side the primary interface in most installations is the Individual UI. This is a web component provided by Unblu that is deployed by integrating it into your website. A website into which the Individual UI is integrated is referred to as "Unblu-enabled".

It is sometimes referred to as the "snippet" because it is included in the page of your website as a snippet of HTML containing a <script> tag that loads the required JavaScript code. For most customers the Individual UI is the default method through which visitors connect to Unblu. See Individual UI Web Integration.

2.8.1.2. JavaScript API

Unblu also offers a JavaScript API (JS-API) that you can use within your website to add functionality above and beyond that provided by the Individual UI. See JavaScript API.

2.8.1.3. Visitor Mobile SDK

Using the Visitor Mobile App SDK you can build a custom mobile app for your visitors to use that supports all the same features as the web-based Individual UI. See Mobile SDK.

2.8.1.4. External Messenger

External Messenger Integration lets you offer your visitors the ability to communicate with agents via Unblu through their existing messenger applications such as WhatsApp, FaceBook Messenger, etc. See External Messenger Integration.

2.8.2. Visitor-Side Built-in Interface

On the agent side Unblu provides the Agent Desk and Configuration Interface as web interfaces served from the Unblu server out-of-the-box. They do not require any extra work to get them up and running.

2.8.2.1. Visitor Desk

The Visitor Desk is a version of the Individual UI which is not integrated into your website but is instead served directly from the Unblu server. Visually it appears as an Individual UI overlayed over a neutral background. This interface is typically used in cases where an advisor agent wants to give a client visitor access to Unblu outside the context of any particular webpage. She does this by sending the visitor a link to the Visitor Desk.

2.8.3. Agent-Side Integrations

2.8.3.1. Custom Agent Mobile App using Mobile SDK

Using the Agent Mobile App SDK you can build a custom mobile app for your agent. See Mobile SDK.

2.8.4. Agent-Side Built-in Interfaces

2.8.4.1. Agent Desk

The Agent Desk is a conventional desktop browser web application served directly by the Unblu server.

2.8.4.2. Administration Interface

The Administration Interface is a conventional desktop browser web application served directly by the Unblu server. Recall Supervisor and Administrator.

2.9. Back End Integrations

In addition to providing many options for front end integrations (see Front End Interfaces and Integrations) Unblu also enables back end integrations using the Web API, Webhooks and the Bot API.

2.9.1. Web API and Webhooks

The Unblu Web API exposes the functionality of the Unblu server enabling you to perform actions on the server using JSON over HTTP. While the Web API enables external software to initiate actions in Unblu, the Webhooks feature enables the opposite: It lets the Unblu server initiate actions on external system, in response to events occurring in the server. For details, see Web API and Webhooks.

2.9.2. Bot Integration

The Bot API enables you to integrate an external chatbot system with Unblu, allowing the bot play the role of an agent in interactions with visitors. Typically the bot will be used to handle more formulaic interactions and information collection. As soon as the bot encounters a question it cannot answer the visitor will be redirected to a human agent. See Bot Integration.

2.10. WebRTC

WebRTC (Web Real-Time Communication) is a free, open-source project that provides web browsers and mobile applications with real-time communication (RTC) via simple application programming interfaces (APIs). It allows audio and video communication to work inside web pages by allowing direct peer-to-peer communication, eliminating the need to install plugins or download native apps. Supported by Apple, Google, Microsoft, Mozilla, and Opera, WebRTC is being standardized through the World Wide Web Consortium (W3C) and the Internet Engineering Task Force (IETF).

— Wikipedia

WebRTC is currently supported in all major browsers - except Internet Explorer.

  • Chrome

  • Firefox

  • Opera

  • Edge

  • Safari (not mobile)

Encryption is a mandatory feature of WebRTC. All communication between peers are end-to-end encrypted using ephemeral keys.

2.10.1. Overview

Unblu uses WebRTC for the following features.

  • Universal and Document Co-Browsing - optional, fallback to HLS is possible.

  • Screen Sharing - mandatory, the underlying browser APIs is based WebRTC.

As WebRTC is a peer-to-peer procotol and can not establish connections when both participants are using a private IP address, Unblu requires a TURN server to facilitate the WebRTC connection between the following participants:

  • Rendering Service running in the Unblu Cloud or on-premise.

  • Visitor browser running anywhere.

  • Agent browser running in the company network (or anywhere).

Unblu currently provides a TURN server based on a monthly subscription hosted at aspectra in Zurich, Switzerland.

Unblu’s TURN server has a static IP address: 194.247.8.211.

In the future Unblu might also integrate with SaaS TURN servers or offer on-premise TURN server support. At the time however we are limited to our own TURN server offering.

The TURN server does at no point know the key used to encrypt the communication and is therefore not able to see the content of the session.

2.10.2. Audio and Video calls

Unblu uses the tokbox platform to support audio and video calls. Tokbox also leverages the WebRTC protocol but uses dedicated TURN servers. It also adds itself as a peer into the session to allow recording of all calls in Unblu. Calls are therefore encrypted over the wire but are decrypted on the server to allow recordings.

The Unblu server requires access to http://api.opentok.com in order to start calls. A forward proxy can be configured.

2.10.3. Ports

WebRTC requires a number of ports to be open from the network zones of the Unblu cluster and the Agent.

  • 3478, TCP and UDP

  • 5349, TCP and UDP

  • 443, TCP (TLS but not HTTP!)

WebRTC will dynamically assess all open ports and start a session based on the best combination. Generally speaking UDP is the preferred protocol and also recommended by Unblu as it is better suitable for streaming, specially in low bandwidth scenarios.

3. Installation and Deployment

3.1. Overview

Previously, in Architecture, we saw how the Unblu system is structured and how the various deployment models affect that structure. In this section we will explain what to consider when choosing which model to use and how to actually perform the installation, deployment or onboarding.

3.2. Recommendations

The first decision to made when adopting Unblu is whether to choose a cloud solution or an on-premises solution.

3.2.1. The Cloud Option

The Unblu Financial Cloud gives you all the advantages typical of cloud services in general:

  • Lower IT costs.

  • Costs are part of operational, not capital, expenditure.

  • Always up-to-date software. No installation. No updates.

  • Easy scalability.

In addition to these, the Unblu Financial Cloud also gives you these specific benefits:

  • The physical and legal security of Swiss hosting.

  • ISO 27001: 2013 certified

  • Compliant with FINMA Guidelines of Circular 2008/7.

  • Compliant with SFBC Circular 2005/2 No. 87.

  • The technical reliability stemming from Unblu’s expertise in our own product and infrastructure.

The use of cloud software is becoming more widespread in the financial industry as regulations are adapted to the new technology and as customers become more familiar with the advantages inherent in the approach.

Our recommendation to our customers is simple: If your organization can (in terms of compliance) choose the the cloud option then you should choose the cloud option.

For details on how to get started see Cloud Onboarding.

3.2.2. The On-Premises Option

While the cloud offers many benefits, Unblu does recognize that many customers will prefer an on-premises installation, for a variety of reasons. If this is the case with your organization, the recommended on-premises solution is the cluster deployment.

Cluster deployment was introduced with Unblu 5 and continues to be the recommended on-premises model for Unblu 6. Previous to Unblu 5 on-premises installations used the application server model. While this type of installation is still possible with Unblu 5 and 6 it is considered deprecated and is not recommended for production systems.

For details on deployment see Cluster Deployment

3.2.2.1. Single-Node Cluster

The cluster deployment model has numerous advantages over the older application server model (see XXX). However, some customers may be concerned about the amount of infrastructure investment required and would prefer to single machine rather than the multiple machines typical of a Kubernetes cluster.

In such cases customers may be tempted to consider a single machine application server install. However, Unblu’s recommendation is to still employ the cluster deployment but to use a single-node cluster.

With the single-node cluster you will still only need a single machine but you will have the advantage of being able to seamlessly scale the system later as your needs grow. In addition, the cluster approach also provides you with

  • Health checks automatic restart of components

  • Metrics and alerting

  • Ability to easily add a rendering service (if you initially start without this feature).

In short the single-node cluster is best choice for a "starter" installation that you can later expand.

3.2.3. Standalone

While the application server approach is not recommended for production systems, it still plays a role in the form of the standalone deployment. In this special case of the application server deployment, the runnable web archive file (war) unpacks itself and runs the system on an embedded Jetty application server.

3.3. Configuration Files

3.3.1. Overview

A big part of the installation process for all on-premises deployments is the configuration of the Unblu system.

Unblu configuration is governed by a single namespace of configuration parameters. On startup the configuration is read from one or more configuration files. Later, once the system is up and running the same configuration namespace is editable via the Configuration Interface.

In the application server and standalone deployments a single configuration file, by convention called unblu-config.properties, is used.

In the cluster deployment a number of configuration files are used in a series of overlays. Customer level configuration is placed in the file unblu-customer.properties.

3.4. Cloud Onboarding

In this section we describe the process of onboarding to the Unblu Financial Cloud.

3.4.1. Unblu Delivery

Once you have a license agreement in place with Unblu the first step is to reach out to the Unblu delivery team to discuss the precise technical details of your project so that Unblu can correctly configure your account for your needs. When configuration is complete you will receive your account details and be able to login as an administrator.

3.4.2. Integrations

With the Unblu Financial Cloud there is, of course, no server installation or configuration to be done on your end. However, you will still need to do some integration work to enable Unblu for visitors on your website. Optionally, you may also want to enable other integrations for visitors, agents or on the back en.

The primary difference, in terms of integration, between an on-premises installations and the cloud setup is that the Individual UI integration is subject to certain restrictions in the cloud case.

All other integrations and interfaces are the same.

3.4.2.1. Individual UI Integration

With the Unblu cloud solution the following restrictions exist with respect to integrating the Individual UI into your company website:

  • The SecureFlow Manager is not available so neither dynamic injection of the client-side code nor protected resource upload are supported.

  • The site-embedded server setup is not supported.

In other words, with the cloud setup your Individual UI web integration will have:

  • Static injection of client code

  • No protected resource upload

  • Cross-origin server setup

3.4.2.2. Other Interfaces and Integrations

All other interfaces and integrations work just as they do with the on-premises setup. On the visitor side the JavaScript API, Visitor Mobile SDK and External Messenger API are supported. On the agent side the Agent Desk and Configuration Interface are available out-of-the-box as usual, and the Agent Mobile SDK is supported. On the back end the Web API, Webhooks and Bot API are also fully supported.

3.5. Cluster Deployment

3.5.1. Prerequisites

To begin cluster installation you will need the following:

  • A running Kubernetes cluster. This may be an existing cluster already used in production at your organization, a newly installed cluster, or a cloud cluster (i.e., one which your organization manages. This is distinct from Unblu’s own cloud offering). Unblu supports both standard Kubernetes and OpenShift.

  • The Kustomize configuration management tool (this may be already included in your Kubernetes installation as it is integrated into kubectl since 1.14).

  • The Unblu Kustomize bundle used to deploy the software. This will be provided to you by the Unblu delivery team.

  • Access to the Unblu container image registry (gcr.io/unblu-containerrepo-public) to pull the images.

Should you not be able to run kustomize, the Unblu delivery team will send you the already built YAML deployment file.

3.5.2. Access to the Unblu Image Registry

A Kubernetes cluster requires access to the image registry at all times in order pull images. Should this be prevented by a company policy, you can use a company internal registry as a proxy. Products such as Artifactory can be used to either manually push images or download images transparently in the background.

Access credentials to the Unblu image registry will usually be provided as a gcr-secret.yaml YAML file. Please apply this file to your cluster before you perform the installation.

Listing 1. Create a namespace and apply the image pull secret (Kubernetes)
kubectl create namespace unblu-test
kubectl apply -f gcr-secret.yaml --namespace=unblu-test
Listing 2. Create a project and apply the image pull secret (OpenShift)
oc new-project unblu-test \
    --description="Unblu Test Environment" \
    --display-name="unblu-test"
oc project unblu-test
oc apply -f gcr-secret.yaml

3.5.3. Database Secret

Unblu stores all data in a relational database. The credentials to access the database need to be passed to Unblu as a secret named database.

Listing 3. Database secret
kind: Secret
apiVersion: v1
metadata:
  name: database
type: Opaque
stringData:
  DB_USER: unblu
  DB_PASSWORD: unblu_password
  DB_ADMIN_USER: unblu_admin
  DB_ADMIN_PASSWORD: admin_password

The database secret is used to populate the user configuration. Consequently, you don’t need to manually declare those parameters in the configuration file unblu-customer.properties. In other words you do not need the following lines in unblu-customer.properties:

Listing 4. When using the secret, the following lines are not needed unblu-customer.properties
com.unblu.storage.database.user=unblu
com.unblu.storage.database.password=<pwd>
com.unblu.storage.database.adminUser=unblu_admin
com.unblu.storage.database.adminPassword=<pwd>

Other database related configuration is part of unblu-customer.properties file and follows the Unblu configuration standard. Please refer to the section Database configuration for more details.

3.5.4. Performing the Installation

The Unblu delivery team will send a compressed archive containing a set of files. The listing below assumes that you’ve extracted the bundle into a folder called unblu-installation.

Listing 5. Build a kustomize bundle and apply the YAML to a cluster
kustomize build unblu-installation > unblu.yaml
kubectl apply -f unblu.yaml

Before deploying Unblu into a cluster, you may want to adjust the following in kustomization.yaml.

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

namespace: cs-poc (1)

bases: (2)
- unblu-kubernetes-base/collaboration-server
- unblu-kubernetes-base/renderingservice
- unblu-kubernetes-base/k8s-ingress
- unblu-kubernetes-base/k8s-prometheus
- unblu-kubernetes-base/grafana

resources: [] (3)

patchesStrategicMerge: [] (4)

configMapGenerator:
- name: collaboration-server-config
  behavior: merge
  files:
    - unblu-customer.properties (5)

secretGenerator:
- name: ingress-tls (6)
  behavior: merge
  files:
    - certs/tls.crt
    - certs/tls.key
  type: "kubernetes.io/tls"

images: (7)
  - name: gcr.io/unblu-containerrepo-public/collaborationserver-public-centos7
    newName: example.com/unblu/collaborationserver-dev-centos7
  - name: gcr.io/unblu-containerrepo-public/headless-browser-public-ubuntu1804
    newName: example.com/unblu/headless-browser-private-ubuntu1804
  - name: gcr.io/unblu-containerrepo-public/nginx-public-centos7
    newName: example.com/unblu/nginx-private-centos7
  - name: gcr.io/unblu-containerrepo-public/haproxy-public-centos7
    newName: example.com/unblu/haproxy-private-centos7
  - name: gcr.io/unblu-containerrepo-public/coturn-public-centos7
    newName: example.com/unblu/coturn-private-centos7
1 Change the namespace (Kubernetes) or project (OpenShift) to be used.
2 Add or remove base modules, depending on your environment or license.
3 Deploy custom components as part of Unblu.
4 Patch some values of the deployment.
5 Add the configuration file unblu-customer.properties to the deployment.
6 Add the TLS certificate as a secret to be used for the Ingress or Route.
7 Rewrite the images source to a new registry.

Instead of updating the kustomization.yaml that was delivered to you, we recommend to create a new one and separate your customizations from our deliveries.

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

namespace: unblu-production

bases:
- unblu-delivery

3.5.5. Update an existing installation

Upgrading an existing Unblu installation implies the following steps:

  1. Remove the existing deployment from the cluster using clean.sh.

  2. Apply the new deployment, identical to a new installation.

  3. Database patches are automatically applied when the Unblu server starts.

For simple configuration updates the first step may be omitted, for Unblu release upgrades all steps are mandatory.

Listing 6. clean.sh for Kubernetes
#!/usr/bin/env bash

NAMESPACE="demo-latest"

read -p "Do you really want to clean environment \"$NAMESPACE\"? (y/N) " -n 1 -r
if [[ ! $REPLY =~ ^[yY]$ ]]
then
  exit 1
fi

echo ""
echo "Dropping Unblu"
kubectl delete deployment,pod -n $NAMESPACE -l "component = collaboration-server"
kubectl delete statefulset,pod -n $NAMESPACE -l "component in (kafka, zookeeper)" \
  --force --grace-period=0
kubectl delete deployment,statefulset,pod,service,configmap,persistentvolumeclaim,secret \
  -n $NAMESPACE -l "app = unblu"

read -p "Do you want to drop the metrics platform (Prometheus, Grafana) as well? (y/N) " -n 1 -r
echo

if [[ $REPLY =~ ^[yY]$ ]]
then
  kubectl delete deployment,pod,service,configmap,persistentvolumeclaim,secret \
    -n $NAMESPACE -l "app in (grafana, prometheus)"
fi

echo "Finished"
Listing 7. clean.sh for OpenShift
#!/usr/bin/env bash

oc whoami &>/dev/null
if [ "$?" != "0" ]
then
  echo "You are not logged in to any openshift cluster. Please login first (oc login) and select the correct project"
  exit 1
fi

if [[ ! $1 = "-f" ]]
then
  read -p "Do you want to delete the contents of $(oc project -q) (y/N) " -r
  echo

  if [[ ! $REPLY =~ ^[nNyY]?$ ]]
  then
    echo "Unexpected answer. Exiting"
    exit 2
  fi

  if [[ ! $REPLY =~ ^[yY]$ ]]
  then
    exit 0
  fi
fi

echo "Dropping Unblu"
oc delete deployment,pod -l "component = collaboration-server"
oc delete statefulset,pod -l "component in (kafka, zookeeper)" --force --grace-period=0
oc delete deployment,statefulset,pod,service,configmap,persistentvolumeclaim,secret -l "app = unblu"

read -p "Do you want to drop the metrics platform (Prometheus, Grafana) as well? (y/N) " -n 1 -r
echo

if [[ $REPLY =~ ^[yY]$ ]]
then
  oc delete deployment,pod,service,configmap,persistentvolumeclaim,secret -l "app in (grafana, prometheus)"
fi

echo "Finished"

3.6. Application Server Deployment

Unblu can be deployed on any Java application server (i.e., any server that functions as a Java Servlet Container, implementing the Java Servlet API). You should consult your application server documentation to get the specific installation directions.

3.6.1. Deploying Unblu on Tomcat

As an example, here we will describe the installation process on Tomcat.

3.6.1.1. Preparation

To begin with, you will need the following:

  • Suitable hardware on which to deploy the application server. For details see Hardware Requirements.

  • An installed Tomcat server. Consult the Tomcat documentation for details on installation.

  • The Unblu war file. (typically, product.com.unblu-<version>-<guid>.war).

  • The Unblu properties file, (typically, unblu-config.properties).

The Unblu files should be provided to you by the Unblu delivery team.

3.6.1.2. Deployment
In Tomcat terminology $CATALINA_HOME is the Tomcat home directory. If your Tomcat is properly installed, this environment variable should point to the location of the Tomcat installation.
3.6.1.2.1. Configuration File

To ensure that Unblu starts up properly upon deployment, you need to install the unblu-config.properties file so that Tomcat reads it on startup. The recommended way of doing this is:

  1. Copy unblu-config.properties to $CATALINA_HOME/conf

  2. In the file $CATALINA_HOME/bin/catalina.sh insert the following line at the top of the file:

    export JAVA_OPTS="$JAVA_OPTS -Dcom.unblu.propertyoverlay=file:///$CATALINA_HOME/conf/unblu-conf.properties"

Once you have made this change, restart Tomcat.

3.6.1.2.2. Context Path

In Tomcat (and other application servers), applications have a context path. This is simply the URI path (relative to the hostname of the server) where you point your browser to access the application. An application can be deployed either to the root context or a non-root context.

Assuming that the server is at http://<tomcat>/ then a typical non-root context for an Unblu install would be

http://<tomcat>/unblu/

Alternatively, if Unblu were deployed to the root context then its URI would be identical to that of the Tomcat server itself:

http://<tomcat>/
3.6.1.2.3. Non-Root Context Deployment

To deploy to a non-root context, the simplest method is:

  1. Rename the war file to <path>.war where path is the relative path at which you wish to deploy Unblu. Following the above example, we would simply rename the the war file to unblu.war.

  2. Ensure that Tomcat us running and copy the war file to the directory $CATALINA_HOME/webapps/. Tomcat should automatically unzip the war file and deploy the application. After a delay Unblu should be accessible at http://<tomcat>/unblu.

  3. Once deployed, you can safely delete the original war file $CATALINA_HOME/webapps/unblu.war.

3.6.1.2.4. Root Context Deployment

In Tomcat the root context app is found in the directory $CATALINA_HOME/webapps/ROOT. By default this directory contains the Tomcat server management application. To install another app at this location you need to replace the contents of that directory with the app you want to deploy. If you still want to keep the Tomcat management apps you have to first rename the existing ROOT folder. Assuming you want to keep the management apps, the following is the easiest way to deploy Unblu to the root context:

  1. Stop Tomcat.

  2. Rename $CATALINA_HOME/webapps/ROOT to something else, like $CATALINA_HOME/webapps/mgmt.

  3. Copy the Unblu war file to $CATALINA_HOME/webapps/` as ROOT.war.

  4. Restart Tomcat.

  5. Once deployed you can safely delete the original war file $CATALINA_HOME/webapps/ROOT.war.

3.6.1.2.5. Database

You can either use approach outlined in the database configuration section or use the datasource provided by the application server to connect Unblu to a relational database.

Listing 8. Configure Unblu to use a datasource provided by the application server
com.unblu.storage.database.datasourceFactory=USE_PROVIDED
com.unblu.storage.database.datasourceName=jdbc/Unblu (1)
1 JNDI name of the datasource
3.6.1.2.6. Check the Server Logs

After starting Tomcat, switch to the folder you configured for logging. You will find 3 files:

  • unblu.datestamp.log

  • unblu-fatal.datestamp.log

  • unblu-session.datestamp.log

Check the file unblu.datestamp.log to see whether the server started normally or if there are any configuration or DB connectivity issues.

3.6.1.2.7. Accessing the Unblu Server

If you deployed Unblu in root context, then:

If you deployed Unblu in a non-root context (let’s say as unblu.war), then:

Note: For more on restricted and public entry paths see System Entry Path Concept.

3.6.1.2.8. Test Whether Unblu Runs Correctly

If Unblu is running correctly, you will see the login screen for the agent view.

Login with the username unblu and the password secret.

3.7. Standalone Deployment

3.7.1. Overview

There are a number of scenarios where it can be useful to deploy an Unblu server quickly to your local machine. For example: testing, demos, development etc. A standalone deployment can be used for these situations.

The Unblu server is available as a war file. The file functions both as a traditional war file for application server deployment and as an executable jar file for standalone deployment.

3.7.2. Requirements

To run Unblu in standalone mode any reasonably modern machine should be sufficient. For example, a machine with the following specs will do the job:

  • 1 Recent CPU core running at 2.4GHz

  • 4 GB RAM

  • 10 GB of hard drive space

You will also need

  • Java 8 or later installed

and finally, you’ll need the installation package from Unblu, which shuld be provided to you by Unblu delivery. It consists of

  • The Unblu war file with a name like product.com.unblu-<version>-<guid>.war

  • The Unblu properties file (optional)

  • A valid Unblu license

3.7.3. Deployment

As a customer you will typically receive access to a downloadable file with a name like product.com.unblu-<version>-<guid>.war.

The Unblu WAR file can also be used as a executable JAR. An embedded jetty based web server is used in that case. Standalone mode is not suitable for production use.

Listing 9. Start Unblu with default configuration
java -jar product.com.unblu.war

The embedded Jetty web server will automatically select a TCP port in the range from 6060 to 7070. To manually select the TCP port add -Dport= on the command line.

3.7.3.1. Command Line Options

When running the executable jar, the following command line options are available:

Listing 10. Options and description
-e,--export <arg>   Type of export. Possible options: 'ear' or 'wjar'
-h,--help	        Display this help message
-l,--list           Format of output: ( version: build: branch: )
-m,--migrationOnly  use to shutdown the product after database migration is complete
-o,--output <arg>   File to write the exported product to. If not given, output will default to STDOUT.
-p,--product <arg>  ID of the product to start. For example product.com.unblu.enterprise (default)
-t,--test           Include test bundles into product execution/export (not available in production versions).
-d,--diag           Include diag bundles into product execution/export (not available in production versions).
Note: The 'product' switch is also available via System Properties and jndi.
3.7.3.2. Configuration File

All configuration can be placed in a separate file, e.g. unblu-config.properties.

Listing 11. unblu-config.properties
com.unblu.runtime.jetty.port=7777

# Create a superadmin on db setup
com.unblu.storage.createSuperAdmin=true
com.unblu.storage.superAdminPassword=superadmin
Listing 12. Start Unblu using unblu-config.properties
java -Dcom.unblu.propertyoverlay=unblu-config.properties \
    -jar product.com.unblu.war

3.8. Database Configuration

3.8.1. Overview

Unblu requires a relational database to persist configuration and operational data.

It is possible to run the Unblu server with an embedded in memory database, but this is only to be used for development and testing.

3.8.2. Compatible Databases

Unblu is compatible with following database platforms:

  • Oracle ≥ V11.2g

  • Microsoft SQL ≥ V2012

  • MySQL ≥ V5.5

  • PostgreSQL ≥ V9.1.22

  • MariaDB ≥ 10.1 Series

3.8.3. Database Setup

Before setup you must ensure the prerequisites are in place:

  • The database must be created by a database administrator with elevated privileges. The initial database creation must be performed manually and may differ slightly between database types.

  • The default charset must be UTF-­8.

  • The initial size requirement is small: < 20MB.

  • The DB size will grow as the system is used and conversations are added into the system.

Document sharing will negate the size numbers. By default documents uploaded into a conversation are stored in the database. This results in a significantly larger storage requirements. When larger amounts of documents are expected, we recommend to either configure a Remote Blob Store (RBS) in the database or use S3 (or a compatible service) to store documents.

3.8.4. Server Recommendations

These (hardware) recommendations should be regarded as a starting point. We cannot know how your system may evolve and therefore cannot define exact specifications for your particular needs. Your hardware requirements will be a direct function of the types and volume of data stored.

  • Recent Quad-core Architecture

  • 16 GB Ram

  • 200 GB disk (SSD)

The above hardware specification should produce the following performance.

  • 50,000 sessions per week

  • (equals) 200 sessions per agent per week for 250 agents

3.8.5. Database Users

Unblu uses two distinct users to operate:

  1. An admin user with database owner (DBO) privileges. He must have rights to execute the following statements: CREATE, ALTER, DROP, INSERT, UPDATE, DELETE, SELECT.

  2. Regular user with rights to execute INSERT, UPDATE, DELETE, SELECT on the tables created by the above user.

Listing 13. Unblu database users
com.unblu.storage.database.user=unblu (1)
com.unblu.storage.database.password=<pwd>
com.unblu.storage.database.adminUser=unblu_admin (2)
com.unblu.storage.database.adminPassword=<pwd>
1 The regular users with DML permissions.
2 The admin user with DDL permissions.

On initial setup of the system, the server must be started with the admin user configured so that the DB structure can be established. Once set up, the server will use the regular user, ensuring that security policies inside large organizations can be adhered to. After a successful setup, the admin user may be removed from the configuration.

Subsequent Unblu product updates will also require a start with the admin user to execute database migrations.

3.8.6. Configuring Different Database Types

There is a separate configuration section for each database type.

In all of the cases below the user and database (and schema, depending on the type) must be created manually.
For the sake of convenience all users and schemas listed here are called unblu. You may use any name you wish.
3.8.6.1. PostgreSQL
Listing 14. Create the unblu database and users
create database unblu;
-- activate database: \c unblu
create user unblu with password 'secret';
create user unblu_admin with password 'admin_secret';
alter default privileges for user unblu_admin in schema public grant select, update, insert, delete on tables to unblu;
grant usage, create on schema public to unblu_admin;

The example configuration below connects to the database unblu and relies on the default schema public which does not need to be created.

Listing 15. Unblu PostgreSQL configuration
com.unblu.storage.database.platform=org.eclipse.persistence.platform.database.PostgreSQLPlatform
com.unblu.storage.database.driver=org.postgresql.Driver
com.unblu.storage.database.url=jdbc:postgresql://<ip>:5432/unblu (1)
com.unblu.storage.database.user=unblu
com.unblu.storage.database.password=<pwd> (2)
com.unblu.storage.database.adminUser=unblu_dbo
com.unblu.storage.database.adminPassword=<pwd> (3)
com.unblu.storage.database.schema=public
com.unblu.storage.database.liquibaseSchema=public
1 Replace <server> with your database hostname or IP address.
2 Replace <pwd> with the password of the unblu user.
3 Replace <pwd> with the password of the unblu_admin user.
3.8.6.2. Oracle
Please review below script with an Oracle database administrator before using it.
Listing 16. Create the Unblu schema and permissions
ALTER SESSION SET "_ORACLE_SCRIPT" = TRUE;
CREATE USER UNBLU_DBO IDENTIFIED BY dbo_secret;
CREATE USER UNBLU IDENTIFIED BY secret;

GRANT CONNECT, CREATE TABLE TO UNBLU_DBO;
GRANT ALTER ANY TABLE TO UNBLU_DBO;
GRANT RESOURCE TO UNBLU_DBO;
GRANT UNLIMITED TABLESPACE TO UNBLU_DBO;

GRANT CONNECT TO UNBLU;

CREATE OR REPLACE TRIGGER UNBLU_DBO.DO_GRANT
  AFTER CREATE ON UNBLU_DBO.SCHEMA
DECLARE
    l_str VARCHAR2(255);
    l_job NUMBER;
BEGIN
    IF ( ora_dict_obj_type = 'TABLE' ) THEN
      l_str := 'execute immediate "grant select, insert, update, delete on '
               || ora_dict_obj_name
               || ' to UNBLU";';

      dbms_job.Submit(l_job, Replace(l_str, '"', ''''));
    END IF;
END;
/
An application restart might be required so that UNBLU can access the tables created by UNBLU_DBO.
Listing 17. Unblu Oracle configuration
com.unblu.storage.database.platform=org.eclipse.persistence.platform.database.OraclePlatform
com.unblu.storage.database.driver=oracle.jdbc.driver.OracleDriver
com.unblu.storage.database.url=jdbc:oracle:thin:@<server>:1521:xe (1)
com.unblu.storage.database.user=unblu
com.unblu.storage.database.password=<pwd> (2)
com.unblu.storage.database.schema=UNBLU_DBO
com.unblu.storage.database.liquibaseSchema=UNBLU_DBO
com.unblu.storage.database.adminUser=unblu_dbo
com.unblu.storage.database.adminPassword=<pwd> (3)
1 Replace <server> with your database hostname or IP address. Change the SID or service name if required.
2 Replace <pwd> with the password of the unblu user.
3 Replace <pwd> with the password of the unblu_admin user.
For a deeper insight into encrypting the database connection, please consult SSL With Oracle JDBC Thin Driver.
3.8.6.3. MySQL
Please consult the configuration section before creating the user and database.
Listing 18. Create the unblu database and users
CREATE DATABASE unblu DEFAULT CHARACTER SET = utf8 DEFAULT COLLATE utf8_general_ci;

GRANT SELECT,UPDATE,INSERT,DELETE ON unblu.* TO 'unblu'@'%' IDENTIFIED BY 'secret';
GRANT SELECT,UPDATE,INSERT,DELETE,CREATE,ALTER,DROP,INDEX,REFERENCES ON unblu.* TO 'unblu_admin'@'%' IDENTIFIED BY 'admin_secret';
Listing 19. Unblu MySQL configuration
com.unblu.storage.database.platform=org.eclipse.persistence.platform.database.MySQLPlatform
com.unblu.storage.database.driver=com.mysql.jdbc.Driver
com.unblu.storage.database.url=jdbc:mysql://<server>:3306/unblu (1)
com.unblu.storage.database.jdbcProperties=connectTimeout=60000,socketTimeout=60000,useUnicode=yes,characterEncoding=UTF-8,useLegacyDatetimeCode=false,serverTimezone=UTC,autoReconnectForPools=true
com.unblu.storage.database.user=unblu
com.unblu.storage.database.password=<pwd> (2)
com.unblu.storage.database.schema=unblu
com.unblu.storage.database.liquibaseSchema=unblu
com.unblu.storage.database.adminUser=unblu_admin
com.unblu.storage.database.adminPassword=<pwd> (3)
1 Replace <server> with your database hostname or IP address.
2 Replace <pwd> with the password of the unblu user.
3 Replace <pwd> with the password of the unblu_admin user.
In MySQL a schema is synonymous with a database. You can substitute the keyword SCHEMA instead of DATABASE in MySQL SQL syntax, for example using CREATE SCHEMA instead of CREATE DATABASE.
3.8.6.3.1. Configuration
We have observed three serious issues that can occur when using the default MySQL or MariaDB configuration applying to both Linux and Windows.

Before creating the schema you must override the MySQL defaults using the instructions below.

3.8.6.3.1.1. Character set
Listing 20. my.cnf (Unix) or my.ini (Windows)
[mysqld]

character-set-server=utf8mb4
3.8.6.3.1.2. Max allowed packet size

To support larger files to be uploaded to Unblu, please set max_allowed_packet to a higher value.

Listing 21. my.cnf (Unix) or my.ini (Windows)
[mysqld]

max_allowed_packet=<size> (Example: 16M)
The maximum file size is 1 Gigabyte (1G).
Listing 22. Access the current maximum file size
SHOW VARIABLES LIKE 'max_allowed_packet';
3.8.6.3.1.3. SQL mode

Unblu requires the MySQL parameters NO_ZERO_IN_DATE and ` NO_ZERO_DATE` to be NOT active. In the example below the section NO_ZERO_IN_DATE,NO_ZERO_DAT needs to be removed and the MySQL server restarted.

Listing 23. my.cnf (Unix) or my.ini (Windows)
[mysqld]

sql_mode=ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION
3.8.6.4. MariaDB

MariaDB is a fork of MySQL and still largely compatible with MySQL. The configuration in Unblu is slightly different though.

Please consult the configuration section of MySQL before creating the user and database.
Listing 24. Create the unblu database and users
CREATE DATABASE unblu DEFAULT CHARACTER SET = utf8 DEFAULT COLLATE utf8_general_ci;

GRANT SELECT,UPDATE,INSERT,DELETE ON unblu.* TO 'unblu'@'%' IDENTIFIED BY 'secret';
GRANT SELECT,UPDATE,INSERT,DELETE,CREATE,ALTER,DROP,INDEX,REFERENCES ON unblu.* TO 'unblu_admin'@'%' IDENTIFIED BY 'admin_secret';
Listing 25. Unblu MariaDB configuration
com.unblu.storage.database.platform=org.eclipse.persistence.platform.database.MySQLPlatform
com.unblu.storage.database.driver=org.mariadb.jdbc.Driver
com.unblu.storage.database.url=jdbc:mysql://<server>:3306/unblu (1)
com.unblu.storage.database.jdbcProperties=connectTimeout=60000,socketTimeout=60000,useUnicode=yes,characterEncoding=UTF-8,useLegacyDatetimeCode=true,serverTimezone=UTC,useSSL=false
com.unblu.storage.database.user=unblu
com.unblu.storage.database.password=<pwd> (2)
com.unblu.storage.database.schema=unblu
com.unblu.storage.database.liquibaseSchema=unblu
com.unblu.storage.database.adminUser=unblu_admin
com.unblu.storage.database.adminPassword=<pwd> (3)
1 Replace <server> with your database hostname or IP address.
2 Replace <pwd> with the password of the unblu user.
3 Replace <pwd> with the password of the unblu_admin user.
3.8.6.5. MSSQL
Listing 26. Create the unblu database and users
CREATE DATABASE unblu;
USE unblu;

CREATE LOGIN unblu WITH PASSWORD = 'Unblu_Secret';
CREATE LOGIN unblu_admin WITH PASSWORD = 'Admin_Secret';

CREATE USER unblu_admin FOR LOGIN unblu_admin;
CREATE USER unblu FOR LOGIN unblu;

GRANT CREATE TABLE TO unblu_admin AS dbo;
GRANT ALTER, REFERENCES ON SCHEMA::dbo TO unblu_admin AS dbo;
GRANT SELECT, INSERT, UPDATE, DELETE ON SCHEMA::dbo TO unblu_admin;
GRANT SELECT, INSERT, UPDATE, DELETE ON SCHEMA::dbo TO unblu;
Listing 27. Unblu MSSQL configuration
com.unblu.storage.database.platform=org.eclipse.persistence.platform.database.SQLServerPlatform
com.unblu.storage.database.driver=com.microsoft.sqlserver.jdbc.SQLServerDriver
com.unblu.storage.database.url=jdbc:sqlserver://<server>:1433;DatabaseName=unblu (1)
com.unblu.storage.database.user=unblu
com.unblu.storage.database.password=<pwd> (2)
com.unblu.storage.database.schema=dbo
com.unblu.storage.database.liquibaseSchema=dbo
com.unblu.storage.database.adminUser=unblu_admin
com.unblu.storage.database.adminPassword=<pwd> (3)
1 Replace <server> with your database hostname or IP address.
2 Replace <pwd> with the password of the unblu user.
3 Replace <pwd> with the password of the unblu_admin user.
3.8.6.6. In Memory database

When no database configuration is present, Unblu will by default start using an embedded H2 database. This allows an administrator to log in and perform tests.

All data will be lost when you restart the server process. Do not use the in memory database for any production use case.

3.8.7. Use a dedicated document storage

A relational database is not an ideal location to store larger binary files such as documents uploaded into a conversation by agents or visitors. We therefore recommend to use Amazon S3 or a compatible service (i.e. min.io).

Listing 28. Unblu Configuration to use min.io
com.unblu.server.storage.blob.persistantstoretype=S3
com.unblu.server.storage.blob.store.s3.bucketName=local-dev
com.unblu.server.storage.blob.store.s3.endpoint=http://minio.example.com:9001 (1)
com.unblu.server.storage.blob.store.s3.folder=blobs
com.unblu.management.aws.accesskey=<key> (2)
com.unblu.management.aws.secretkey=<secret> (3)
1 Remove this line to use AWS S3 instead of min.io.
2 Add the access key here.
3 Add the access secret here.

All of the configurations below can be added at the schema level. For example, the statistics database can become very large over time and it may be that you would want to use a separate server for the statistics database. Connection and pool parameters can be added to the configuration file. In such a case all other schemas would use the default connection pool.

Listing 29. Unblu database configuration reference
com.unblu.storage.database.platform=
com.unblu.storage.database.driver=
com.unblu.storage.database.url=
com.unblu.storage.database.jdbcProperties=
com.unblu.storage.database.user=
com.unblu.storage.database.password=
com.unblu.storage.database.schema=
com.unblu.storage.database.liquibaseSchema=
com.unblu.storage.database.adminJdbcProperties=
com.unblu.storage.database.adminUser=
com.unblu.storage.database.adminPassword=
com.unblu.storage.database.poolInitial=
com.unblu.storage.database.poolMax=
com.unblu.storage.database.readPoolUrl=
com.unblu.storage.database.readPoolUser=
com.unblu.storage.database.readPoolPassword=
com.unblu.storage.database.readPoolInitial=
com.unblu.storage.database.readPoolMax=
com.unblu.storage.database.poolMinIdle=
com.unblu.storage.database.adminUser=
com.unblu.storage.database.adminPassword=
3.8.8.1. Connection pool

The default JDBC connection pool is HikariCP.

It provides some improved speed and stability compared to the deprecated EclipseLink connection pool:

  • Connections are closed when not used for a longer period.

  • Connections are validated before using java.sql.Connection.isValid(int) provided by the JDBC Driver. (See Documentation)

  • New connections are proactively opened (not just on demand).

A Grafana dashboard called "Database (HikariCP)" visualizing all HikariCP metrics is automatically deployed with every Unblu cluster installation.

Listing 30. HikariCP default configuration
# Database Connection Pool
com.unblu.storage.database.datasourcefactory=HIKARI
com.unblu.storage.database.poolMax=20 (1)
com.unblu.storage.database.poolMinIdle=20 (2)
1 Maximum number of connections in the pool.
2 Minimum number of connections that should be idle, new connections are added to the pools when connections are busy up to the configured maximun number of connections.

The above configuration reflects the default starting from Unblu 6, please only add a connection pool configuration when you want to deviate from this default.

Listing 31. Legacy EclipseLink pool configuration
# Database Connection Pool
com.unblu.storage.database.datasourcefactory=INTERNAL
com.unblu.storage.database.poolInitial=1
com.unblu.storage.database.poolMax=20
Instead of the approaches listed in this chapter, you can also use a datasource provided by the application server. Please refer to this chapter for instructions.

4. Front and Back End Integration

As we saw in the sections Front End Interfaces and Integrations and Back End Integrations Unblu offers a number of connection points for integrating different kinds of interfaces and additional functionality. In the following section we will look at each of these integration points in more detail.

4.1. Overview

In terms of our earlier Basic System Components diagram, we will be looking at the highlighted components below:

Produced by OmniGraffle 7.11.2 2019-09-13 12:01:48 +0000 Canvas 1 Layer 1 Company Network Mobile Visitor Unblu Server Back End Integration Web API Webhooks Agent on Mobile Agent Front End Integration Agent Mobile SDK Internal Company Systems Database Rendering Service External Service TokBox Service Company Website Web Visitor External Service Unblu Cloud TURN Server Agent on Web Rendered Co-Browsing Video & Voice Agent Front End Built-in Agent Desk Admin Interface Config Interface Visitor Front End Integration Individual UI JS API Visitor Front End Integration Visitor Mobile SDK SecureFlow Asset Upload
Figure 8. Integration System Components

4.2. Individual UI Web Integration

To enable the Individual UI on your website the Unblu installation must be integrated with your web infrastructure. This involves addressing three issues:

  • How is the client code for the Individual UI included in your website page? The options are dynamic injection or static inclusion.

  • Where is the Unblu Server positioned insideyour infrastructure? The options are site-embedded or cross-origin.

  • Do you need support for protected resource upload to the agent?

These options only apply in an on-premises deployment. In a cloud deployment dynamic injection, site-embedded integration and protected resource upload are not supported. Consequently, all cloud deployments use static inclusion and cross-origin integration and do not have protected resource upload.

4.2.1. Client-Side Code Inclusion

When an Unblu-enabled website is initially requested by a visitor’s browser the returned page includes not just the normal website code but also extra code that implements the Unblu visitor interface. This extra Unblu client code can be included in your website code by either static inclusion or dynamic injection.

4.2.1.1. Static Inclusion

In this method you alter your website markup to include a small JavaScript snippet that loads the Unblu client code. This involves placing a small JavaScript snippet on in the code of the website page on which you wish to display the visitor interface launcher button. This method is relatively simple but you do need access and permission to change the actual code of the website in question.

Listing 32. Unblu snippet example
<!DOCTYPE html>
<html>
<head>
    <script type="text/javascript" defer="defer"
        src="https://unblu.cloud/unblu/visitor.js?x-unblu-apikey=YOUR_API_KEY"></script> (1)
</head>
<body>
    <!-- Your HTML body -->
</body>
</html>
1 Replace YOUR_API_KEY with your API key.

The JavaScript snippet with the correct key can also be copied from the API keys section in the Account Configuration.

For certain use cases you might not need the snippet on all pages. For example when you want Unblu’s Universal or Document Co-Browsing only on a specific section of your website, it is sufficient to instrument only those pages.
4.2.1.2. Dynamic Injection

In this method you install a reverse proxy in front of your website server that includes the SecureFlow Manager. This method does not involve any changes to the website code itself, but it does involve installation of software on your corporate infrastructure. If you already have a suitable cache/reverse proxy installed you may be able to simply add the SecureFlow Manager to it.

The SecureFlow Manager will manage the injection of the required JavaScript into the pages to enable the Individual UI. It also provides the protected resource upload functionality (see below).

For details on installation see SecureFlow Manager Deployment.

4.2.2. Server Positioning

4.2.2.1. Site Embedded

The following diagram depicts the site-embedded scenario:

Company Network
[Not supported by viewer]
Company
Website
Backend
[Not supported by viewer]
Web Visitor
[Not supported by viewer]
Unblu
Server
[Not supported by viewer]
SecureFlow
Manager
[Not supported by viewer]
Proxy
[Not supported by viewer]
URI
Mapping
[Not supported by viewer]
Dynamic JS
Injection
[Not supported by viewer]
www.bank.com/*
[Not supported by viewer]
www.bank.com/unblu
<font color="#1d3479">www.bank.com/unblu</font>
Figure 9. Site-Embedded Install

In this setup both the Unblu server and your company website server sit behind a proxy. Note that in this case the diagram also depicts the SecureFlow Manager as being installed on the proxy server. In most situations where a site-embedded integration is used, the SecureFow Manager will also be used (and thus dynamic injection and protected resource upload will both be enabled). However, strictly speaking the two factors are independent: SecureFlow Manager can be used without site-embedded integration and vice versa.

4.2.2.2. Cross-Origin

The following diagram depicts the cross-origin scenario:

Company Network
[Not supported by viewer]
Company
Website
Backend
[Not supported by viewer]
www.bank.com
[Not supported by viewer]
Web Visitor
[Not supported by viewer]
Unblu
Server
[Not supported by viewer]
unblu.bank.com
[Not supported by viewer]
Figure 10. Cross-Origin Install

In this setup the Unblu server and your company website server are exposed separately to the internet. Typically this arrangement is used with static inclusion, though as above, the factors are independent: cross-origin installation could theoretically be used in conjunction with dynamic injection provided by a SecureFlow Manager.

4.2.3. Protected Resource Upload

As discussed in XX, embedded co-browsing works by capturing the state of the DOM of the Unblu-enabled website on the visitor browser and transferring that state to the agent browser.

Once the DOM is rebuilt on the agent browser there are typically additional resources (stylesheets, images, etc.) that the browser must request to complete the rendering of the visitor’s view.

In many cases these resources will be inaccessible without authentication and authorization, for example, if they are part of a bank’s e-banking site. In normal circumstances, such as in the case of the visitor browser, this does not present a problem since that browser will already be signed in to the site. However, co-browsing is a special case. The agent browser will not have the same authorization as the visitor browser and yet, in order to properly render the visitor’s view, it needs access to the protected resources.

Since uploading the resources from the visitor browser is considered unsafe and would usually be too slow, Unblu solves this problem with the SecureFlow Manager, a software component installed in a proxy in front of the website server that caches the resources and uploads them on demand to the Unblu server, from where the agent browser can successfully request them and build an accurate rendition of the visitor’s view.

4.3. JavaScript API

The JavaScript API is an optional add-on to the Unblu Individual UI website integration. It allows JavaScript to access and control certain functions related to the Individual UI.

4.3.1. Concepts

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

For security reasons, the JS API can only perform actions that the current visitor has the right to perform. 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.

The visitor JS API is meant to be used for actions directly connected to the current visitor and that visitor’s usage of the Individual 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 Web API either directly in JS or via custom REST services provided by your own server.

4.3.2. Reference

Details about integrating the Visitor JS-API into your website and how to use it can be found in the reference documentation unblu-visitor-js-api Be aware that this page is updated with the changes of the latest Unblu 5 version.

If you run an older Unblu 5 installation you might prefer getting the documentation page directly from your Unblu Server:

<unblu-server>/unblu/static/js-api/v2/docs/index.html

This page describes the JS API as it is available on your server.

4.4. SecureFlow Manager Deployment

4.4.1. Overview

The SecureFlow Manager is a component that can be used to integrate Unblu into your website infrastructure. It serves multiple purposes:

  1. Dynamically inject the Unblu JavaScript snippet. This eliminates the need to modify the source code of the instrumented website.

  2. Intercept the traffic of active co-browsing sessions and upload resources (CSS, images, and similar) to Unblu’s backend. This allows co-browsing of protected applications requiring a valid session such as online banking.

  3. Integrate Unblu into a website using the same domain as the original website. (This could also be achieved using any reverse proxy supporting path based routing.)

Unblu’s SecureFlow Manager is optimized for stability and resilience and will not interfere with your normal web traffic when Unblu is not active.

4.4.2. Compatible Reverse Proxies

The SecureFlow Manager can be installed as a module into the following products.

Other products may be integrated upon request.

4.5. Mobile SDK

The Mobile SDKs for Android and iOS can be used to integrate Unblu into mobile applications for visitors or agents. When the SDK is integrated into an app, the app can use many of the same features as are available to visitors and agents through the web interfaces (chat, co-browsing, notifications, etc.).

4.5.1. Mobile SDK Requirements

The mobile SDK requires the following platforms / versions.

Operating System Supported Version SDK Type

iOS

10 (or newer)

Framework

Android

5 (or newer)

Android Archive

4.5.2. Features

The following features can be used when interacting with the SDKs:

  • Dynamically de-/initialize the API

  • Check if a connection to the Unblu server could be established

  • Start a chat conversation

  • Start a mobile co-browsing conversation

  • Start an audio/video call

  • Adding/Removing private views, which should not be displayed to the agent/visitor (e.g., password fields)

  • Add/update custom cookies which are sent with each request to the Unblu server

  • In app events for API state, session state, notifications (e.g., agent/visitor joint messages, chat messages), errors (More details can be found in the code documentation which is provided together with the SDK for each platform.)

  • Push notifications about unread messages and incoming calls

For the visitor SDK there are additionally the following features:

  • Check if an agent is available

  • Join a conversation via a PIN from the agent

The following features are available in co-browsing sessions:

  • Co-browsing all content of the app

  • Interactions of the user with the device screen can be seen remotely

  • Orientation changes are displayed on the agent side

  • Lock screen displayed on agent desk, if the visitor puts the app into the background.

  • Areas of the app can be marked remotely

  • Chat between visitor and agent inclusive UI

  • Start an audio/video call

4.5.3. Architecture Overview

The above diagram shows how the mobile SDKs are integrated into the Unblu environment. Additionally it shows the OpenTok and Firebase Server which are used inside the SDKs via their libraries.

4.5.4. Configuration on the Unblu server

The following configuration properties are important for the mobile SDKs.

Configuration Property Description

messenger.mobileVisitorSdkEnabled

Whether or not the visitor mobile SDK is enabled. This must be enabled so that the visitor SDK on a mobile device can initialize. Otherwise it is not usable at all.

messenger.mobileAgentSdkEnabled

Whether or not the agent mobile SDK is enabled. This must be enabled so that the agent SDK on a mobile device can initialize. Otherwise it is not usable at all.

messenger.mobileCoBrowsingEnabled

Whether or not the mobile co-browsing with the SDKs is enabled. If it is not enabled, the SDKs can still be used for chat or call conversations.

conversation.feature.mobileCoBrowsingEnabled

Same as messenger.mobileCoBrowsingEnabled but on conversation level. This can be configured differently for each conversation and conversation templates.

cobrowsing.startWithMobileCobrowsingOptionEnabled

Enables the possibility to start a mobile co-browsing conversation. Such a conversation directly starts the mobile co-browsing when the conversation is accepted in the queue.

visitor.ui.showRequestMobileCobrowsingEngagementOption

When the Unblu UI is displayed in the app, the UI offers the possibility to start a mobile co-browsing conversation.

4.5.5. Integration

For the iOS integration please go to Mobile SDK - iOS Integration.

For the Android integration please go to Mobile SDK - Android integration .

4.5.6. Mobile Push Notifications

The following configuration properties need to be set to be able to send/receive mobile push notifications from the Unblu Unblu server via firebase cloud messaging to the mobile devices.

Configuration Property Description

mobile.push_notification.enablePushNotification

Enables in general notifications. Currently there are email and mobile push notifications.

mobile.push_notification.enableFirebasePushNotification

Enables push notifications via firebase cloud messaging.

mobile.push_notification.firebaseDatabaseName

The name of the firebase database where the app is configured for firebase cloud messaging.

mobile.push_notification.firebaseServiceAccountKey

The account key to allow the Unblu server to access firebase cloud messaging.

For more information about firebase cloud messaging, please look at the official documentation found here.

Depending on the operating system that you are targeting refer to:

To go directly to the mobile SDKs API documentation:

4.5.7. Mobile SDK - Android Integration

This section describes how the visitor/agent SDK can be integrated into an Android app. It describes step by step from adding the aar files to use the api, whereby it gives some hints to get a good user experience and avoid some common pitfalls.

4.5.7.1. Android Archive Integration

For android, Unblu provides android archive (AAR) files for release and debug. Additionally some public sources are provides as .jars which contain also the JavaDoc of the public classes.

In total there are the following files:

  • coresdk-debug-x.x.x.aar

  • coresdk-release-x.x.x.aar

  • coresdk-public-sources-x.x.x.jar

  • visitorsdk-debug-x.x.x.aar

  • visitorsdk-release-x.x.x.aar

  • visitorsdk-public-sources-x.x.x.jar

  • agentsdk-debug-x.x.x.aar

  • agentsdk-release-x.x.x.aar

  • agentsdk-public-sources-x.x.x.jar

Typically one would use the release aar files and add the public-sources jar files to get the JavaDoc in the IDE. The coresdk.aar needs to be added always. Depending on the type of the app, if it should be for a visitor or for an agent, either the aar file for the visitor or agent sdk needs to be added too.

The easiest way to add the dependency to gradle is to use the android studio wizard. It can be found in File/Project Structure and must be executed ones for the coresdk and either the visitor or agentsdk files.

  1. To open the wizard click the green plus sign on the top left.

  2. In the wizard, select the Import .JAR/AAR Package section. After the path definition to the SDK AAR file is set, it is added as a module.

  3. In the app/Dependencies section of the Project Structure dialog you must define the dependency from the app to the SDK module. This can be done with the green plus on the right side and choosing Module dependency. Now the SDK is linked to the application.

    The AAR files in android do not provide any javadoc information. To add this information, you must switch from the Android Project view to the Project view.

  4. Find the Unblu SDK in the External Libraries section then right-click to open the Library Property. After clicking the green plus, the path to the unblusdk-public-sources.jar file can be defined. Now the javadoc is available inside the IDE.

Note: The *-public-sources.jar files only contains the sources for the public API part and cannot be used as a library as it does not contain the internal classes.

The Unblu SDKs use Firebase Cloud Messaging for push notifications. For Firebase to work correctly, it is necessary that the google-services.json file from the Firebase project is added to the app. Additionally you need to add the following line at the end of your app gradle file.

apply plugin: 'com.google.gms.google-services'

Please follow the instructions from here for detailed information.

Important to know is also, that it is not necessary to setup Firebase in your code. This is automatically done by the SDK when push notifications are enabled.

4.5.7.2. Permissions

The following permissions are required in the applications manifest for different features.

Permission Key Required for Feature

android.permission.INTERNET

Required to use the internet connection

android.permission.SYSTEM_ALERT_WINDOW

Required to overlay the Unblu UI on top of the application. This permission is automatically granted by the app store.

android.permission.WRITE_EXTERNAL_STORAGE

Required to save files which should be downloaded

android.permission.RECORD_AUDIO

Required from OpenTok for audio and video sessions (also for plain audio sessions)

android.permission.CAMERA

Required from OpenTok for audio and video sessions

android.permission.MODIFY_AUDIO_SETTINGS

Required from OpenTok for audio and video sessions (also for plain audio sessions)

android.permission.BLUETOOTH

Required from OpenTok if bluetooth device is used inside calls

android.permission.BROADCAST_STICKY

Required from OpenTok (no details available)

android.permission.READ_PHONE_STATE

Required from OpenTok (no details available)

4.5.7.3. Code Setup and Initialization
4.5.7.3.1. UnbluApplication

In order to ensure the SDK works properly you must set the attribute android:name in the application tag of the AndroidManifest.xml file to either com.unblu.visitorsdk.UnbluVisitorApplication or config:com.unblu.agentsdk.UnbluAgentApplication. Alternately, to your own custom application class, which then inherits from one of the above classes. See the code snippet below for an example.

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.unblu.testapp">

    <application
        android:name="com.unblu.visitorsdk.UnbluVisitorApplication"> <!-- there a may also some other attributes -->
        </application>
</manifest>

If this is not possible in your application, you can use the UnbluVisitorApplicationHelper or UnbluAgentApplicationHelper. They define a couple of static functions like onCreate(..), which need to be called in the corresponding functions of the used Application class. The names of the functions in the helper class are the same as the one from the Application class. Additionally in the JavaDoc it is stated if the function needs to be called before or after the super call.

4.5.7.3.2. Unblu API Instance

The most important class of the visitor SDK is UnbluVisitorApi and of the agent SDK it is UnbluAgentApi. They provide an getInstance() function, which can be used to get an instance of the API.

Note: The UnbluApi is defined as a singleton, so there is only one instance of it. Therefore further usages of the instance member will not create additional instances.

4.5.7.3.3. Unblu API Configure

Before using the instance of the UnbluVisitorApi/UnbluAgentApi, it needs to be configured. The api can be configured using the function UnbluVisitorApi#configureApi(..) / UnbluAgentApi#configureApi(..). It accepts an instance of UnbluVisitorApiConfiguration / UnbluAgentApiConfiguration. This class can be instantiated with the base url of the Unblu server and the API key of the Unblu account.

For all possible configurations and their effects, take a look at the documentation of UnbluVisitorApiConfiguration / UnbluAgentApiConfiguration. There is only a very limited set of configurations which can be done on via the Unblu SDKs. All configurations which are independent of the client (the app) can be done via the Unblu agent desk.

To properly separate the configuration for the mobile visitor and agent SDK and also from configurations done for the webpage where Unblu is integrated, we recommend to use different API Keys for each environment.

Inside the Unblu API instance, only a copy of the configuration is stored. So it can not be changed by the reference. A new call to configureApi has to be done. Configuring the API can only be done while it is not initialized and it would throw an exception if it is already initialized.

Normally the configuration should only be done once at the beginning.

4.5.7.3.4. Events

Before you initialize the API you should register for events in order to be sure not to miss any.

In android this can be done by using a custom implementation of UnbluVisitorEventReceiver for the visitor sdk and UnbluEventReceiver for the agent SDK. Additionally for UI events a subclass of UnbluUiEventReceiver can be used. An instance of such an receiver will register himself in the given context. Therefore it should typically be instantiated inside the Activity.onStart method and should be unregistered in the Activity.onStop via Activity.unregisterReceiver.

Detailed information on the events can be found inside the IUnbluEventApiVisitor / IUnbluEventApi and UnbluUiEventApi class. They also provides constants to get the values out of an Intent if this is done manually without a subclass.

A very important event is the UiVisibilityRequest. As soon as push notifications are used, it is recommended to listen for this event. E.g. there is a push notification, when there is an incoming call. If the user opens the app by clicking the notification, the SDK directly will fire this event and assumes that the app will initialize and opens the Unblu UI as soon as possible.

4.5.7.3.5. Initialization and Deinitialization

To initialize an instance of UnbluVisitorApi / UnbluAgentApi the function initApi(..) can be called.

The callback parameters can be used to get information about success and errors. Additionally the IUnbluEventApi.Error event can be used as described in the events section. Regarding on errors it is highly recommended to register for the api error event globally to not miss an error as they can happen independent of an explicit call to the api.

After the success callback was triggered, the Unblu UI can be displayed, new conversations can be started, agent availability can be checked, etc…​

The API can either be initialized directly or only on demand. For example when co-browsing is needed. Note that when the API is initialized on demand the SDK will take some time until it is ready and a session can be started. Additionally if push notifications are used, it is required at least once to have the API initialized. Otherwise the Unblu Unblu server has no connection between a user and the device. Therefore in general we recommend to initialize the API as soon as it is possible (directly after login).

If the SDK is no longer needed and everything should get cleaned up, there is the deinitApi(..) function.

4.5.7.4. Unblu UI

The UnbluVisitorSDK/UnbluAgentSDK provides an Unblu UI which shows all existing conversations and which can be used to chat and make a call inside a conversation. This UI can be displayed on top of the app UI. It is controlled also be using the instance of the UnbluVisitorApi/UnbluAgentApi. It is possible to open/close and change its top/bottom margin. Additionally it can be checked if it is open or if a call is currently displayed. For those states there are also events defined in the IUnbluUiEventApi.

screenshot mobile sdk android

If there is an issue with the Unblu SDK, please be aware that the UI is rendered inside a WebView. Therefore it is possible to attach the local Chrome to check if for error logs. It is a limitation of the android WebViews that it is not possible to see the full content of logs inside the normal debugger console.

Note that there are several functions like opening a conversation or starting and audio/video call require to open the UI at least once so that the corresponding part was loaded in the javascript. You can find details about in the documentation of each function and the error callbacks may need to implement this case.

If, at some point, it is likely that the user would use the Unblu UI, we would recommend you preload the UI. This can be achieved by either configuring to preload the UI with the initialization (see UnbluCoreApiConfiguration#setPreloadAfterInitEnabled(..)) or by calling UnbluCoreApi#preloadUi(..) if the API was already initialized previously.

4.5.7.5. UnbluUiButton

Next to the Unblu UI, the SDKs provide the class UnbluUiButton. This button UI can be placed inside the app UI either via xml or directly in the Code. Typically the button will be placed in the lower right corner of the screen.

The user can use the button to toggle the visibility of the Unblu UI.

The button displays a number of unread chat messages when new messages arrive and the UI is hidden. Additionally it can automatically set the bottom margin for the Unblu UI and places a semi transparent background behind it.

To integrate it, please follow the instructions in the UnbluUiButton class documentation.

4.5.7.6. Private Views

The SDKs provides a simple way to add specific views which should not be shown on the remote side. To do this, the UnbluVisitorApi/UnbluAgentApi provides the function addPrivateView(..) which takes an id. Each view as his own id.

After a view id is added, it is automatically overlaid by an image before the screen is transmitted to the remote side. It is also possible to make a view visible to the remote side again by calling the removePrivateView(..) function.

4.5.7.6.1. Custom Cookies

It is possible to define custom cookies, which should be sent with each request to the Unblu server. This can either be done (initially) by using the UnbluVisitorApiConfiguration/UnbluAgentApiConfiguration#setCustomCookies(..) or by setting the the cookies dynamically via the setCustomCookies(..) function. Before the API is initialized, always the last cookies configured are used. If the API is already initialized, cookies with the same name are overridden and new cookies are added. The previously-defined cookies will stay until the API is de-initialized. If the API is then initialized again, only the last defined cookies are used again.

4.5.7.6.2. Named Areas

Similar to a web page, the named area feature is also available for the mobile SDKs.

A named area can either be set via the UnbluVisitorApiConfiguration/UnbluAgentApiConfiguration#setNamedArea(..) before initializing the API. Or else it can be set by calling UnbluCoreApi#setNamedArea(..) on the UnbluVisitorApi/UnbluAgentApi instance.

If a named area is set before initializing the API, also the specific configuration for it is loaded on initialization. If it is later set, it only changes the requests for new conversations in the agent desk queue in the way that the agent can filter by the named area. The named area has no effect for existing conversations.

As consequence, it is important to know if there will be specific configuration on the named area scope. In this case the named area has to be configured/set in the SDK before initializing the API, but then it should be always considered to change the configuration on API Key level. If a named area are only used for the queue, it can be set at any time before starting a new conversation.

4.5.8. Mobile SDK iOS Integration

This section describes how the visitor/agent SDK can be integrated into an iOS app. It describes step by step from adding the framework files to use the api, whereby it gives some hints to get a good user experience and avoid some common pitfalls.

4.5.8.1. Framework Files

Unblu provides different framework files for the different platforms: simulator, real device and a fat framework.

A fat framework contains both platforms and is typically the best choice. However, for a release in the Apple AppStore the x86 framework must be removed using Apple’s “lipo” tool as Apple does not allow binaries for the simulator. There are several scripts on the internet that can be used to strip the simulator part away while building the app. Those scripts need to be added to the build phases of the app.

In total there are 5 files.

  • UnbluCoreSDK.framework

  • UnbluCoreSDKResources.bundle

  • UnbluVisitorSDK.framework

  • UnbluVisitorSDKResources.bundle

  • UnbluAgentSDK.framework

  • UnbluAgentSDKResources.bundle

The agent and visitor SDK are build as static framework files. Therefore it is required that the resources of a framework file are provided via bundle files. The UnbluCoreSDK.framework and UnbluCoreSDKResources.bundle need to be added always. Depending on the type of the app, if it should be for a visitor or for an agent, either the framework and bundle for the visitor or agent sdk needs to be added too.

To add the files to an Xcode project, they can be dragged and dropped to Xcode. Automatically the framework files get added to the project settings Build Phases > Link Binary With Library and the bundle files get added to the Build Phases > Copy Bundle Resources. Additionally the framework files need to be added manually to the settings of the project in General > Embedded Binaries.

As Unblu only provides static frameworks, it does not deliver the dependencies with them. The following table shows the dependencies which need to be added to the app. We prefer to add the dependencies via [CocoaPods](https://cocoapods.org/), but the tables also gives a link on how to integrate the library manually.

Name Version CocoaPods Podfile Manual Integration Link Purpose

OpenTok

~> 2.16

pod ‘OpenTok’, ‘~> 2.16’

https://tokbox.com/developer/sdks/ios/ Using the SDK

Needed for audio/video calls

Firebase Core

~> 6.7

pod ‘Firebase/Core’, ‘~> 6.7’

https://firebase.google.com/docs/ios/setup#frameworks

Base for firebase messaging

Firebase Messaging

Derived from Firebase Core

pod ‘Firebase/Messaging’

https://firebase.google.com/docs/ios/setup#frameworks

Needed for push notifications

For Firebase to work correctly, it is also necessary that the GoogleService-Info.plist file from the Firebase project is added to the app. Please follow the instructions from here to add it to your project. Important to know is also, that it is not necessary to setup Firebase in your code. This is automatically done by the SDK when push notifications are enabled.

4.5.8.2. Swift Compatibility
4.5.8.2.1. Objective-C

The frameworks provides from Unblu are written in Swift and not with Objective-C as Swift is the new standard from Apple. In theory Swift code can be used in Objective-C. But actually there are some limitations. E.g. enums in Swift need to have a raw type of Int. Therefore it is not simply possible to use the SDKs in an Objective-C environment. The project which was formally an Objective-C project, would need to be changed to a Swift project, which mainly uses Objective-C. Then the usage of an SDK is required to be wrapped into a Swift helper, which can be used in Objective-C. Currently Unblu does not provide any Swift helper classes.

4.5.8.2.2. Swift Versions

In 2014 Apple wrote:

“… if your project uses frameworks to share code with an embedded extension, you will want to build the frameworks, app, and extensions together. It would be dangerous to rely upon binary frameworks that use Swift — especially from third parties. As Swift changes, those frameworks will be incompatible with the rest of your app. When the binary interface stabilizes in a year or two, the Swift runtime will become part of the host OS and this limitation will no longer exist.

The binary interface has not, unfortunately, ‘stabilized’ yet. This means that the Swift version of the used Unblu SDK must match the Swift version of the App. In case the used Unblu SDK from Unblu was build with an older version, the project could be change to a different Swift Language Version inside the project compiler settings. This, unfortunately, does not work always. In this case there are two possibilities. First download an older version of the XCode Toolchain to be compatible again. Second update to a newer version of the Unblu SDK.

Typically Unblu always tries to provide the SDKs for the newest Swift version. If you need the Unblu SDK for an older Swift version, because the app is still on an older version, you can ask the Unblu support for it.

4.5.8.3. Permissions

The following permissions are required in the applications info.plist for different features.

Permission Key Required for Feature

NSPhotoLibraryAddUsageDescription

Required to add downloaded images to photos app

NSPhotoLibraryUsageDescription

Required to upload images from photos app into a conversation

NSCameraUsageDescription

Required from OpenTok for audio and video sessions (also for plain audio sessions)

NSMicrophoneUsageDescription

Required from OpenTok for audio and video sessions

4.5.8.4. Code Setup and Initialization

To use Unblu the SDK in the code of an application, it is necessary to specify the import of the corresponding SDK. Either use import UnbluVisitorSDK or import UnbluAgentSDK.

4.5.8.4.1. AppDelegate

The AppDelegate of the app should inherit from the UnbluUiApplicationDelegate. This is needed for Unblu to setup correctly the Firebase and push notification integration.

The UnbluUiApplicationDelegate implements some of the functions from the protocol UIResponder, UIApplicationDelegate, MessagingDelegate it implements. For some of the functions it is possible to override them again in the AppDelegate, but then it is typically necessary to call the super implementation. Some functions, e.g. for the messaging are not possible to override again.

If the app itself uses push notifications, the UnbluUiApplicationDelegate provides those functions with an on_ prefix. The benefit of this is, that the used Unblu SDK checks for Unblu push notifications. Only for notifications which are not for the SDK, it calls the on_ prefixed functions. This means the app itself does not need to filter out the Unblu push notifications.

If for some reason it is not possible to use the UnbluUiApplicationDelegate as base class, there are several things which are needed to do manually. E.g. Firebase and its messaging part needs to be configured; The handling of app launches from a push notification click and the handling of new incoming push notifications needs to be forwarded to the SDK. This is not covered by this documentation. Please ask the Unblu support for more details on it.

4.5.8.4.2. Unblu API Instance

The most important class of the visitor SDK is UnbluVisitorApi and of the agent SDK it is UnbluAgentApi . They provide an instance function, which can be used to get an instance of the API.

It is highly recommended to get an instance of the UnbluVisitorApi/UnbluAgentApi class inside the AppDelegate.application function by calling instance. In this way the SDK can register itself for all required app events before one of them is fired.

Note: The UnbluApi is defined as a singleton, so there is only one instance of it. Therefore further usages of the instance member will not create additional instances.

4.5.8.4.3. Unblu API Configure

Before using the instance of the UnbluVisitorApi/UnbluAgentApi, it needs to be configured. The api can be configured using the function configureApi. It accepts an instance of UnbluApiConfiguration. This class can be instantiated with the base url of the Unblu server and the API key of the Unblu account.

For all possible configurations and their effects, take a look at the documentation of UnbluApiConfiguration. There is only a very limited set of configurations which can be done on via the Unblu SDKs. All configurations which are independent of the client (the app) can be done via the Unblu agent desk.

To properly separate the configuration for the mobile visitor and agent SDK and also from configurations done for the webpage where Unblu is integrated, we recommend to use different API Keys for each environment.

Inside the Unblu API instance, only a copy of the configuration is stored. So it can not be changed by the reference. A new call to configureApi has to be done. Configuring the API can only be done while it is not initialized and it would throw an exception if it is already initialized.

Normally the configuration should only be done once at the beginning.

4.5.8.4.4. Events

Before you initialize the API you should register for events in order to be sure not to miss any.

In iOS this can be done by using NotificationCenter. Inside the Notification.Name object all Unblu events are available with “Unblu” as the prefix. Detailed information on the events can be found inside the UnbluEventApi and UnbluUiEventApi class. They also provides constants to get the values out of the Notification.userInfo member.

A very important event is the UiVisibilityRequest. As soon as push notifications are used, it is recommended to listen for this event. E.g. there is a push notification, when there is an incoming call. If the user opens the app by clicking the notification, the SDK directly will fire this event and assumes that the app will initialize and opens the Unblu UI as soon as possible.

4.5.8.4.5. Initialization and Deinitialization

To initialize an instance of UnbluVisitorApi/UnbluAgentApi the function initApi can be called.

The callback parameters can be used to get information about success and errors. Additionally the UnbluEventApi.Error event can be used as described in the events section. Regarding on errors it is highly recommended to register for the api error event globally to not miss an error as they can happen independent of an explicit call to the api.

After the success callback was triggered, the Unblu UI can be displayed, new conversations can be started, agent availability can be checked, etc…​

The API can either be initialized directly or only on demand. For example when co-browsing is needed. Note that when the API is initialized on demand the SDK will take some time until it is ready and a session can be started. Additionally if push notifications are used, it is required at least once to have the API initialized. Otherwise the Unblu Unblu server has no connection between a user and the device. Therefore in general we recommend to initialize the API as soon as it is possible (directly after login).

If the SDK is no longer needed and everything should get cleaned up, there is the deinitApi function.

4.5.8.5. Unblu UI

The UnbluVisitorSDK/UnbluAgentSDK provides an Unblu UI which shows all existing conversations and which can be used to chat and make a call inside a conversation. This UI can be displayed on top of the app UI. It is controlled also be using the instance of the UnbluVisitorApi/UnbluAgentApi. It is possible to open/close and change its top/bottom margin. Additionally it can be checked if it is open or if a call is currently displayed. For those states there are also events defined in the UnbluUiEventApi.

screenshot mobile sdk ios

If there is an issue with the Unblu SDK, please be aware that the UI is rendered inside a WebView. Therefore it is possible to attach the local Safari to check if for error logs. It is a limitation of the iOS WebViews that it is not possible to see the logs inside the normal debugger console.

Note that there are several functions like opening a conversation or starting and audio/video call require to open the UI at least once so that the corresponding part was loaded in the javascript. You can find details about in the documentation of each function and the error callbacks may need to implement this case.

If, at some point, it is likely that the user would use the Unblu UI, we would recommend you preload the UI. This can be achieved by either configuring to preload the UI with the initialization (see UnbluApiConfiguration) or by calling preloadUi if the API was already initialized previously.

4.5.8.6. UnbluUiButton

Next to the Unblu UI, the SDKs provide the class UnbluUiButton. This button UI can be placed inside the app UI either via the Xcode Interface Builder or directly in the Code. Typically the button will be placed in the lower right corner of the screen.

The user can use the button to toggle the visibility of the Unblu UI.

The button displays a number of unread chat messages when new messages arrive and the UI is hidden. Additionally it can automatically set the bottom margin for the Unblu UI and places a semi transparent background behind it.

To integrate it, please follow the instructions in the UnbluUiButton class documentation.

4.5.8.7. Private Views

The SDKs provides a simple way to add specific views which should not be shown on the remote side. To do this, the UnbluVisitorApi provides the function addPrivateView which takes a tag. A tag can be defined for each view.

After a view tag is added, it is automatically overlaid by an image before the screen is transmitted to the remote side. It is also possible to make a view visible to the remote side again by calling the removePrivateView function.

4.5.8.7.1. Custom Cookies

It is possible to define custom cookies, which should be sent with each request to the Unblu server. This can either be done (initially) by using the UnbluApiConfiguration or by setting the the cookies dynamically via the setCustomCookies function. Before the API is initialized, always the last cookies configured are used. If the API is already initialized, cookies with the same name are overridden and new cookies are added. The previously-defined cookies will stay until the API is de-initialized. If the API is then initialized again, only the last defined cookies are used again.

4.5.8.7.2. Named Areas

Similar to a web page, the named area feature is also available for the mobile SDKs.

A named area can either be set via the UnbluApiConfiguration before initializing the API. Or else it can be set by calling setNamedArea on the UnbluVisitorApi/UnbluAgentApi instance.

If a named area is set before initializing the API, also the specific configuration for it is loaded on initialization. If it is later set, it only changes the requests for new conversations in the agent desk queue in the way that the agent can filter by the named area. The named area has no effect for existing conversations.

As consequence, it is important to know if there will be specific configuration on the named area scope. In this case the named area has to be configured/set in the SDK before initializing the API, but then it should be always considered to change the configuration on API Key level. If a named area are only used for the queue, it can be set at any time before starting a new conversation.

4.6. External Messenger Integration

Note: External messengers are supported with Unblu server version 6.

4.6.1. Overview

At the moment Unblu provides a generic way to integrate external messengers. An external messenger can be any communication tool which is basically text based, e.g. Email, SMS, WhatsApp.

One external messenger can be represented as multiple external messenger channels inside Unblu server. E.g. In WhatsApp a company can have 2 business accounts. For each account a channel would be created inside the Unblu server. Those channels are named CustomExternalMessengerChannel. In the future there will be also be tighter integrations of some messengers like WhatsApp into the product.

A conversation is always linked to one channel. Either to Unblu internally itself or to one external messenger channel. This can not be changed afterwards. It means if a conversation should be continued via Unblu internal messaging, a new conversation needs to be created.

4.6.2. Integration

4.6.2.1. Integration Custom Channel