Cobrowse Visitor Events

Visitor Events are the events included within the visitor side behavior of Cobrowse.

Session Lifecycle Events

To keep track of a session's lifecycle status, monitor these status events.

leavesession

leavesession is fired when a visitor ends the session.

sessionstarting

A session in the process of starting posts this sessionstarting event. It is followed by sessionstart, or by error if the session fails to start. It can take a few moments for a session to start.

sessionstart

sessionstart means the session has started.

sessioncontinue

sessioncontinue is fired when the session is first established (after sessionstart), and again every time the visitor navigates to a new page while in the session.

statereceived

A session posts statereceived after a visitor has navigated to a new page and the initial session state has been received from the session server.

While handling this event call GLANCE.Cobrowse.Visitor.getSessionState() to retrieve the state information.

sessionend

A session posts sessionend when it has ended. It passes an object describing the reason, e.g.:

{reason: 'agent' || 'visitor' || 'error'}

Abnormal-Condition Events

error

A session posts error when an error occurs. It passes this object describing the error

{
    "code": "[error code]",
    "msg": "[a description of the error]"
 } 

Possible error codes include these:

• "service": A connection could not be established to the cobrowse service
• "conndrop": The connection to the cobrowse service dropped and could not be re-established.
• "dupkey": A session is already running with the specified session key or visitor id, and the group is configured to prevent duplicate keys.
• "maskingerror": fires if there is an error determining masked fields.
• "SCRIPT_NOT_LOADED": fires when a script fails to load. The name of the failed script is passed under params.script.

connection

The connection event means the status of the connection to the Glance Cobrowse Service has changed. The UI may display a connectivity warning if the status is "reconnecting", and clear the warning if the status is "ok". A connection event with "reconnecting" status will be followed by either another connection event with the status "ok", or an error event with the "conndrop" code. connection includes an object identifying the status.

{status : ["ok" | "reconnecting"] }

Session Information Events

addguestaccepted

addguestaccepted is fired when a visitor has accepted a request to add a guest to the session.

addguestdeclined

addguestdeclined is fired when a visitor has declined a request to add a guest to the session.

addguestrequested

addguestrequested is fired when an agent has requested to add a guest to the session.

accessibility

The accessibility event means accessibility features (such as screen -reader support) are turned on or off. It includes an object showing the accessibility-feature state.

{enabled :[true | false]}

agents

The agents event means updated session participant information is available. This event occurs when a page first loads, and again whenever an agent or guest joins the session. It includes an object containing an array of information about the agents/guests viewing the session, for example:

{
   "count": 3,
   "agentlist": [
       {
           "username": "abc.glance.net",
           "partnerid": 12345,
           "partneruserid": "abc@company.com",
           "name": "Janet Wills",
           "title": "Senior Representative",
           "role": "agent",
           "guestid": 1162611,
           "num": 1,
           "agentrole": "Account Support" //available in Cobrowse 5.2 or later.
       },
       {
           "username": "def.glance.net",
           "partnerid": 12345,
           "partneruserid": "def@company.com",
           "name": "Mary Supervisor",
           "title": "Supervisor",
           "role": "agent",
           "guestid": 1217257,
           "num": 2,
           "agentrole": "Supervisor"//available in Cobrowse 5.2 or later.
       },
       {
           "role": "guest",
           "name": "Betty Rubble",
           "guestid": 1164652162,
           "num": 3
       }
   ]
}

• Most sessions have just one agent, but it is possible to have multiple agents participating.
• "role" allows you differentiate between additional agents versus non-authenticated guests that are admitted to the session.
• "title” in the agent information comes from the Public Title, which currently can be set only by Glance. If a Public Name is specified for the agent, that name will be sent in agentlist instead of the agent’s profile name.

Note: Agent name, title, partneruserid, Glance Address are not included in the agentlist by default, but can be included if enabled by Glance Support. This capability is available only in Cobrowse version 4.10.1 or later. Allowing additional "guests" to join sessions is only available in Cobrowse 5.0 or later.

blur

A session posts blur when the visitor clicks on or opens another browser tab or window pointing to the same website. The newly activated window takes session focus and blur occurs in the original window.

focus

A session posts focus when the visitor clicks on the window, making it the active session window.

sessionpaused

A session posts sessionpaused when the session is paused or unpaused. It includes an object describing the current state of the session:

{ paused: [true|false] }

navigation

navigation is fired when the agent navigates the visitor to a new page or back/forward.

outline

outline is fired when an agent gestures on the screen.

Document Sharing Events

agentdocshare

agentdocshare is fired when an Agent shares a document.

documentviewed

The documentviewed event occurs any time the document viewer is launched. The event object includes some information about the file being shared, as well as who is doing the sharing.

For files that are shared by the visitor from their local computer:

{
    "name": "example_file.xlsx",
    "visitorselected": true,
}

For files that are hosted on the customer website and opened by the visitor clicking on a link to a PDF or CSV:

{
   "url": "https://www.<customerdomain>.com/example.pdf"
}

For files that are shared by the agent:

{
    "name": "example_file.xlsx",
    "agentselected": true,
}

docsharestatus

docsharestatus fires when visitor document sharing has been accepted, declined, or started.

{ status: "accepted" | "declined" | "started" }

docsharerequested

docsharerequested fires when an agent requests a document share.

visitordownload

The visitordownload event occurs when the visitor downloads a file shared by the agent. The event object includes:

{
    "name": "example_file.xlsx",
    "agentselected": true,
}

agentdownload

The agentdownload event occurs when the agent downloads a file shared by the visitor. The event object includes:

{
    "name": "example_file.xlsx",
}

Remote Control Events

rcaccepted

rcaccepted fires when a visitor accepts a request to add remote control.

rcdeclined

rcdeclined fires when a visitor declines a request to add remote control.

rcrequested

The rcrequested event means an agent is requesting remote control of the visitor's browser. It includes this object containing two callback functions.

   {accept : [callback function],
    decline: [callback function] }

To handle this event, call either accept() or decline() once you determine whether the visitor will grant remote control permission.

rcenabled

The rcenabled event means remote control has started or ended.
When remote control is active, this rcenabled event also occurs whenever the visitor navigates to a new page. It includes an object showing the remote-control state.

{enabled :[true | false]}

rcevent

Occurs each time the agent performs an action in the visitor's browser. The event object includes:

{
    "type": "<click|agenttyping|inputchange>",
    "agent": {
        "username": "user.glance.net",
        "puid": "user@company.com",
        "num": 1
    },
    "path": "[data-gid=\"167\"]",
    "value": "something"
}

• Type
  • click - The agent has clicked an element.
  • agenttyping - The agent is typing. Will fire after each keystroke. See notes on Value below.
  • inputchange - Occurs when the input loses focus after editing. This will only fire if the agent has edited the field.
• Agent
  • username and puid - The agent's username and puid as provisioned in Glance.
  • num - The order in which the agent joined the session
• Path
  • During a Cobrowse session, each element in the DOM is assigned a unique data-gid integer value. This value can be used to identify the specific element being interacted with, for example by calling document.querySelector(path). For an input field, you can see the new value by calling document.querySelector(path).value.
• Value
  • Will be undefined when the type is click or inputchange.
  • When the type is agenttyping the value passed in the event will be equal to the entire value of the input field after each agent keystroke. For example, if the value of an input is abc and the agent types d, then the value of the event will be abcd.

Reverse Session Events

Agents can request reverse sessions from within existing sessions.

reverseconfirm

The reverseconfirm event means an agent is asking the visitor to join a reverse session. It includes this object containing two callback functions.

     {accept : [callback function],
      decline: [callback function] }

To handle this event, call either accept() or decline() once you determine whether the visitor wishes to join the reverse session.

reverseended

The reverseended event means the agent has ended a reverse session. The reverse session will automatically end for the visitor. If a reverse session confirmation dialog is still waiting for a visitor response, hide it when getting reverseended.

Screenshare Session Events

pausevisitorscreenshare

pausevisitorscreenshare fires when the agent stops the visitor's screenshare.

screenshare

The screenshare event means a screenshare session has started or ended. It includes this object.

{     
    "screenshareView": "glance_video_1",
    "agentnum": 1,
    "state": "new",
    "paused": false,
    "params": {
        "type": "forward"
    }
}

screenshareViewis the id of the iframe that displays the view of the screenshare. It will have a value like "glance_screenshare","glance_agentvideo", or "glance_agentvideo_1" if using a standard Glance Cobrowse agent viewer. If using a custom agent viewer, screenshareView may be a custom name. This may vary in future releases.

agentnum is the sequential number of the agent, visitor, or guest who is sharing the screen or video.

type may be "reverse" instead of "forward" in an escalate to view.

This event occurs as follows:

• When a screen share session first starts (state==="new").
• After every page load—as long as the session is in progress (state==="continued").
• When a screen share session ends (state==="ended").

Handle this message by positioning, sizing and displaying the iframe identified by screenshareView.

screensharepaused

The screensharepaused event means the agent has paused a screen share session. It is typically handled by hiding the corresponding screenshare viewer, or by replacing it with a static image. It includes an object identifying the screen share session.

{ screenshareView:[viewname] }

screenshareresumed

The screenshareresumed event means the agent has resumed a paused screen share session. It includes an object identifying the screen share session.

{ screenshareView:[viewname] }

viewerinfo

The viewerinfo means screenshare viewer information is available. It occurs after a Screen Share session is first started, and whenever the display side monitor or resolution changes. For sessions running in video mode, this event also occurs periodically to report statistics such as viewer frame rate.

{ screenshareView:[viewname],
  screen : { width: [w],height : [h]},
  scaledview: { width: [w], height : [h]},
  glance_viewer: {
    stats: {fpslimit: [n], viewerfps: [n], displayfps: [n]}
  }
 }

screenshareView identifies the screen share session to which the information applies. All other properties are provided if they have changed since the last viewerinfo event.

This event is typically handled by adjusting the dimensions of the screen share viewer according to the display resolution.

visitorscreenshareaccepted

visitorscreenshareaccepted fires when a visitor accepts the screen share request.

visitorscreensharedeclined

visitorscreensharedeclined fires when a visitor declines the screen share request.

visitorscreenshareended

visitorscreenshareended fires when a visitor stops sharing their screen.

visitorscreensharepaused

visitorscreensharepaused fires when the visitor pauses their screen share.

visitorscreensharerequested

visitorscreensharerequested fires when an Agent requests the visitor to screen share.

visitorscreensharestarted

visitorscreensharestarted fires when the visitor starts sharing their screen.

Legacy Event

urlstartwarning

This deprecated urlstartwarning event means parameters have been passed onto the page URL signaling that a session should continue on a new domain. This event, used for cross domain cobrowse, provides legacy support for old Microsoft Internet Explorer.

      {accept : [callback function],
       decline: [callback function] }

Visitor Video Events

participantvideopaused

participantvideopaused fires when an agent pauses a participant's video.

visitorvideo

Occurs when

• a visitor video session first starts
• when the video session resumes after navigation
• when an inactive browser tab regains focus

Note that even if the visitor's camera is unavailable, visitorvideo still fires to indicate that the video session has started in an error state.

Object Passed to Event Handler

{ video : "large" | "small", camerastatus : "blocked" | "nocamera" | "available" | "error" }

visitorvideoaccepted

visitorvideoaccepted fires when a visitor agrees to add video to an existing Cobrowse session. { camerastatus: <camerastatus>,video: <small/large>,videobgfilter: <true/false>,videobgtype: <blur/fill/image>,videopaused: <true/false>,videosource: <camera_name> }

visitorvideocreated

visitorvideocreated fires when a visitor video session is created.

visitorvideodeclined

visitorvideodeclined fires when a visitor declines to add video to an existing Cobrowse session.

visitorvideoended

visitorvideoended fires when a visitor video session ends.

visitorvideorequested

Occurs when the agent has requested that the visitor initiate a video session. To accept the request, call the accept callback and the visitor's video session will start. Typically visitorvideorequested is handled by presenting a preview dialog with the ability to select a camera and pause video.

To control how the visitor's video will start, pass VideoParams (see the documentation for GLANCE.Cobrowse.Visitor.startSession) to the accept callback.

Object Passed to Event Handler

{ accept : [callback fn], decline: [callback fn] }

visitorvideoresize

visitorvideoresize fires when a video was resized.

visitorvideostarted

Occurs when the visitor video session first starts.

Object Passed to Event Handler

{ width : [video resolution width], height : [video resolution height]}

visitorvideostopped

Occurs when the visitor video session ends.

visitorvideopaused

Occurs when the visitor video session has completed the "pause" process after a call to toggleVideo(). After the visitorvideopaused event, a subsequent call to toggleVideo() will unpause the video. visitorvideopaused also occurs on page navigation immediately after visitorvideo if the video session is in a paused state.

visitorvideoresumed

Occurs when the visitor video session has completed the "unpause" process after a call to toggleVideo(). After the visitorvideoresume event, a subsequent call to toggleVideo() will pause the video.

visitorvideoerror

Object Passed to Event Handler

{ error : [errorcode] }

viewerclosing

Occurs when participants in a multiway video session are unable to play videos due to their browser/network.

{ closereason: "PlayerTooSlow"}

waitingforcamera

Occurs after five seconds if the camera doesn't respond, most often due to a camera permission prompt that the user has not responded to.

Invoking The Visitor API From Another Window

In some cases, it is useful to control the Cobrowse session from a window other than the one the visitor is browsing the instrumented website from. A chat window is a typical example.

To support this functionality, the visitor window listens for glance_invoke messages posted from the chat window. The window message handler will only accept glance_invoke messages if the domain of the origin is in the list of trusted domains as configured in the Cobrowse settings for the account.

Parameters

GLANCE.Cobrowse.InvokeVisitor

To invoke a GLANCE.Cobrowse.Visitor function from a chat window using GLANCE.Cobrowse.InvokeVisitor, add the GlanceCobrowseInvokeVisitor.js to the chat window page.

Methods

The following methods are available on Glance.Cobrowse.InvokeVisitor:

Example

GLANCE.Cobrowse.InvokeVisitor.init(wnd, 12345, "*");
GLANCE.Cobrowse.InvokeVisitor.invoke("startSession", { sessionKey : "9999" });
GLANCE.Cobrowse.InvokeVisitor.invoke("stopSession");

Invoking Visitor API Using postMessage

To invoke a GLANCE.Cobrowse.Visitor function from another window using postMessage, post a message to the visitor window in the form:

glance_invoke : { func : [method of GLANCE.Cobrowse.Visitor], args : [args object], groupid : [goupid]}

The groupid must match the groupid on the visitor side.

Example:

wnd.postMessage({ glance_invoke: { func: "showTerms", args: { sessionKey: "12121212" }, groupid: "72937"} }, "*")

Screenshare and Agent Video in a Custom Visitor UI

When using the default visitor user interface, both Glance Screen Share and Agent Video are automatically displayed in the visitor browser. When using a custom visitor user interface, implement a listener for the screenshare event.

When an agent chooses to share their screen or webcam video, a screenshare event fires. See Visitor Side Events for a description of the Screen Share event. Glance uses the standard screenshareView names: glance_screenshare and glance_agentvideo for Screen Share and Agent Video sessions respectively.

To support Screen Share and Agent Video with a custom user interface, add hidden iframes and with id="glance_screenshare" and id="glance_agentvideo" to the visitor's page, and unhide the corresponding iframes when a screenshare event fires.

The glance_agentvideo and glance_screenshare iFrames must exist in the page before the agent initiates Agent Video or Screen Share. In addition, if the visitor navigates after Agent Video has already been turned on, the iframe must exist in the page before the visitor connects to the Cobrowse server. It is not possible to wait to create the iframe until the "screenshare" event fires.