Contact usRequest a demo

This document describes version 6 of Unblu. If you’re using the latest major version of Unblu, go to the documentation of the latest version.

The support period for version 6 ended on 29 August 2023. We no longer provide support or updates for this version. You should upgrade to the latest version of Unblu.

Configuring and manipulating collaboration layers

Collaboration layers work out of the box, but they might not work exactly the way you want them to. This article will show how you can change that.

First we will discuss the various aspects of collaboration layers in general that you can configure. We will then go into each collaboration layer individually.

Collaboration layers are configured on a conversation or conversation template basis. This means that you can opt to configure collaboration layers differently for different engagement types or different named areas. For example, support agents may only need embedded co-browsing, whereas relationship managers should also have the option of co-browsing documents with their clients.

It is possible to change settings for collaboration layers on individual active conversations. This article will only refer to conversation templates, since that is the more general case.

Prerequisites

Before you start configuring collaboration layers in specific conversation templates, you must activate the licensed collaboration layers. If you don’t, the settings for those layers will not be available in the settings of your conversation templates.

You can activate the collaboration layers in the GLOBAL (i.e. server) or ACCOUNT scope with the following configuration properties:

To upload files for document co-browsing, you must also enable file sharing:

Mobile co-browsing can be enabled if

All of these configuration properties are in the Account Settings section of the account configuration interface, under the heading Popular features .

General configuration options

The collaboration layers that Unblu provides differ in their use cases and the underlying technology employed. At the same time, they share a variety of features:

  • Conversation participants can launch and stop collaboration layers, and you can specify which person types may do so.

  • Launching a collaboration layer may require the approval of other participants. You can specify which cases require approval.

  • You must specify which collaboration tools you want to allow participants to use.

  • You can make the use of collaboration tools subject to the approval of other participants.

  • You can show or hide various UI elements pertaining to collaboration layers.

As a result, a number of configuration properties are present for some or all of the collaboration layers. There are also several configuration properties that affect more than one collaboration layer:

Launching a collaboration layer

There are a number of ways to launch a collaboration layer. Which method users choose will depend on the stage of a conversation they are in and their role in the conversation. You can specify who may (or may not) launch a collaboration layer in a conversation.

Which collaboration layers may be launched in a given conversation is determined by two factors:

  • The collaboration layer must be enabled in the Conversation feature configuration section of a conversation template’s settings.

  • There must be conversation participant capable of sharing the collaboration layer in question. If, for example, nobody is taking part in the conversation with an app that uses the Unblu Mobile SDK, it will not be possible to launch a mobile co-browsing session. In such a case, the controls to launch a mobile co-browsing session will not appear, even if they would be available according to the conversation template’s settings.

Launching a collaboration layer from the Agent Desk

Please refer to the Agent Desk guide for information on how to launch and manage collaboration layers in the Agent Desk.

Launching a collaboration layer from the Visitor Individual UI

In a running conversation, a number of settings influence how visitors can launch collaboration layers.

  • You can enable visitors to do so in the Conversation action bar configuration section of the account settings. You can opt to make launching a certain collaboration layer available in the conversation action bar or in the overflow menu. However, this option does not become available to the visitor until an agent has joined the conversation.

    Please refer to the descriptions of the configuration properties in that section of the configuration properties reference to learn more about the scopes you can define these settings on.

    This feature also affects the conversation action bar in the Agent Desk.

  • Another possibility for visitors to launch a new collaboration layer is by means of the collaboration layer controls. For the controls to be visible, the visitor must have a person type listed in the com.unblu.conversation.collaboration.showLayerControls setting of the relevant conversation template. Furthermore, their person type must be present in com.unblu.conversation.collaboration.switchLayers.

    The visitor collaboration layer controls are only visible if another collaboration layer is already running. This means that once a conversation has started, a visitor can only launch a new collaboration layer from these controls if a different collaboration layer is already running.

    A single conversation may have multiple collaboration layers running concurrently. When someone launches an additional collaboration layer, the previous layer remains available.

  • By and large, not many visitors will start a conversation by opening a collaboration layer. You can, however, enable them to do so in the Messenger configuration section of your account or server settings.

    The collaboration layers visitors can start a conversation with are:

    • Embedded co-browsing

    • Mobile co-browsing

    • Screen sharing

    It is only possible to launch a collaboration layer if there is a conversation participant who can actually share the layer in question. If none of the conversation participants is using an app that integrates the Unblu Mobile SDK, for example, it will not be possible to launch a mobile co-browsing session, even if your configuration is such that it is possible in principle.

Approving a collaboration layer

Each collaboration layer has a configuration property to define whether visitors must approve its use. When set to true, the context person must explicitly consent to launching the collaboration layer. If the collaboration layer would display the screen contents of another participant, e.g. a secondary visitor or agent, that participant must also approve the collaboration layer. Unblu will only launch the collaboration when all relevant participants have given their approval.

Stopping a collaboration layer

Each collaboration layer has a configuration property to specify which categories of conversation participants may stop a collaboration layer.

The relevant properties are grouped in the Conversation collaboration configuration section of the configuration properties reference.

Collaboration tools

Unblu includes a number of tools to make working with collaboration layers more effective.

Mark mode

Allows conversation participants to mark an area of the view being shared in the conversation.

Remote control

Allows a conversation participant to take control of the pointer in the collaboration layer. If the layer contains editable fields, the participant may be granted permission to edit them.

Scroll lock

Locks in place the section of the page currently being displayed.

A participant who activates scroll lock and remote control will be able to scroll on a page without moving the section of the page that the other participants can see. For example, a support agent can look for something on a page without inducing motion sickness in a visitor.

Not all of the collaboration tools are available in all collaboration layers. If a tool is available in a particular collaboration layer, there will be a configuration property to enable it for different categories of conversation participants. See the sections below on the individual collaboration layers for further details.

The collaboration tools are configured on conversations or conversation templates, which offers you great flexibility. You might decide, for example, that relationship managers should be granted full control of the collaboration layer in conversations with their clients. In conversations between support agents and visitors, on the other hand, agents should only be allowed to mark sections of the layer.

If a participant is not entitled to use a tool or carry out an action, the control to do so will not be available to them in the collaboration layer controls.

Other collaboration layer actions

There are a number of other actions that participants can carry out in collaboration layers:

Stop

Stop a collaboration layer. This is defined separately for each collaboration layer.

Access navigation bar

Access the browser’s navigation bar in the collaboration layer. Only relevant for embedded co-browsing and universal co-browsing sessions.

Switch layer configuration

Switch between different collaboration layers. The action is granted to types of conversation participants. Activate with the setting com.unblu.conversation.collaboration.switchLayers.

Display inactive layers

Show which other types of collaboration layer are available even though they are not currently being used in the conversation. This action, too, is granted to types of conversation participants. Activate with the setting com.unblu.conversation.collaboration.action.displayInactiveLayers.

Configuring embedded co-browsing

To enable embedded co-browsing for an account or a server, set the following property to true:

How embedded co-browsing is made available to users is affected by these configuration properties:

In conversation templates, the configuration properties for embedded co-browsing are:

Specifying agent actions in remote control mode

If remote control mode is enabled in embedded co-browsing, agents can click, scroll, enter input, and select radio buttons and checkboxes. You can determine which of these actions should be available to agents with the following configuration properties:

Listing 1. Configuration properties for agent actions in embedded co-browsing remote control mode 
# Enable support for click events in embedded co-browsing
com.unblu.domcap.remoteaction.clickEnabled=true
# Enable support for input field change events in embedded co-browsing
com.unblu.domcap.remoteaction.inputChangeEnabled=true
# Enable support for scroll events in embedded co-browsing
com.unblu.domcap.remoteaction.scrollEnabled=true
# Enable support for HTML SELECT element change events in embedded co-browsing
com.unblu.domcap.remoteaction.selectionEnabled=true

The settings are grouped in the Remote support action configuration section of the conversation template settings.

Skipping DOM elements

Modern web pages often consist of a surprisingly large number of DOM elements. Single page applications, for example, often load content that is hidden from users until they perform some action or other. Capturing such hidden or irrelevant elements on a page for embedded co-browsing makes little sense. This can result in unnecessary network traffic and have a negative impact on the performance of the embedded co-browsing collaboration layer.

To mitigate these issues, Unblu allows you to specify that it should skip certain elements when capturing the DOM for embedded co-browsing. There are three ways to do this:

  1. The custom HTML attribute x-unblu-skip-element

  2. The JS property unbluSkipElement

  3. With a custom JavaScript function specified in the configuration property com.unblu.domcap.externalSkipElementFunctionName

Skipping DOM elements with x-unblu-skip-element

By applying the custom HTML attribute x-unblu-skip-element to elements of the page you don’t need in embedded co-browsing sessions, you can exclude those elements from Unblu’s DOM capturing process.

The example below skips the HTML element with the ID virtualKeyboard:

Listing 2. Adding the attribute x-unblu-skip-element to an HTML button to prevent it from being exposed in the embedded co-browsing session 
<div class=“virtual-keyboard” x-unblu-skip-element=“true” id=“virtualKeyboard”></div>

Skipping DOM elements with unbluSkipElement

You can use JavaScript to select an element or elements in the pages and set the property unbluSkipElement to true.

The example below has a similar effect to the example in the previous section: it skips the HTML element with the ID virtualKeyboard.

Listing 3. Skipping the virtualKeyboard element during DOM capturing using unbluSkipElement 
var d = document.getElementById("virtualKeyboard");
d.unbluSkipElement = true;

Skipping DOM elements with a custom JavaScript function

Sometimes, determining whether to capture or skip an element is a complex operation. In such cases, you may prefer to implement the logic that carries out this evaluation in a function within your own application. If you do, you must provide Unblu with the name of the function it should call to decide whether or not to skip an element. For this purpose, Unblu has the configuration property com.unblu.domcap.externalSkipElementFunctionName.

Suppose you want to skip elements that satisfy one of the following conditions:

  • The element’s aria-hidden attribute is true.

  • The element has the attribute x-custom-attribute.

  • The element has the attribute hidden.

To this end, you add the following function to your application at the window level:

Listing 4. Custom JavaScript function to determine whether Unblu should capture or skip an element 
function simpleSkipElementFunction(targetElement) {
	if (targetElement && targetElement.getAttribute) {
		return (
			targetElement.getAttribute("aria-hidden") === "true" ||
			targetElement.hasAttribute("x-custom-attribute") ||
			targetElement.hasAttribute("hidden")
		);
	}
	return false;
}

To get Unblu to use the function, set com.unblu.domcap.externalSkipElementFunctionName to simpleSkipElementFunction. The configuration property may be set in the ACCOUNT and GLOBAL scopes.

Once none of the conditions in your function apply, Unblu will detect the change and include the element when it captures the DOM.

Hiding specific page elements in a co-browsing session (field masking)

If you only want to mask a field, that is, exclude the content (value) of HTML text input fields from being captured by Unblu, add the custom HTML attribute unbluCapturingHint to the element and set its value to block:

Listing 5. Hiding the content of a text input field from agents 
<input type="text" unbluCapturingHint="block"/>

Other conversation participants will only see asterisks instead of the field’s actual content.

You can also protect HTML elements from being edited. To do so, add the custom attribute unbluEditingHint to the element and set it to "block":

Listing 6. Preventing agents from editing or activating an HTML element 
<div unbluEditingHint="block">...blocked content...</div>

Agents who click on the element will merely see a lock icon.

Limitations of embedded co-browsing

Embedded co-browsing has a number of limitations. Please read the article Limitations of embedded co-browsing for more details.

Configuring universal co-browsing

This section does not discuss how to configure the rendering service, which is a prerequisite for both universal and document co-browsing. Please review the article Configuring the Unblu rendering service for details on how to configure the rendering service.

To enable universal co-browsing for an account or a server, the following property must be true:

How user can launch universal co-browsing is affected by the next configuration property:

The following configuration properties are available to configure universal co-browsing in conversation templates:

You can influence a number of aspects of the Chromium browser that universal co-browsing uses:

The language of the headless browser is determined by the language of the conversation. If a conversation is, say, in Swedish, then the headless browser used for the universal co-browsing session will behave like a Swedish browser running on a Swedish operating system.

For further information on how the language of a conversation is set, read our article on setting the locale.

Determining the headless browser’s viewport size

There are several configuration properties that influence the headless browser’s viewport size:

To determine the viewport, each participant’s browser sends their maximum viewport size to the collaboration server. If a participant has multiple tabs open, the maximum viewport size is sent for each tab. Each time a user resizes a window, the new viewport size is sent to the collaboration server. The server collects this information for all of the participants in the collaboration session. It then determines the viewport size with the largest possible area and checks the value against the configuration properties listed above.

If necessary, participants will see a scaled image of the viewport to ensure that they all see the same content. To illustrate how this may work, imagine a collaboration between an agent and a visitor:

  • The agent has a new 4k screen with the resolution set to 3840x2160.

  • The visitor, on the other hand, has poor eyesight and has therefore set their screen’s resolution to 800x600.

  • The headless browser will render a window 800x600 large, which is then streamed to the agent. Their view of the window is scaled up to fit their browser window. If this didn’t happen, their view of the shared browser view would be too small to be of much use.

Setting the headless browser’s time zone

When a universal co-browsing session is launched, the time zone of the headless browser is set to that of the participant who launched the co-browsing session. It does so by reading the timezone property of the object returned by the Intl.DateTimeFormat.prototype.resolvedOptions() method (see this MDN article for more details).

If Unblu is unable to determine the user agent’s time zone, it will use the time zone defined in com.unblu.platform.server.geolocation.defaultTimeZone. The default value is Europe/Zurich.

Apply specific behavior in a universal co-browsing session

For universal co-browsing sessions, the rendering service launches a Chromium browser in headless mode. That browser’s user agent string includes the rendering service and its version. This provides a way of checking if a page is being displayed in a universal co-browsing session:

Listing 7. Check if a page is running in a universal co-browsing session 
<script type="text/javascript">
if (navigator.userAgent.indexOf("UnbluRenderingService") != -1) {
	// Your amazing code that should only run in a universal co-browsing session,
	// e.g. to load additional CSS or manipulate the DOM
}
</script>

Alternatively, you can check whether the unbluCefObject exists:

Listing 8. Check if unbluCefObject exists 
<script type="text/javascript">
if (typeof(unbluCefObject) != undefined) {
	// Your amazing code that should only run in a universal co-browsing session,
	// e.g. to load additional CSS or manipulate the DOM
}
</script>

This can be useful in a number of situations, For example, you could include such a check on internal pages to ensure that they aren’t shared with customers by accident.

Keyboard input during universal co-browsing

One advantage of universal co-browsing is the possibility for all participants to enter information in a single shared browser. Sometimes, however, this may not work as expected.

Certain characters users enter may not be displayed, as if they hadn’t been transmitted to the rendering service. The reason for this is how browsers and operating systems handle keyboard events.

Most keyboards provide the possibility to enter characters that are not available as key legends by using dead keys in combination or sequence with another key. This is particularly common for characters with diacritics, such as â, ñ or ź.

For example, to write ñ on a keyboard with a US layout, you must first press Shift+~, then press N. The first step, pressing Shift+~, does not produce any output by itself. Instead, it starts a composition event. Once the second key (N in our example) is pressed, the desired letter ñ is composed.

If you want to see for yourself the individual steps required to generate a character, you can use the W3C keyboard event viewer.

Universal co-browsing sessions take place in a headless browser running on Ubuntu Linux. When the rendering service receives a character generated by a composition event, it must therefore translate it into a native Linux event. Unfortunately, this is not always possible for composed characters, since some of the information required for the translation is no longer available. As a result, these characters are not displayed in the universal co-browsing session.

The simplest way to work around this limitation is to copy characters that aren’t displayed from another program and then paste them into the collaboration layer browser.

Configuring document co-browsing

This section only deals with configuration properties that affect how users may leverage document co-browsing. Please review the article on configuring the Unblu rendering service for information on configuring the rendering service.

To enable document co-browsing on an account or a server, set the following configuration property to true:

You must also enable file sharing, or participants will not be able to upload documents to co-browse:

Review the following configuration properties in your conversation templates to configure document co-browsing according to your needs:

Like universal co-browsing, document co-browsing takes place in a Chromium browser running in headless mode.Participants can thus co-browse files formats supported by Chromium, such as PDF files or images.

Using document co-browsing with files of a type other than PDF relies on third-party services and involves uploading the files to the servers of those third parties. Please read the data security section of the rendering service deployment documentation and the section on supported file types for further information.

Document storage options

Most conversation data are stored in a relational database. Depending on how heavily you use document co-browsing, this may not be a suitable solution for you. Fortunately, you can configure Unblu to use Amazon S3 or a compatible service like min.io as a document storage. Please read the section on using a dedicated document storage of the database deployment documentation for more information.

Configuring mobile co-browsing

For mobile co-browsing to work with your app, you will first have to integrate Unblu into the app using the Unblu mobile SDK for Android or iOS. Please read the appropriate sections of the Unblu documentation on iOS and Android integration for information on how to do so, and consult the mobile SDK references.

To enable mobile co-browsing for your account or server, the following configuration property must be true:

This configuration property is only available if

  1. com.unblu.license.account.featureMobileSdkVisitor is defined

  2. com.unblu.messenger.mobileVisitorSdkEnabled is true

Where participants can launch a mobile co-browsing session is determined by the next two configuration properties:

The following configuration properties allow you to customize mobile co-browsing to suit your organization’s needs:

As you can see from the list of configuration properties, there is no remote control mode in mobile co-browsing.

Configuring screen sharing

To enable screen sharing for your account or server, the following configuration property must be true:

These configuration properties determine how conversation participants may launch screen sharing sessions:

The settings only have an effect for visitors if the browser and operating system they are using meet the technical requirements to launch a screen sharing session. This is not the case for Internet Explorer 11, for example.

In your conversation templates, review the following configuration properties to get screen sharing working the way your organization wants:

As you can see from the list above, there are no collaboration tools available in screen sharing sessions.

You can affect the size that the shared screen is displayed at with the configuration properties below. Obviously, the settings only affect participants who aren’t sharing their screen.

These properties are set in the GLOBAL or the ACCOUNT scope, not on conversation templates.

Screen sharing features that rely on MediaDevices.getDisplayMedia()

Browsers that support the MediaDevices.getDisplayMedia() method of the Screen Capture API provide additional screen sharing features: sharing audio while screen sharing, and the option to restrict sharing the entire screen.

You can enable audio sharing by setting com.unblu.conversation.allowSharingAudio to true.

Sharing the entire screen can be enabled on a per-role basis with the configuration property com.unblu.conversation.allowSharingEntireScreen. If sharing the entire screen is enabled for the user’s role, Unblu works as before. If, on the other hand, sharing the entire screen is not enabled for the user’s role, how Unblu behaves depends on the user’s browser:

  • If the user’s browser does not support detecting the MediaTrackSettings.displaySurface of the source, screen sharing will be disabled entirely. This is the case for Mozilla Firefox, Apple Safari, and older versions of Microsoft Edge not based on Chromium.

  • If the user’s browser allows detection of the source using MediaTrackSettings.displaySurface, the user will be able to select a source to share. The source may be

    • a browser tab,

    • a window, or

    • the entire screen.

    If the user opts to share the entire screen, Unblu will display a dialog stating that they can only share a browser tab or a window. Selecting the OK button allows the user to select a different source to share. Selecting the Cancel button aborts the screen sharing session.

Both audio sharing and the restrictions on sharing the entire screen are set in the CONVERSATION scope.

The features described in this section were introduced in Unblu 6.33.0.