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 |
---|---|
email |
Visitor’s email address. Up to 127 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() |
name |
Visitor’s name. Up to 63 Unicode characters. |
phone |
Visitor’s phone number. Up to 31 Latin-1 (?ISO/IEC 8859-1) characters. |
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. |
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 |
addEventListener
?(eventName, listener) |
addEventListener(eventName, listener) adds a listener function to be called when the event specified by eventName occurs. See Visitor Side Events.
|
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.
|
continueSessionAt
?(params) |
Deprecated See Using continueSessionAt. |
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.
|
enableRC*
?([true|false]) |
enableRC() enables or disables remote control.
|
getCallId()* | Returns the Call ID (unique identifier) of the active session. This method would only be available when a session is running. |
getKey()* | getKey() returns the session key.
|
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 Note: the Glance Cobrowse session cookie is a cookie on your website domain. |
getSessionState
?(eventName [, identifier])* |
getSessionState() returns the information that was reported in the most recent state event specified by eventName .
For example,
For the |
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 |
inSession() | inSession() returns true if a session is active and false if not.
|
isMobileDevice | Returns true if the visitor is on mobile device, otherwise returns a false value. |
isPageMasked() | This function returns true if the page is masked. |
isSessionPaused()* | Returns true if the session is currently paused, otherwise returns a false value. |
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.
|
notifyChanged(params) | notifyChanged() notifies the Glance Cobrowse script of changes to <canvas> elements. See Using notifyChanged.
|
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
|
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:
|
removeEventListener
?(eventName, listener) |
removeEventListener(eventName, listener) removes the specified event listener function.
|
sendDocument(file) | sendDocument(file) allows visitors and agents the ability to download documents shared during Document Sharing.
|
sendSessionMessage
?(msgName, msg)* |
sendSessionMessage(msgName, msg) sends a message with the name msgName and the payload msg to the agent.
|
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:
|
startSession
?(sessionKey|options) |
startSession() starts a session. See Using startSession().
|
stopSession()* | stopSession() stops the Cobrowse session.
|
showTerms | showTerms shows the Terms and Conditions modal with Accept/Decline buttons. Clicking Accept starts the session.
Note: Deprecated: Use the |
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:
|
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 |
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:
See Excel Cobrowsing for more information. |
* 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.
-
startSession(key)
, wherekey
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 neithersessionKey
norGLANCE_COBROWSE.visitorid
is defined, a random key is generated. -
startSession(options)
starts a session using the parameters specified inoptions
.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 thedata-groupid
attribute of the cobrowse<script>
tag.sessionKey
(Optional) Session key. See above for behavior whensessionKey
is not specified.name
Visitor nameemail
Visitor emailphone
Visitor phone numbercontent
“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 statevideosource
device id of the camera to showpreviewelementid
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()
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 opentarget
Where to display theurl
. It may have the values"_self"
or"_blank"
, indicating whetherurl
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:
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 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.