Contact usRequest a demo

Configuring the embedded co-browsing collaboration layer

Embedded co-browsing allows visitors to share their view of an Unblu-enabled website with other conversation participants.

Prerequisites

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

You can activate embedded co-browsing in the GLOBAL or ACCOUNT scope with the following configuration property com.unblu.messenger.embeddedCoBrowsingEnabled.

General configuration options

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

Embedded co-browsing configuration properties

How embedded co-browsing is made available to users is affected by the following 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 many of DOM elements. Single page applications, for example, often load content that’s 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. It 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 lets you 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 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, 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 detects 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 the element merely see a lock icon.

Limitations of embedded co-browsing

Embedded co-browsing has a number of limitations. For more information, refer to Limitations of embedded co-browsing.