Cobrowse Visitor API

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



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

String Properties

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

Property Description
visitorid If specified, a visitorid is used as the Session Code when a Cobrowse session starts instead of a random key. A visitorid is often a user ID or some other string that uniquely identifies the website visitor. It may contain alphanumeric characters, (-) and (.). If name, email, and phone number are provided, the visitorid is stored with the session record in the Glance database.
name Visitor’s name.
email Visitor’s email address.
phone Visitor’s phone number.



visitorid: "59204gh-42",

name: "Joe Smith",

email: "",

phone: "314-555-1212"


If this variable is defined at the time a session starts, these visitor parameters are used for the session regardless of how the session was started.


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:

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

Property/Method Description
startSession(sessionKey) starts a cobrowse session.
  • If sessionKey is of type "string", that key is used for the session. A session key can contain the following characters: numbers, letters (upper or lower case), underscore, or dash and can be up to 50 characters long.
  • If sessionKey is "GLANCE_KEYTYPE_RANDOM", a random key is generated.
  • If sessionKey is undefined and GLANCE_COBROWSE.visitorid is defined, the visitorid is used as the session key.
  • If neither sessionKey nor GLANCE_COBROWSE.visitorid is defined, a random key is generated.
startSession(startParams) starts a session according to the parameters specified in startParams.

startParams may contain any of the following properties:
  • Groupid: (Optional) ID of the 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 script tag.
  • sessionKey: (Optional) Session key. See startSession(sessionKey) for behavior when sessionKey is not specified.
  • name: Visitor name
  • email: Visitor email
  • Phone: Visitor phone number
  • Example:
    var startParams = { sessionKey : "ABCD", name : "Julie Smith", email : "", phone : "314-555-1212"};
setStartParams(startParams) sets the start parameters in advance for the next session. These 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.
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() enables or disables remote control.
(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.
(eventName, listener)
addEventListener(eventName, listener) adds a listener function to be called when the event specified by eventName occurs. See Visitor Side Events.
(eventName, listener)
removeEventListener(eventName, listener) removes the specified event listener function.
(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.
(msgName, msg)*
sendSessionMessage(msgName, msg)* sends a message with the name msgName and the payload msg to the agent.
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.
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.
crossDomain(crossDomainParams)* crossDomainParams: { url: [url to open when done],target: ["_self" \| "_blank"]}

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

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

"target" may be "_self" or "_blank", indicating whether the url should open in the same window or a new window.

crossDomain() 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 11.
continueSessionAt(params) Deprecated. 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.

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: params = {<br/>destination : [destination domain such as ""],destinationurl : [optional, a helper url to use instead of the one that is configured on the Cobrowse Settings page], oncomplete : [function to call when the session data has been passed to the new domain],iewarningsuppressed : [optional, set to true if the warning is suppressed for Internet Explorer - the destination page will auto-accept the "urlstartwarning" event]
viewPDF(params) viewPDF() opens a PDF file using the Glance Cobrowse PDF Viewer. When a web page opens a PDF using viewPDF(), the agent is able to view the PDF along with the visitor, as with any other cobrowseable web page.


params = { url : ["url to the pdf file"] }

This call does not accept relative links. To work around this limitation, you can build an absolute URL by combining window.location with the relative path:
var absurl = window.location.protocol + "//" + window.location.hostname + window.location.pathname + "/" + relativeurl
notifyChanged(params) notifyChanged() notifies the Glance Cobrowse script of changes <canvas> elements.

params = {<br/>canvas : {gcids : [gcid1, gcid2...] }<br/>}

The gcidsare the values of the "data-gcid" attribute on each changed canvas element.

Using notifyChanged()

The Glance Cobrowse visitor script is not notified by the browser 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.


A 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:

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

The portion in blue is an array of data-gcids. This example uses jQuery to select each canvas element and obtain the value of its "data-gcid" attribute.

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