Presence Agent API

Including the Presence Agent API

To include the Presence Agent API in a web page, add the following HTML, substituting your group id for "12345".

<meta id="glance-cobrowse" data-groupid="12345" />
<script src="https://ww2.glancecdn.net/cobrowse/CobrowseJS.ashx?groupid=12345&script=PresenceAgent" ></script>

If you are including the presence script bundled in a component or self-hosted, you must add a meta tag to specify the group id: <meta id="glance-cobrowse" data-groupid="groupidhere"></meta>

The Presence Agent API can only be used from a trusted domain.

NOTE: Contact Glance to ensure that your website domain is configured as an allowed agent origin on our Presence Service.

Authorization

The Presence Agent API requires an Authorization Token which can be obtained from the Glance Authorization Service web service. Authorization should be performed once to obtain a token which can be used for a set duration.

Please refer to the Glance Authorization API for information on obtaining and using an Authorization Token.

The Glance Presence Agent API is defined in the namespace GLANCE.Presence.Agent.

GLANCE.Presence.Agent(params) – constructor

Constructs a Presence agent object. A separate agent object must be instantiated for each visitor that the agent needs to communicate with.

Either a visitorid or a uniqueid must be specified in the params object to identify the visitor connection.

Parameters

{
  "presenceserver": [Presence Service, defaults to "presence.glance.net"],
  "visitorid":"" //specify visitor id for a visitor connected with GLANCE.Presence.Visitor.connect()
  "uniqueid":"" // specify unique id for a visitor connected with GLANCE.Presence.Visitor.connectUnique()
}

GLANCE.Presence.Agent.prototype.lookupVisitor(params)

{
  "onsuccess" : [called back with visitor presence info if lookup succeeds],
  "onfail" : [function(errorcode) {} called back if lookup fails]
}

GLANCE.Presence.Agent.prototype.signalVisitor(params)

Sends a signal (message) to a visitor who has been connected within the last 5 seconds to the service. If the visitor has an open connection to the service, the visitor will be signaled immediately. Otherwise, the visitor will be signaled on next connect, if within 5 seconds.

The on success callback is called when the signal is confirmed that it was received by the Presence service.

Parameters

{
  "data" : [message to send to visitor],
  "onsuccess" : [function to be called back on success],
  "onfail" : [function to be called back on failure]
}

The visitor receives the signal via the onsignal event

GLANCE.Presence.Agent.prototype.invokeVisitor(params)

Invokes a visitor side JavaScript function in the GLANCE namespace. Visitor side must have been connected at some point within the last 5 seconds.

The onsuccess callback is called when the invoke message is confirmed that it was received by the Presence service.

Parameters

{
  "func" : [name of function to invoke, must be in the GLANCE namespace],
  "args" : [object to pass to the function ],
  "onsuccess" : [function to be called back on success],
  "onfail" : [function to be called back on failure]
}

GLANCE.Presence.Agent.query(params)

Queries Presence data // not implemented yet

GLANCE.Presence.Agent.prototype.connect(params)

Connect to the Presence server to receive notification of events related to the visitor. connect() opens a WebSocket connection to the Presence service.

Before calling connect(), set event handlers as properties of the Agent object.

GLANCE.Presence.Agent.prototype.disconnect()

Disconnect the Presence Agent from the presence service.

Agent Events

Events which may fire on the agent side are:

Event	Data Passed
onvisitorconn	{ "connected" : [true\|false] } Fires when a visitor connects or disconnects from the presence service. Note that for a visitor browsing a website, the actual websocket connection will disconnect and reconnect as the visitor navigates from page to page. The visitor is still considered connected to presence during navigation, so no "visitorconn" event fires.
onvisitorsock	{ "connected" : [true\|false] } Fires when the visitor's actual socket or websocket connection to the presence server is established or closed.
onpresence	{ the presence data just sent by the visitor }
onerror	{ "error" : [error code], "detail" : [error detail] } Error codes: connfail – Failed to establish or maintain the websocket connection. In the event of a connection failure, a "detail" property will include a detailed reason: authorization – Authorization token missing, bad, or expired connection – Network connection dropped error – Server returned an error
onterms	{ status : ["displayed"\|"accepted"\|"declined"] } The terms event fires when the terms and conditions dialog is displayed, accepted, or declined by the visitor.
onvisitorsessionstart, onvisitorsessionend, onvisitorerror	These events fire when the corresponding events sessionstart, sessionend, and error fire on the visitor side. See the `GLANCE.Cobrowse.Visitor` API documentation for details.
onvisibility	{ visibility : ["hidden"\|"visible"] } The visibility event fires when the visitor's browser tab visibility changes.

Error Handling

The onfail parameters to GLANCE.Presence.Agent methods should be a function which takes a "reason" parameter. The "reason" codes will be one of the following:

authorization – Authorization token missing, bad, or expired
connection – Network connection could not be established. See the browser console for details.

Sample Code

See Sample Code for details.

Updated on 11 May 2021