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
.
Login key authentication call:
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, [params])
-
sessionKey: Session Key
-
params: other optional parameters
windowName: window name for new window, defaults to “_blank”
windowFeatures: features for window.open, defaults to 800x800 window with no title or menu bar
wait: boolean indicating whether the method should wait for a session to start, defaults to true.
agentVideo: boolean indicating if the agent had video turned on.
Lookup 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(key, [params])
-
key: Session key
-
params: other optional parameters, see joinSession
Change in 4.19: openViewer no longer takes a third webserver argument, set GLANCE.Agent.webserver instead.
Open the agent viewer in a window to join a session. This 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.
GLANCE.Agent.openAgentJoinURL(url, [params])
-
url: URL to join the session, typically returned from lookupSession
-
params: other optional parameters, see joinSession
-
windowName: window name for new window, defaults to "_blank"
windowFeatures: features for
window.open, defaults to 800x800 window with no title or menu bar.
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=true])
sessionKey: Session Key
wait: boolean indicating whether the method should wait for a session to start, defaults to true.
Looks up a session with the required session key parameter. Returns a Promise that resolves to an object. If the session is found there will be an 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. “videoStarted”
-
handler: function (eventname, eventdata) {}
GLANCE.Agent.addEventListenerAll(handler)
handler: function (eventname, eventdata) {}
Set an event handler that will be called for all events.
GLANCE.Agent.presenceConnect(sessionkey)
sessionkey: Session Key
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 datapresenceOnTerms
Event datapresenceError
Event errorpresenceVisibility
Event datapresenceFailed
{
"service": "Presence",
"reason": <error>
}
GLANCE.Agent.presenceStartSession(sessionkey, invokeparams, joinparams)
sessionkey: {string | number} invokeparams: {Object} joinparams: {Object}
This method returns a promise that resolves to GLANCE.Agent.joinSession
(see above) with the sessionkey and joinparams provided, or as a random integer if left undefined. The presenceAgent invokeVisitor function is called with the invokeParams argument or as default the GLANCE.Cobrowse.VisitorUI.showTerms
if left undefined. If invokeVisitor
fails, the promise is rejected and an event is fired:
presenceInvokeFailed
{
"service": "Presence",
"reason": <error>
}
GLANCE.Agent.presenceDisconnect(sessionkey)
Disconnect from Presence service
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>
}
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"
}
rc
{
"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.