Cobrowse Visitor API

The Visitor API allows you to customize the visitor side behavior of Cobrowse.

Parameters

GLANCE_COBROWSE

You can control Cobrowse parameters by setting properties on the Javascript object window.GLANCE_COBROWSE.

Note: GLANCE_COBROWSE must be defined before the Glance cobrowse script initializes.

Properties/Methods

The following properties can be set on GLANCE_COBROWSE. These properties, apart from getMaskingDescriptor, would typically be set if the visitor is logged in and the information is known at the time the page is rendered.

Any or all these properties may be set.

If name, email, and phone number are defined prior to the cobrowse script initializing, then those values are stored with that session participant's record in the Glance database once the session starts.

Example

GLANCE_COBROWSE = {
  visitorid: "59204gh-42",
  name: "Joe Smith",
  email: "jsmith@example.com",
  phone: "314-555-1212"
};

GLANCE.Cobrowse.Visitor

The GLANCE.Cobrowse.Visitor object is defined in any web page that includes the Glance Cobrowse script tag.

A sample code which implements a Cobrowse user interface using GLANCE.Cobrowse.Visitor can be found here: https://www.glance.net/cobrowse/js/GlanceCobrowseCustomUI.js.

Properties and Methods

The following properties and methods are available on GLANCE.Cobrowse.Visitor. Methods marked with ^* can only be called when there is a session active.

if (GLANCE.Cobrowse.Loader.setUIReady)
GLANCE.Cobrowse.Loader.setUIReady()

^* May only be called when a session is active.

Using GLANCE.Cobrowse.Visitor methods

Using startSession()

startSession() starts a Cobrowse session. You may use it in one of two ways.

1. startSession(key), where key is a string, uses that key for the new session. A session key can be up to 100 characters long and contain the following characters: numbers, letters (upper or lower case), underscore (“_”), dash (“-”), and tilde (“~”). Other characters are not supported.

   If the value of sessionKey is "GLANCE_KEYTYPE_RANDOM", a random key is generated. If neither sessionKey nor GLANCE_COBROWSE.visitorid is defined, a random key is generated.

2. startSession(options) starts a session using the parameters specified in options.

   options may contain any of the following properties:

   • groupid (Optional) ID of the Glance group in which to start the session. If no groupid is present, the session starts in the group specified in the data-groupid attribute of the cobrowse <script> tag.
   • sessionKey (Optional) Session key. See above for behavior when sessionKey is not specified.
   • name Visitor name
   • email Visitor email
   • phone Visitor phone number
   • content "visible" "hidden" (defaults to "visible") not supported

If the session should start with video, and the agent who will join has multiparticipant video privileges, the following VideoParams parameters can be specified:

• video "large" "small" "off" indicates initial video state
• videosource device id of the camera to show
• previewelementid id of video preview element (defaults to glance_videopreview)
• camerastatus "blocked", "nocamera", "available", "error"
• videopaused true if visitor's video should start paused, false if video is on

Example

To specify a key and start a session, make this call.

GLANCE.Cobrowse.Visitor.startSession("ABCD");

To start a session with a randomly generated key, make this call.

GLANCE.Cobrowse.Visitor.startSession("GLANCE_KEYTYPE_RANDOM");

To start a session in large video mode, make this call.

GLANCE.Cobrowse.Visitor.startSession({video:'large'})

To provide multiple parameters, use Javascript code like this.

var options =
   {
     sessionKey : "ABCD",
     name : "Julie Smith",
     email : "jsmith@example.com",
     phone : "314-555-1212"
   };
GLANCE.Cobrowse.Visitor.startSession(options);

Using crossDomain()

Please see Cobrowse Cross-Domain for details.

crossDomain(options) sends session information to all the domains listed in the Cross Domain trust list, allowing the Cobrowse session to continue if and when the visitor navigates to pages on those domains.
crossDomain() returns a promise which resolves when the process is complete.

promptCrossDomain(options) (see VisitorUI API here) works exactly like crossDomain(options), and prompts the user for permission first. crossDomain() opens a temporary pop-up window. So, to avoid triggering a pop-up blocker, it must be called in response to a user action such as a click or keystroke. promptCrossDomain() does not trigger a pop-up blocker because the user clicks "Yes" to start the cross domain process.

The options parameter contains these properties.

• url The url to open
• target Where to display the url. It may have the values "_self" or "_blank", indicating whether url should open in the same window or a new window.

The options parameter is optional. If specified, then crossDomain(option) redirects to the url once the session information has been sent.

crossDomain(options) opens a popup window and therefore should only be called in response to a user action such as a click or keystroke, in order to avoid potentially triggering a pop-up blocker.

Using pauseSession

GLANCE.Cobrowse.Visitor.pauseSession(params) can be used to pause/unpause a cobrowse session.

If you want the session to start paused or for a page to be paused on load, add data-startpaused=1 to the cobrowse script tag. This will avoid a race condition where a page is uploaded to the session before pauseSession can be called. The session will be paused as soon as the visitor navigates to a page with data-startpaused="1".

While a cobrowse session is paused, no page updates will be sent to the viewers. The viewer will display a frozen view of the session. If a message is specified in the call to pauseSession, that message will be displayed over the agent viewer, completely covering the frozen view. When a cobrowse session is unpaused, a full update will be sent to the viewers.

pauseSession only applies to the current page. When the visitor navigates to a new page, the session is unpaused, unless the new page has data-startpaused specified in the script tag.

A website built in React or another single page application platform can call pauseSession as views change, to control what is shown/hidden in a cobrowse session.

If an additional agent or guest joins while the session is paused, the second agent sees the same paused state as the first.

The params object can contain the following properties:

var params = {pause: true, message: "This session is paused."}

   GLANCE.Cobrowse.Visitor.pauseSession({pause: true, message: "This session is paused."}) // this pauses it and displays the message on the agent side.

   GLANCE.Cobrowse.Visitor.pauseSession({pause: false}) // this unpauses the session

Using notifyChanged()

Browsers cannot automatically notify the Glance Cobrowse visitor script when canvas elements change. Some modifications to canvas elements, therefore, are not detected and the agent view is not updated accordingly. This results in canvas based graphs or drawings not rendering correctly on the agent side.

Canvas drawing is performed by customer's Javascript running in the browser. If customers add a call to GLANCE.Cobrowse.Visitor.notifyChanged() when this happens, the Cobrowse script can capture the changes and send them to the agent view.

The Cobrowse script adds a unique ID to each canvas element as an attribute "data-gcid". The data-gcids are used to identify which canvas elements have changed.

Example

This example page contains two canvas elements, <canvas id="c1"> and <canvas id="c2">. After some script runs which draws on those canvases, the following API call will notify the Cobrowse script that the canvas drawings have changed:

if (GLANCE && GLANCE.Cobrowse && GLANCE.Cobrowse.Visitor) {
    var canvases = { canvas:
        { gcids: [$("#c1").attr("data-gcid"),
                  $("#c2").attr("data-gcid")] }};
    GLANCE.Cobrowse.Visitor.notifyChanged(canvases);
}

The important part of the canvases object in this example is the array of data-gcids. Notice the if statement. It allows your Javascript to work even when cobrowsing is not active. This example uses jQuery to select each canvas element and obtain the value of its "data-gcid" attribute.

Using continueSessionAt()

Deprecated. See Using crossDomain.

continueSessionAt() allows a Cobrowse session to continue even if the visitor navigates to a page on a different domain. The destination domain must be a website that is tagged with the Glance Cobrowse script tag.

On the Cobrowse Settings Page, include both source and destination domains in the list of domains that are trusted for Cross Domain Cobrowse on the Cobrowse Settings page.

Normally, Cross Domain Cobrowse works automatically once domains are listed under Cross Domain Cobrowse. However, if the visitor navigates to a destination domain via a server or client side redirect, as opposed to clicking on a link or button, then it will be necessary to call continueSessionAt() before the redirect occurs.

Example

if (GLANCE && GLANCE.Cobrowse && GLANCE.Cobrowse.Visitor) {
   var params = {
       // The destination domain
       destination : "example.com",    
       // (optional) A destination helper url to use instead of
       // the one configured on the Cobrowse Settings page
       destinationurl : "https://example.com/helper",
       // A function to call when the session data
       // has been passed to the new domain
       oncomplete : completionFunction,
       // (optional) Set to true if the warning is suppressed
       // for Internet Explorer -- the destination page
       // will auto-accept Internet Explorer's  "urlstartwarning" event
       iewarningsuppressed : true
   };
   GLANCE.Cobrowse.Visitor.continueSessionAt (params);
}

Using getMaskingDescriptor()

Glance cobrowse provides a "hook" function to allow customers to customize page and element masking during a cobrowse session.

The hook function is: window.GLANCE_COBROWSE.getMaskingDescriptor(params)

All cobrowse hook function definitions must be included in the page before the Glance Cobrowse script tag is included. If no masking hook is found at the time the Glance Cobrowse script loads, then masking is performed according to the group's masking configuration.

Glance Cobrowse calls the cobrowse masking hook function on every page to which the visitor navigates, before sending page contents to the Agent.

getMaskingDescriptor should return a Promise that resolves to a masking descriptor with the following optional properties:

{
"maskpage": true|false, // default: false
"maskedelements": [array of css selectors]
}

When a cobrowse session starts, the Glance cobrowse script calls GLANCE_COBROWSE.getMaskingDescriptor() before uploading the page contents, and then masks the specified elements or the whole page accordingly.

In addition to calling getMaskingDescriptor when a cobrowse session first starts, the cobrowse script will call getMaskingDescriptor({ agents : [agent information] } ), passing in agent information:

• When an agent or guest joins or leaves the session.
• When the visitor navigates to a new page.

Whenever the cobrowse script calls getMaskingDescriptor, if the masking rules have changed, the script will send a full update to the server applying the current masking rules. This may cause the page to "flash" on the agent side.

Parameters passed to getMaskingDescriptor

Requires Cobrowse 5.2 or later.

If known, information about agents and guests is passed to getMaskingDescriptor through the params object: { agents : [agent information] }

The agent information passed to getMaskingDescriptor is the same as the agent information passed with the "agents" visitor side event, which includes an "agentrole" attribute for agents.

{
    "count": 2,
    "agentlist": [
        {
            "username": "fred.glance.net",
            "guestid" : 42309845,
            "partnerid": 12345,
            "partneruserid": "fred@myco.com",
            "name": "Fred O'Hare",
            "title": "",
            "role": "agent",
            "agentrole" : "Business Unit 1",
            "num": 1
        },
        {
            "role": "guest",
            "guestid" : 8549238,
            "name": "Nina Winston",
            "num": 2
        }
    ]
}

When the session first starts, getMaskingDescriptor will be called with params.agents undefined. As agents and guests join or leave, getMaskingDescriptor will be called again with the current agent information.

Masking based on Agents in Session

The agents information passed to getMaskingDescriptor can be useful for implementing masking based on agent role or agent ID.

Once information is unmasked in a session, it will be visible to new agents who join the session, from the time the agent joins until the masking rules are updated with a new call to getMaskingDescriptor. Therefore when implementing role based masking using getMaskingDescriptor, your account should be configured to only allow agents in the same role to join a given session.

See the Role Based Masking example below.

The Cobrowse Masking Hook and Masked Element Selectors Configured on the Group

Page and element masking can also be implemented with configuration settings on your account. If masking rules are specified in the group configuration, then the rules specified by getMaskingDescriptor are combined with the group level rules as follows:

The "maskpage" property, if specified, overrides the page masking determination based on the Allow/Deny list configured in the Glance database.

The "maskedelements" in the masking descriptor are used in addition to the masked element selectors configured for the group.

Error Handling

If the getMaskingDescriptor Promise rejects, the entire page is masked.

Examples

Masking Based on Web Service

In this example, the set of masked elements is based on the results of a web service request.

GLANCE_COBROWSE.getMaskingDescriptor = async function () {
    return new Promise(async (resolve, reject) => {
        // Read an agent identifier from a cookie
        let agenttoken = Cookies.get("agenttoken")

        // Query a web service, passing the agenttoken
        let maskinginfo = await fetch(`/api/GetAgentMaskRules?id=${agenttoken}`)
        if (!maskinginfo.ok)
            reject("Error attempting to query masking info")
        else resolve({
                    "maskpage": false,
                    "maskedelements": maskinginfo.json().maskedelements
                })
    })
}

Role-Based Masking

In this example, the set of masked elements is based on the roles of agents in the session. Agents in role "Northeast Region" can see elements on the page with data-agentrole="northeast region". Elements on the page with data-agentrole set to any other value will not be displayed.

This implementation requires that you have configured roles in the Account Management site.

See more info below about configuration options for handling agents with multiple roles in the same session.

// Hook function called by cobrowse script to get masking information
GLANCE_COBROWSE.getMaskingDescriptor = async function (params) {
    return new Promise(async (resolve, reject) => {

        let maskingdescriptor = {};

        // If agent information is not yet available, mask everything with a data-agentrole attribute
        if (!params.agents || params.agents.count === 0)
            maskingdescriptor.maskedelements = ["[data-agentrole]"];
        else
            maskingdescriptor.maskedelements = [`[data-agentrole]:not([data-agentrole='${params.agents.agentlist[0].agentrole.toLowerCase()}'])`];

        resolve(maskingdescriptor);
    })
}

Multiple Roles

When a new agent joins a session, the agent is briefly shown the same view that the existing agent(s) see, possibly including information not intended for agents in the new role. A group may optionally be configured to prevent agents from joining a session if the new agent's role does not match the existing agent's role. Contact Glance Support to change this configuration.

Multiple Roles Allowed

If enabled by Glance Support, agents with different roles may join the session. The customer's masking hook may update the masking rules according to the mix of agents in the session, but the agent with the new role may initially see all the page elements that were displayed to the original agent.

Multiple Roles Not Allowed

If not enabled by Glance Support, an agent joining with a different role will see an error message.

An agent who is not assigned to a role may only join sessions with other "no role" agents.

Agents can admit guests regardless of whether multiple agent roles are allowed.

GLANCE.Cobrowse.Visitor.isPageMasked()

This function returns true if the page is masked.

Error Event

Event: "maskingerror"

"maskingerror" fires if there is an error determining masked fields. The payload of the event is { “reason” : msg } where msg is the exception string.