Universal and Document Co-browsing (Optional)

The information on this page assumes you are already familiar with how to set up and configure an the collaboration server.

In order to be able to use universal co-browsing and/or document co-browsing in a collaboration server running on your application server, the unblu/renderingservice appliance is required.

Document co-browsing and universal co-browsing require the Rendering Service appliance to be installed. The unblu Rendering Service is based on Docker (https://www.docker.com/). It requires a separate host to run Docker with the rendering service Docker image available at https://hub.docker.com/r/unblu/renderingservice/

For more information on how to install and run a docker engine visit https://www.docker.com/.

For more information on Docker and why we use it see: Docker Explained.

Note: From version 4.2 onwards, the collaboration server requires the Docker rendering service tags to be version-specific to the collaboration server version used. So, if you use unblu 4.2 then 4.2 is the tag version number of the unblu Docker rendering service you must use. unblu 4.3 will use 4.3, and so on.

Universal Versus Embedded Co-browsing

Embedded co-browsing is where we capture the Document Object Model (DOM), images and style sheets using the Filter and the visitor stays inside their browser while we use JavaScript to replicate the browser on the agent side.

Universal co-browsing is where a headless browser runs on our server inside the rendering service and we render the graphical output to both the agent and visitor.

Note: Session-in-context or 'context sharing' is not possible if the session cookie has the HTTPONLY flag. Context sharing means that visitors do not lose their login or shopping cart information when they start co-browsing.

Enable Universal and Document Co-browsing (Optional)

The rendering service appliance is a helper appliance that augments the Collaboration Server with the capability to perform universal co-browsing and document sharing.

Network Connectivity Requirements to run the Rendering Service

SSH Collaboration Server to the Rendering Service

The Collaboration Server must be able to connect to the rendering service using the SSH protocol on a tcp port on the Docker host that is mapped to the tcp port 22 in the Rendering Service container.

HTTP(s) from the rendering service to the Collaboration Server

The Rendering Service container must be able to connect to the Collaboration Server using http(s) with the URL provided in the com.unblu.hbworker.headlessBrowserReverseBaseUrl configuration property.

HTTP(S) Rendering Service to Internet / Intranet

If the Rendering Service is used for universal co-browsing then the rendering service container needs to be able to access all web servers (using HTTP(S)) that need to be available within universal co-browsing. Note that this requirement does not apply when the rendering service is only used for document sharing.

Configure and Run the Rendering Service Appliance

The rendering service appliance is installed / started using the Docker command line tool with the following command:

# Create and start the rendering service container
# <name>: name of the docker container that is created on the docker  
# host 
# <port>: tcp port mapping for the unblu/renderingservice on the docker # host 
#         (the Unblu Server will connect to the
#          unblu/renderingservice through this tcp port)
# <password>: password for the Unblu Server to connect to
#             the unblu/renderingservice
# <tag>: version number
docker run -d --name <name> -p <port>:22 -e PASSWORD=<password> unblu/renderingservice:<tag>

This command creates and starts a container from the rendering service image on the Docker host.

To stop the rendering service container:

# Stopping the rendering service container
# <name>: name of the docker container as given in the "docker run" command above
docker stop <name>

and to start the container again:

# Starting the rendering service container
# <name>: name of the docker container as given in the "docker run" command above
docker start <name>

The rendering service Docker image is stateless and does not store any persistent data, thus it is also possible to use a transient container (create a new container on every start of the system) instead of using a persistent container.

If you want to remove the rendering service use the following command:

# Stop and remove the rendering service
# <name>: name of the docker container as given in the "docker run" command above
docker -t 10 stop <name>; docker rm -f <name>

Configure the Collaboration Server to use the Rendering Service

With the rendering service started you can configure the Collaboration Server to use it with the following configuration properties:

# <collaborationServerBaseUrl>: fully qualified base url of the unblu 
#          collaboration server (reachable from the renderingservice), 
#          i.e. https://unbluserver.mycompany.com 
#          (format: <protocol>://<host>[:<optionalPort>]
# <dockerHost>: host name or IP of the docker host where the unblu/renderingservice 
#               container is running
# <renderingServicePort>: tcp port of the unblu/renderingservice container 
#                         as mapped using the -p <renderingServicePort>:22 
#                         argument in the "docker run" command
# <password>: the password of the unblu/renderingservice
# '/sys-unblu' must be explicitly enabled as it is disabled by default

While the above block deals with the technical requirements to establish connections between the Collaboration Server and the rendering service, the following property is required to enable universal and document co-browsing in unblu as a whole:

# enable universal co-browsing options in agent desk

Test Connectivity of Docker to Collaboration Server

Once Docker has been started with docker run (see above), try to connect from the Collaboration Server into Docker as follows:

Connecting to the docker image
# <port>: port on which docker host is providing access to the image 
#         (corresponds to <port> from docker run command)
# <dockerHost>: host name or IP of the docker host where the 
#               unblu/renderingservice container is running
# <password>: the password specified when starting the unblu rendering service 
#             with docker run
ssh -p <port> unblu@<dockerHost>
Password: <password>

Within the Docker image you should also check whether the connection back to the Collaboration Server works. For that purpose make sure the Collaboration Server has been successfully started. Once it is started, login to the Docker image using ssh (see above) and execute the following:

Connecting back to collaboration server
# <collaborationServerBaseUrl>: fully qualified base url of the Unblu Server. 
#                               Must eventually match with what's specified in the 
#                               unblu.properties file 
#                               (see com.unblu.hbworker.headlessBrowserReverseBaseUrl 
#                               above) 
curl <collaborationServerBaseUrl>/sys-unblu/rest/product/all

# example output from the above command:
product.com.unblu.enterprise_4.3.0.RELEASE-TtILheWJ MAIN

Diagnostic Tools

Some other network diagnostic tools that may help to analyze problems when you are connected with SSH into the unblu Docker image (example):

Example diagnostic tools
# check if dns lookups work
# <collaborationServerHostname>: Hostname or IP of the Unblu Server
nslookup <collaborationServerHostname>

# check if ping works. Note: must be called with sudo. Operation is not permitted otherwise.
# <collaborationServerHostname>: Hostname or IP of the Unblu Server
sudo ping <collaborationServerHostname>

Defining who Controls the Universal Session

To define which party controls a session (AGENT, VISITOR, or BOTH) see "View-Only Mode for Universal".

Rendering Service Hardware Requirements (traditional Web server)

Typical Cluster Setup (Openshift/Kubernetes)

Refresh Behavior in Universal Co-browsing when Migrating Session

  • deployonprem

results matching ""

    No results matching ""