Contact usRequest a demo

Configuring the universal co-browsing collaboration layer

Universal co-browsing lets agents and visitors view websites together that haven’t been instrumented with Unblu. To do so, the Rendering Service launches a Chromium browser in headless mode, and all conversation participants interact with that browser to view the website together.


Before you start configuring universal co-browsing in specific conversation templates, you must activate it. If you don’t, the settings for universal co-browsing aren’t available in the settings of your conversation templates.

You can activate universal co-browsing in the GLOBAL or ACCOUNT scope with the configuration property com.unblu.messenger.universalCoBrowsingEnabled.

General configuration options

For information on general configuration options, refer to the section General configuration options of the article Configuring and manipulating collaboration layers.

Universal co-browsing configuration properties

This section doesn’t discuss how to configure the Rendering Service, which is a prerequisite for both universal and document co-browsing. Review the article Configuring the Unblu Rendering Service for details on how to configure the Rendering Service.

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

You can also 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 behaves like a Swedish browser running on a Swedish operating system.

For more information on how the language of a conversation is set, read the article Setting the visitor-side 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 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 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 renders 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 1. 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

Alternatively, you can check whether the unbluCefObject exists:

Listing 2. 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

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 aren’t 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+~, doesn’t 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 isn’t always possible for composed characters, since some of the information required for the translation is no longer available. As a result, these characters aren’t 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.

See also