Cobrowse Agent API

The Agent API allows you to customize agent side behavior and integrate Cobrowse with the agent's console or CRM.

Viewer URL

Use the following URL format to view a session that was started with a specific Visitor ID or a random Session Code:

https://www.glance.net/agentjoin/AgentView.aspx?VisitorId=[visitorid|ssncode]&wait=1

NOTE: `SessionKey` is a synonym for `VisitorId` in the parameter list. .

To maximize the viewing area, this URL should be opened in a separate browser window with no address bar or menu:

window.open(
   "https://www.glance.net/agentjoin/AgentView.aspx?VisitorId=" + visitorid,
   "_blank",
   "location=no,menubar=0,titlebar=0,status=0,toolbar=0");

If an agent is not already logged into their Glance account, they will be prompted to log in. Alternatively, single sign-on credentials can also be passed on the Agent Viewer URL:

SessionKey=ssnkey&partnerid=pid&partneruserid=puid&loginkey=loginkey

The optional query string parameter Wait controls handling of the case when the session has not started yet. If Wait=1 is specified, the viewer window will poll waiting for the session to start. Otherwise, the viewer will redirect to an error page if the session has not yet started.

Include the API

To include the Agent API on a page, add a Cobrowse script tag following the format of the script tag used on the visitor side, but add script=Agent (case sensitive) to the src attribute.

Agent side script tag example

<script
    id="glance-cobrowse"
    type="text/javascript"
    src="https://www.glancecdn.net/cobrowse/CobrowseJS.ashx?group=[groupid]&site=[production|staging]&script=Agent"
    data-groupid="[groupid]"
    data-site="[production|staging]"
    charset="UTF-8">
</script>

GLANCE.Cobrowse.Agent API

The GLANCE.Cobrowse.Agent object implements the Agent API. A typical use case for the Agent API is a page that embeds the Cobrowse viewer in an <iframe>.

Methods and Properties

When the enclosing page includes the Agent API JavaScript, the page has access to the following methods on the GLANCE.Cobrowse.Agent object:

Property/Method	Description
`init(viewerFrame)`	`init(viewerFrame)` initializes the Agent Side API viewerFrame. This is the iframe containing the agent view.
`enableAccessibility(enable)`	`enableAccessibility(enable)` enables or disables accessibility features. When accessibility features are enabled, any screen reader in use will read the element that an agent gestures on.
`accessibilityEnabled()`	`accessibilityEnabled()` returns true if accessibility features are enabled, false otherwise.
`addEventListener (eventName, handler)`	`addEventListener(eventName, handler)` adds an event handler to be called when the event specified by `eventName` occurs.
`removeEventListener (eventName, handler)`	`removeEventListener(eventName,handler)` removes the specified event handler.
`addSessionMessageListener (msgName, handler)`	`addSessionMessageListener(msgName, handler)` adds a session message handler. The handler function is called when a message with the name `msgName` is received from a visitor. The handler function takes two parameters: `msgName`: the message name. `msg`: the message payload object that was sent from the visitor side in sendSessionMessage.
`sendSessionMessage (msgName, msg)`	`sendSessionMessage(msgName, msg)` sends the `msg` to the visitor side. Note: `msg` must be an object. For Example: `GLANCE.Cobrowse.Agent.sendSessionMessage("hello", {"foo": 123})`
`navigate(options)`	`navigate()` redirects the visitor's browser to a specified `url`. See Using navigate.
`leaveSession (targetUrl)`	`leaveSession(targetUrl)` ends the agent’s connection to the session and redirects the Agent Viewer to the `targetUrl`.
`addScreenshare(options)`	`addScreenshare(options)` adds an already-started Screen Share session to the Cobrowse session. See Using addScreenshare.
`pauseScreeenshare(options)` `resumeScreenshare(options)`	Pause or resume the visitor side Screen Share. See Using pauseScreenshare and resumeScreenshare.
`closeScreenshare(options)`	The `options` object includes the following property: `{screenshareView}` The screen share view that was specified in `addScreenshare()`
`requestRC(true\|false)`	`requestRC(true)` sends a request to the visitor to enable remote control. The default visitor side UI prompts the visitor to allow or decline the request. `requestRC(false)` stops remote control.
`requestVisitorVideo(true)`	`requestVisitorVideo(true)` sends a request to the visitor to turn on small visitor video. Calling `requestVisitorVideo`causes a `visitorvideorequested` event to fire on the visitor side. The visitor may accept or decline the video session.
`getSessionState(eventname)`	`getSessionState()` retrieves information about the session as reported by the specified event. For example, `getSessionState("rc")` returns the event data reported in the most recent `rc` event.
`getUserState(name)`	`getUserState()` retrieves the user state that was stored on the session by a call to `GLANCE.Cobrowse.Visitor.setUserState()`
`toggleAgentVideo()`	Pauses or unpauses agent video
`updateVideoOptions(options)`	Updates the video session options

Using GLANCE.Cobrowse.Agent methods

Using navigate()

navigate(options) redirects the visitor's browser to a specified url. The options object includes these properties:

url: The url to navigate to. It may be:
- A relative URL. The Visitor is redirected to the specified URL relative to the current page.
- An absolute URL. The hostname must be in the list of trusted domains for Cross Domain Cobrowse specified on the Cobrowse Settings page.
- "forward" or "back". The Visitor's page navigates forward or backward.
- "refresh". The Visitor's page refreshes.
browser - Visitor’s browser type and version.
visitorversion - Cobrowse version used on the visitor side.
pagemasked - True if the page is masked, false otherwise.
confirm: (optional) If specified, the visitor side will fire a confirm event before navigating. The object passed to the confirm event handler will include the options passed to navigate(), as well as an accept() method to call if the visitor accepts.

If navigating to a page URL (as opposed to forward, back, or refresh) then either open or link should be specified. If open is specified, window.open() is used to open the specified page. If link is specified, then an anchor tag is added to the page and programmatically clicked.

Using addScreenshare()

addScreenshare(options) adds an already-started Screen Share session to the Cobrowse session. Once a Screen Share session has been added, it will automatically persist even if the visitor navigates to a new page.

The options object includes the following properties:

screenshareView: (string) The
ID of the iframe on the visitor side where the screen share viewer should appear. Use "glance_agentvideo" or "glance_screenshare" for agent video and screen share respectively, if using the standard visitor side user interface.
sessionKey: (string) The session key.
key: Synonym for sessionKey. In version 3.7.4, this parameter was renamed sessionKey.
ssnParams: The parameters that were passed to GLANCE.Client.InvokeGlance() used to start the session, or the query string parameters that were passed to the Glance protocol handler to start the session. ssnParams may be an empty object, but supplying the session parameters can assist in rendering the screen share view. For example, ssnParams for a video session may be as follows:
```
{type: "forward", video: 1, size: "240x320"}
```
agentparams: Parameters indicating agent side behavior.
preview: Set this to true to display the built-in video preview on the agent side. Set this to false to suppress the built-in agent preview. Defaults to false.

Using pauseScreenshare() and resumeScreenshare()

pauseScreeenshare(options) pauses the visitor-side Screen Share session, and resumeScreenshare(options) resumes it. These methods work by triggering a screensharepause or screenshareresume event on the visitor side.

The options object must include this property:

screenshareView: the screenshare view that was specified in the call to addScreenshare().

Typical usage would be to call these methods before invoking ActionPause or ActionUnpause on the Screen Share session using the Glance Client Library.

The default user interface behavior on the visitor side is to hide the Screen Share or video view while the session is paused.

Updated on 12 Oct 2022