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, [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 data
presenceOnTerms Event data
presenceError Event error
presenceVisibility Event data
presenceFailed

{
   "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"
}

{
    "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 02 Dec 2022