Browser Agent API Reference

GLANCE.Agent.webserver

The default value is https://www.glance.net. This should only be set if a different service address is being used.

GLANCE.Agent.authenticate(credentials)

Authentication is required for joinSession or lookupSession, optional for openViewer and not used in openAgentJoinURL.

GLANCE.Agent.authenticate({
			loginkey: "<loginkey>",
			partnerid: <partnerId>,
			partneruserid: "<partnerUserId>"
		});

See Login Key Authentication for information on these parameters.

SAML authentication calls includes the following:

GLANCE.Agent.authenticate({idpid: <id>});

GLANCE.Agent.authenticate({idptoken: <token>});

GLANCE.Agent.authenticate({idpusername: <username>});

GLANCE.Agent.joinSession(sessionkey[, joinparams])

sessionKey: The key for the session the agent is attempting to join.
joinparams: Other optional parameters. Examples below:

const joinparams = {
  windowName: "Name of the window", // Window name for new window, defaults to “_blank”
  windowFeatures: "width=1000,height=1000", // Features for window.open, defaults to 800x800 window with no title or menu bar
  wait: true, // Boolean indicating whether the method should wait for a session to start, defaults to true
  agentVideo: "true", // Boolean. If true, the video will engage automatically as soon as the agent joins the session
  name: "Agnes Agent", // Stored on the agent's call viewer record
  email: "agnes@example.com", // Stored on the agent's call viewer record
  phone: "+17813162596", // Stored on the agent's call viewer record
};

GLANCE.Agent.joinSession("5012", joinparams);
//Joins a session with session key "5012" and the parameters listed above

This method will look up and join a Glance session, opening a new viewer window. This function returns a JavaScript Promise. When the viewer window is opened the Promise will "resolve" with a value that can be used to close the window with the .close() method. This is currently the actual Window object but that may change in future releases. If opening the window is blocked by the browser popup blocker, the event "popupblocked" is fired.

joinSession calls GLANCE.Agent.lookupSession passing true for the wait parameter. On lookupFound, this method calls openAgentJoinURL with the returned url. Various events are fired during the process.

GLANCE.Agent.openViewer(sessionkey[, joinparams])

sessionKey: The key for the session the agent is attempting to join.
joinparams: Other optional parameters. See joinSession.

This method will open the agent viewer in a window to join a session. The function returns a JavaScript Promise like joinSession.

If authenticate has been called with credentials they will be used in openViewer. Otherwise the agent will be prompted to login if they are not already.

NOTE: If you are using openViewer with an iframe id set (or using the joinSession method with iframe id set), make sure that your iframe implementation has the following attribute set: allow="camera *; microphone *"

GLANCE.Agent.openAgentJoinURL(agentjoinurl[, joinparams])

agentjoinurl: URL to join the session, typically returned from lookupSession.
joinparams: Other optional parameters. See joinSession.

This method will open the agent viewer URL in a window to join a session. This function returns a Javascript Promise like joinSession.

This is intended to be passed the agentjoinurl returned from lookupSession or equivalent.

GLANCE.Agent.lookupSession(sessionkey[, wait])

sessionKey: The key for the session the agent is attempting to join.
wait: Optional boolean indicating whether the method should wait for a session to start. Defaults to true.

GLANCE.Agent.lookupSession("1234",false)
// Attempts to look up session with key "1234".  Will not wait.

This method looks up a session with the required session key parameter. Returns a Promise that resolves to an object. If the session is found, the Promise will resolve to an object that has the same properties as the lookupFound event, which also fires. Note the agentjoinurl property. Various errors, a timeout, or a canceled lookup will reject the Promise. A lookupFailed event will be fired for errors and timeouts.

If wait is false only one attempt is made to lookup. If the lookup request succeeds but the session is not found the Promise resolves to {}.

If wait is true (or omitted), the method repeatedly tries looking up the session for 45 seconds. Every time a new lookup is performed, a lookupWaiting event is fired. If the lookup times out a lookupFailed event is fired with a reason property of "timedout".

The lookupWaiting event has data like {service: "agent", ssnkey: "1234", cancel: ƒ}

The property cancel is a function to call to cancel the lookup. This can be used if more than one lookup is in progress (not a typical use-case).

GLANCE.Agent.cancelLookup()

Stops the most recent lookup in progress, firing a lookupCanceled event.

GLANCE.Agent.addEventListener(eventName, handler)

eventName: name of the event e.g., “sessionEnded”. See below for the list of events.
handler: The function to be called.

This method will set an event handler for the specified event. Where applicable, the handler is called with an eventdata parameter.

GLANCE.Agent.addEventListener("sessionEnded", function (eventdata) {
	// Perform your actions.
})

GLANCE.Agent.addEventListenerAll(handler)

handler: The function to be called

This method will set an event handler for all events. The handler is called with two parameters: eventname and eventdata. For certain events, eventdata may be an empty object.

GLANCE.Agent.addEventListenerAll(function (eventname, eventdata) {
	// Perform your actions.
})

GLANCE.Agent.presenceConnect(visitorid)

visitorid: The id of the visitor to look up.

This method returns a promise which creates a new GLANCE.Presence.Agent internally and sets up events for the Presence Agent.

When presenceConnect is called, it calls GLANCE.Authorization.authorize. If glanceCredentials are not set prior to making this call, the promise is rejected and a presenceFailed event is fired. If the call succeeds, new events are created for:

presence Event data
presenceOnTerms Event data
presenceError Event error
presenceVisibility Event data
presenceFailed

{
   "service": "Presence",
   "reason": <error>
}

GLANCE.Agent.presenceStartSession(visitorid[, invokeparams, joinparams])

visitorid: The id of the visitor. Used as the sessionkey by default.
invokeparams: Invokes a visitor side JavaScript function.
joinparams: Optional parameters passed to joinSession. See above.

This method returns a promise that resolves to GLANCE.Agent.joinSession(see above) with the visitorid as the sessionkey (or as a random integer if left undefined) and joinparams provided. It must be called after presenceConnect for the given visitorid.

The presenceAgent invokeVisitor function is called with the invokeparams argument or as default the GLANCE.Cobrowse.VisitorUI.showTerms if left undefined.

const invokeparams = {
  func: "GLANCE.Cobrowse.VisitorUI.showTerms", // The function that will be invoked on the visitor side.
  args: {
    groupid: "20541", // The group that the session will start in.  The value passed here must match one of the group ids included in the script tag on the visitor side.
    video: "off", // The state of video when the session starts on the visitor side.  Other options are "large" and "small".  Overrides the group default and script tag setting.  
  },
};

If invokeVisitor fails, the promise is rejected and an event is fired:

presenceInvokeFailed

{
   "service": "Presence",
   "reason": <error>
}

GLANCE.Agent.presenceDisconnect()

Disconnect from Presence service

Glance.Agent.inSession(sessionkey)

This method returns a promise. sessionkey is a required parameter.

If the session key matches an active session that the agent is currently participating in, the promise resolves to a boolean true. Otherwise, resolves to false.

NOTE: Calling insession() without parameters is possible but is not supported. Currently, this will return an array of sessions that the agent is participating in, but this functionality should not be relied on and will be separated into a different method in a future release.

Glance.Agent.Screenshare.disableUrlValidation()

This method disables URL validation for the session.

Must be called from the Agent Viewer window and before a screen share session is started.
Returns True if OCR URL validation has been successfully disabled.
Returns False if there is an error.

Glance.Agent.getUrlValidationEnabled()

This method indicates if URL validation has been enabled for the agent in the session.

Must be called from the Agent Viewer window.
Returns True if URL validation has been enabled and false otherwise.

Glance.Agent.Screenshare.getAllowedUrls()

This method retrieves the list of allowed domains for this agent.

Must be called from the Agent Viewer window.
Returns a string array of the allowed URLs for this agent or null if there is an error.

Agent Events

These are events generated by the Browser Agent API itself. There are a set of named events for each service. The event data will have an attribute "service" that will be one of "agent", "screenshare", "cobrowse", or "video". Other attribute values may change in future releases.

lookupWaiting

The lookupWaiting event occurs during a lookupSession function when event data is being looked up in the database.

{
   "service": "agent",
   "ssnkey": <The session key>,
   "cancel": <The cancel function>
}

lookupFailed

The lookupFailed event occurs during a lookupSession function when an error occurs. Fail scenarios include:

The API returned an error
An exception occured in the client code
The lookup exceeded the retry number (The lookup searches immediately, then retries every 3 seconds for the first 15 seconds, then every 5 seconds for the next 30 seconds)

{
   "service": "agent",
   "ssnkey": <The session key>,
   "reason": <The exception or error that occured>
}

lookupCancelled

The lookupCancelled event occurs during a lookupSession function when a lookup event was cancelled.

{
  "service": "agent",
  "ssnkey": <The session key>
}

lookupFound

The lookupFound event occurs during a lookupSession function when a lookup event was successful.

{
   "service": "agent",
   "id": <The ID of the event>,
   "ssnid": <The session ID>,
   "serverip": <The server IP>,
   "servername": <The server name>,
   "personid": <The person ID>,
   "groupid": <The group ID>,
   "passcode": <Passcode>,
   "agentjoinurl": <Agent join page URL>,
   "clientjoinurl": <Client join page URL>,
   "visitorversion": <Visitor's version number>
   }

iframeblocked

The iframeblocked event occurs when an iframe is blocked on the agent's side.

{
  "service": "agent"
}

popupblocked

The popupblocked event occurs when a pop up has been blocked (i.e., The Agent Join modal).

{
  "service": "agent"
}

viewerOpened

The viewerOpened event occurs when the agent viewer window has opened.

{
  "service": "agent"
  "close": <The close function>
}

viewerClosed

The viewerClosed event occurs when the agent viewer window has closed.

{
  "service": "agent"
}

approvedSite

The approvedSite event occurs when an agent visits an approved site in a Web Screen Share session with OCR restrictions.

{
    "textRead": <text read by OCR>,
    "ruleMatch": <rule matched in allowed list>,
    "timeRead": <time url was read; dd/mm/yyyy hh:mm:ss AM/PM>
}

unapprovedSite

The unapprovedSite event occurs when an agent visits an unapproved site in a Web Screen Share session with OCR restrictions.

{
    "textRead": <text read by OCR>,
    "timeRead": <time url was read; dd/mm/yyyy hh:mm:ss AM/PM>
}

visitorConnected

The visitorConnected event occurs when the visitor connects or disconnects from the presence service. This information can be used to display a status indicator to the agent (e.g.,Turning the JOIN button in a CRM from blue to orange).

{
    "connected": true || false
}

Cobrowse Events

Includes the events documented in the Cobrowse Agent API. For consistency with other services sessionend has been renamed to sessionEnded.

connecting

{
    "groupid": "72",
    "visitorid": "00000",
    "ssnkey": "00000",
    "service": "cobrowse"
}

navigate

{
    "browser": {
        "name": "chrome",
        "platform": "win",
        "version": 80
    },
    "visitorversion": "4.9.2.0",
    "url": "https://ew10.myglance.org/test/CobrowseTest2.htm",
    "service": "cobrowse"
}

agents

{
    "count": 1,
    "agentlist": [],
    "service": "cobrowse"
}

{
    "enabled": false,
    "suspended": true,
    "service": "cobrowse"
}

sessionEnded

{
    "reason": "AgentLeft",
    "service": "cobrowse"
}

lookupFailed

{
    "reason": "timedout",
    "service": "cobrowse"
}

Screenshare Events

connecting

{
    "calltype": "G",
    "ssnkey": "4400",
    "ssnid": "20541.4400.846930886",
    "agentconnect": true,
    "server": "",
    "maincid": 88071823,
    "displayprotocolversion": 1019,
    "callflags": 2195648,
    "visitorversion": "4.17.1.18+GCD+OS%3d%22Mac+OS+X+10.16+(20D91)%22",
    "agentusername": "joe.demo.glance.net",
    "agentinfo": {
        "username": "joe.demo.glance.net",
        "partnerid": 20541,
        "partneruserid": "Demo",
        "name": "Joe Demo",
        "title": ""
    },
    "videoserver": "video.glance.net",
    "agentvideo": 0,
    "service": "screenshare"
}

The agent viewer page is connecting to the screenshare session. The event data has various parameters, the most interesting is probably"visitorversion"which contains the Glance version number on the visitor side, plus OS type and version. Also contains "agentusername", the Glance Address of the agent.

connected {}

The screenshare viewer has connected.

screen

{
    "display": {
        "width": 375,
        "height": 812
    },
    "view": {
        "width": 211,
        "height": 458
    }
}

Sent on session start and whenever display size changes.

stats

{
    "bytespersec": 5221.8,
    "framespersec": 0.4
}

Statistics on screenshare bandwidth and frame rate (values can be null)

conndrop

sessionEnded

{
    "iserror": true,
    "status": 28
}

Screenshare session has ended. "status" values:

FAIL_VERSION 17 // protocol version mismatch

FAIL_UNAUTHORIZED 18 // bad server key or insufficient privileges

FAIL_NO_SESSION 19 // session no longer running

FAIL_REJECT_ENCRYPT 20 // reject encrypt error from server

FAIL_UNKNOWN 21 // unknown error

SESSION_ENDED 23 // session ended from agent side

SESSION_ENDED_QUIT 24 // session ended from other side

SESSION_ENDED_TIMEOUT 25

SESSION_ENDED_KILLED 26

SESSION_ENDED_CONN_DEAD 27

SESSION_ENDED_CALL_DEAD 28

SESSION_ENDED_ERROR 29

SESSION_ENDED_UNKNOWN 30

SESSION_ENDED_DECLINED 31

CANT_CONNECT 32

CANT_RECONNECT 34

SESSION_FULL 35 // max guests in session already reached

SESSION_ENDED_REPLACED 36

Video Events

initialized

{
  "service": "video"
}

previewStarted

Used with cobrowse sessions, not used within screenshare sessions

previewEnded

Used with cobrowse sessions, not used within screenshare sessions

videoStarted

{
    "options": {
        "sessionkey": "1498V231480",
        "bgBlur": true,
        "maincallid": "86490035",
        "vserver": "https://video.glance.net/",
        "width": 352,
        "height": 288,
        "framerate": 15,
        "bandwidth": "250kbps",
        "mime": null,
        "modelID": "browser",
        "deviceName": null,
        "maincid": null,
        "stopPreviewsOnSessionEnd": true,
        "groupid": null,
        "partnerid": null,
        "username": null,
        "isAnonymous": null,
        "password": null,
        "videoBackEnabled": false,
        "bitspersecond": 250000,
        "requestedbitspersecond": 250000,
        "device": "LG UltraFine Display Camera",
        "sourceDevice": "LG UltraFine Display Camera (043e:9a4d)"
    },
    "service": "video"
}

videoEnded

{
  "service": "video"
}

visitorvideo

visitorvideo fires when the visitor's video state changes, either by pause/unpause or by resizing small/large.

{
      "video":"small"
      "paused":false
      "service":"cobrowse"
  }

guestCountChanged

{
    "count": 1,
    "service": "video"
}

This event with "count":1 means the visitor side has connected to the video session. 0 means the visitor has disconnected.

error

{
    "message": "initialize failure",
    "options": {
        "sessionkey": "1234V823366",
        "maincallid": "13685174",
        "vserver": "https://video.myglance.org/",
        "width": 176,
        "height": 144,
        "framerate": 15,
        "bandwidth": "250kbps",
        "mime": null,
        "modelID": "browser",
        "deviceName": null,
        "maincid": null,
        "stopPreviewsOnSessionEnd": true,
        "groupid": null,
        "partnerid": null,
        "username": null,
        "isAnonymous": null,
        "password": null,
        "bitspersecond": 250000,
        "requestedbitspersecond": 250000,
        "device": "cam1",
        "sourceDevice": "Logitech HD Webcam C615 (046d:082c)"
    },
    "service": "video"
}

notEnabled

{
    "reason": "AgentVideo script not loaded (unsupported browser or visitor script version?)",
    "service": "video"
}

info

{
    message,
    options: {
        bandwidth: "1500kbps",
        bgBlur: true,
        bitspersecond: 1500000,
        device: "Logitech HD Webcam C615",
        deviceName: undefined,
        framerate: "15",
        groupid: null,
        height: 288,
        isAnonymous: false,
        maincallid: null,
        maincid: null,
        mime: "video/webm; codecs="
        avc1 .42E01 E "",
        modelID: "browser",
        partnerid: null,
        password: null,
        requestedbitspersecond: 1500000,
        sessionkey: "tjtaAg",
        sourceDevice: "Logitech HD Webcam C615 (046d:082c)",
        stopPreviewsOnSessionEnd: false,
        username: null,
        videoBackEnabled: falsev,
        server: "https://myvideo.myglance.org:3000/",
        width: 352
    }

These are informational messages from either the client itself or from the Video Server.

Among these sent by the client are:

'Background Blurring requires a more powerful version of WebGL than is supported by your browser.' Notice that though background blurring has been requested, it has been disabled because though the client browser supports WebGL, it is not a powerful enough implementation to support Agent detection and background blurring.
'Background Blurring requires WebGL which is not supported by your browser.' Notice that though background blurring has been requested, it has been disabled because the client browser does not support WebGL which is required for background blurring.

Updated on 04 Aug 2023