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.

Property/Method Description
visitorid A visitorid is often a user ID or some other string that uniquely identifies the website visitor. If defined prior to the session starting, the visitorid will be used as the session key by default. As such, the visitorid must adhere to the same requirements as a session key, listed here. If using the visitorid for the purposes of establishing a presence connection, then it must be defined before the Glance cobrowse script initializes as noted above.
name Visitor’s name. Up to 63 Unicode characters.
email Visitor’s email address. Up to 127 Latin-1 (​ISO/IEC 8859-1) characters.
phone Visitor’s phone number. Up to 32 Latin-1 (​ISO/IEC 8859-1) characters.
getMaskingDescriptor() getMaskingDescriptor() should return a promise that resolves to a masking descriptor with properties to cutomize page and element masking during a cobrowse session. See Using getMaskingDescriptor()

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.

Property/Method

Description

startSession

 (sessionKey|options)

startSession() starts a session. See Using startSession().

setStartParams

 (options)

setStartParams(options) sets the start parameters in advance for the next session, using the same options object as startSession(options). These session start parameters will be used when the session is started in one of the following ways:

  1. Visitor clicks the standard cobrowse button.
  2. GLANCE.Cobrowse.Visitor.startSession() is called with no arguments.
  3. Visitor clicks the button with the attribute glance_button='startSession'.
  4. Visitor clicks the button with the attribute glance_button='showTerms' and then clicks Accept.

    To clear the start parameters, call setStartParams() with no arguments.
inSession()

inSession() returns true if a session is active and false if not.

toggleVideo()

Toggle video on or off (paused). toggleVideo() may only be called if multiparticipant video has started.

toggleVideoSize()

Toggle video size between small and large video

readyState

readyState indicates the state of the visitor page as it connects to a Cobrowse session. The possible values for readyState are contained in the GLANCE.Cobrowse.Visitor.READYSTATE object:

  • sessionend
  • sessionstarting
  • sessionstart
  • sessioncontinue
  • statereceived

    An event occurs at each state change.

    For example, when adding listeners for these state events, it may be necessary to check readyState to determine whether the event has already occurred.

inSession()

inSession() returns true if in a session, false otherwise.

stopSession()*

stopSession() stops the Cobrowse session.

getKey()*

getKey() returns the session key.

enableRC*

 ([true|false])

enableRC() enables or disables remote control.

getSessionState

 (eventName [, identifier])*

getSessionState() returns the information that was reported in the most recent state event specified by eventName.

For example, getSessionState("agents") returns the object that would have been passed into the agents event listener.

For the Screen Share state, pass the screenshareView as the optional identifier parameter. If the specified event has not yet occurred, getSessionState() returns null.

addEventListener

 (eventName, listener)

addEventListener(eventName, listener) adds a listener function to be called when the event specified by eventName occurs. See Visitor Side Events.

removeEventListener

 (eventName, listener)

removeEventListener(eventName, listener) removes the specified event listener function.

addSessionMessageListener

 (msgName, handler)*

addSessionMessageListener(msgName, handler) adds a handler function that is called when a message with the name msgName is received from an agent.

addSessionMessageListener(msgName, handler) is in the form: function(msgName, msg) {...} where:

  • msgName: the message name.
  • msg: the message payload object that was sent from the agent side in sendSessionMessage.
sendSessionMessage

 (msgName, msg)*

sendSessionMessage(msgName, msg) sends a message with the name msgName and the payload msg to the agent.

getCookieValue()

setCookieValue()

getCookieValue() and setCookieValue() are convenience methods for storing and retrieving values on the Glance Cobrowse session cookie.

It can be helpful to store the UI state in a cookie for faster rendering of the UI when a page first loads. If stored in a cookie, the UI state is available immediately when a page loads instead of waiting for API events that occur only after the visitor script connects to the session server.

These methods can only be called after the sessioncontinue event occurs.

Note: the Glance Cobrowse session cookie is a cookie on your website domain.

getUserState(name)*

setUserState(name, data)*

setUserState() stores information on the Cobrowse session. getUserState() can be used to retrieve user state data. These methods are similar to setCookieValue() and getCookieValue(), except that the data is stored on the server instead of in a browser cookie.

After the visitor navigates to a new page, user state is only available after the statereceived event has fired.

isRandomKey()*

isRandomKey() returns true if the session key was randomly generated by Glance. This method is useful for scenarios when the key only needs to be displayed if it was randomly generated.

viewPDF(params)

viewPDF() opens a PDF file using the Glance Cobrowse PDF Viewer. See PDF Cobrowsing.

viewXLS(params)

viewXLS() opens an Excel file overlaid on the screen. When a web page opens an Excel file, the agent is able to view the Excel file along with the visitor, as with any other cobrowseable web page.

Example:

params = ({url: "https://....xlsx"})

See Excel Cobrowsing for more information.

sendDocument(file)

sendDocument(file) allows visitors and agents the ability to download documents shared during Document Sharing.

notifyChanged(params)

notifyChanged() notifies the Glance Cobrowse script of changes to <canvas> elements. See Using notifyChanged.

crossDomain

 (options)*

crossDomain() sends session information to all domains listed in the Cross Domans trust list, and optionally navigates to a cross-domain URL. See Using crossDomain and Cobrowse Cross-Domain.

promptCrossDomain

 (options)*

promptCrossDomain() works like crossDomain() but prompts the user for permission first to avoid pop-up blockers. See Using crossDomain and Cobrowse Cross-Domain.

continueSessionAt

 (params)

Deprecated See Using continueSessionAt.

isPageMasked()

This function returns true if the page is masked.

pauseSession(params)*

params = {pause : [true|false]} indicates whether the session should be paused or unpaused. This can be used to pause/unpause a cobrowse session. See additional details below in Using pauseSession

isSessionPaused()*

Returns true if the session is currently paused, otherwise returns a falsy value.

setUIReady()

If implementing a custom UI, call GLANCE.Cobrowse.Loader.setUIReady() Once the custom UI has added all GLANCE.Cobrowse.Visitor event listeners.

Note: For customers with a custom UI implemented before Cobrowse 5.4, add:

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

getCallId()*

Returns the Call ID (unique identifier) of the active session. This method would only be available when a session is running.

* 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 contain the following characters: numbers, letters (upper or lower case), underscore (“_”), dash (“-”), and tilde (“~”). Keys may be up to 100 characters long.

    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) 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.

crossDomain() is not supported for Internet Explorer.

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:

Parameter Description Example
pause Pause or unpause the session true|false
message html string An optional message to display to the agent while the session is paused. The message may contain HTML markup.
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 Manage Your Account 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.

By continuing to use the site, you agree to the use of cookies. Learn More