Presence Visitor API

For more control over the type and frequency of Presence data, and to allow the visitor to listen for custom messages, you can load the API, but suppress the default Presence behavior:

  • Include the standard Cobrowse script tag to get the GLANCE.Cobrowse.Loader API.

  • Set data-presence=“api” in the script tag. The Visitor Presence script also includes SockJS, which defines a single global variable SockJS.

The Presence Visitor API is defined in the namespace GLANCE.Presence.Visitor. Use the Visitor API to customize presence behavior. As noted above, it is not necessary to make any API calls in order to get the behavior described under Default Presence Behavior.

All API calls take a single JavaScript object as a parameter.

GLANCE.Presence.Visitor(params)

Constructor for a Visitor Object

Using the Glance Presence Visitor API without Cobrowse

In order to use the Glance Presence Visitor API on a page that does not have a cobrowse script tag, add the following script tag to the page:

<script src="https://www.glancecdn.net/cobrowse/CobrowseJS.ashx?group=72&site=staging&script=PresenceVisitor"></script>

Constructor for a Visitor Object

Parameters

{
  "groupid" : [group id], // defaults to GLANCE_COBROWSE.groupid
  "visitorid" : [visitor id] // defaults to GLANCE_COBROWSE.visitorid
}

Do not specify a visitorid if the visitor will connect using connectUnique.

See this page for more information on Glance Cobrowse.

GLANCE.Presence.Visitor.prototype.presence(params)

Sends Presence information to the Presence service.

Parameters

{
  "data": [custom data to be stored on the presence server] // optional
}
Info

Data must be a JavaScript object whose properties are of type string or number.

The first time presence() is called after a new page is loaded, general visitor information such as URL and browser are sent to the Presence service, as well as any user specified information. On subsequent calls to presence(), any new Presence information provided will be merged with any existing information already on the server.

GLANCE.Presence.Visitor.instance

GLANCE.Presence.Visitor.instance is set to the most recently instantiated GLANCE.Presence.Visitor object. This allows multiple scripts running on a page to share a single Visitor instance.

GLANCE.Presence.Visitor.prototype.connect()

Connect to the Presence service to listen for Presence events related to the visitor. Behind the scenes, this method opens a SockJS connection to a specific Presence server. If the Presence server instance shuts down due to an auto scaling event, the Visitor object automatically connects to a new Presence server instance.

connect() must be called on the visitor side in order to receive commands from the agent, for example if the agent calls signalVisitor() or invokeVisitor().

If the visitor navigates to a new page, connect() must be called again to reestablish the connection. If the visitor is not connected at the time an agent signals or invokes the visitor, the visitor will receive the message upon next connection.

If a new visitor connection is opened with the same visitor id, for example because the visitor opened a new browser tab to the same website, or switched from the website to a desktop application, the second connection takes focus and the first connection is sent a “blur” message.

GLANCE.Presence.Visitor.prototype.connectUnique()

Open a unique connection to the Presence service. A unique connection may be used in a scenario where a predetermined visitor id is not known to both visitor and agent. A unique connection differs from a non-unique connection in that:

  • The Presence Service assigns a 6 digit unique id (see the onunique event)
  • A unique connection times out after 5 minutes
  • Once a unique connection is established, no other connection can be made with the same unique id

GLANCE.Presence.Visitor.prototype.extendUnique()

Extends the timeout for an already open unique connection by another 5 minutes.

GLANCE.Presence.Visitor.prototype.setVisitorId(visitorid)

Change the visitor ID. If the presence instance is already connected to the Presence Service, calling setVisitorId() will disconnect and reconnect using the specified visitor ID.

GLANCE.Presence.Visitor.setVisitorId(visitorid)

Change the Visitor ID for the most recently constructed GLANCE.Presence.Visitor instance.

Warning

When using setVisitorId, the initial value of visitor id on page load can not be null. If the value of the visitor id on page load is not known, use a placeholder value and then change it with setVisitorID at a later date.

GLANCE.Presence.Visitor.prototype.disconnect()

Disconnect the Presence Visitor from the Presence service.

Visitor Events

Before calling connect(), add event handlers as properties on the Visitor instance. Supported events are:

Event Description
onerror See Glance.Presence.Agent onerror event.
onsignal(data) onsignal fires when the agent sends a message via signalVisitor({ "data" : data }). Data contains the object passed into signalVisitor by the agent.
onunique(uniqueid) Fires when the Presence Service has assigned a unique id to a connection established with connectUnique().

Visitor Presence and Focus

If a visitor has multiple windows or tabs open, only the currently active tab will send presence information or listen for messages from agents.

Sample Code

See Sample Code for details.