Visitor Presence API – SDK

The Visitor Presence API is implemented on the Glance.Presence.Visitor namespace.

All PresenceVisitor API calls should be made from the main thread.

Before using the Presence API, the application must first:

  • call Glance.Visitor.Init() to specify a group ID and a visitor ID.
  • call Glance.Visitor.SetEventHandler (or set an OnEvent delegate) in order to detect presence events.
  • wait for an EventVisitorInitialized event to fire. If the Glance service is inaccessible, this event may not fire.

Glance.Visitor.init(VisitorInitParams vip)

Initialize the Visitor API.

VisitorInitParams includes a group ID, visitor ID and site (staging vs. production). It looks up the host name of the Presence Service based on the group ID and site.

The visitor ID has the same restrictions as session key: max 62 characters, alphanumeric, – , _, and ~ characters allowed. If the visitor ID does not meet these criteria, EventInvalidParameter is fired.

Calling init multiple times with different visitor IDs is not supported. After the visitor ID is set in a call to init(), it cannot be changed.

Visitor.init() issues a web service request to look up visitor settings which are needed in order to connect to presence. If the settings lookup fails, the application will still receive an EventVisitorInitialized event. If connect() or any other PresenceVisitor methods are then called, the SDK will retry the web service request to get the visitor settings.

Glance.PresenceVisitor.connect()

Connect to the Presence service. The Visitor must be connected to send presence information or receive signals from the Agent.

When connected, the SDK notifies the Presence Service of various visitor side events such as screenshare session started, session ended, application in the background.

Event Data Agent side event
visitorerror
e.g. no gserver configured for sdk version
“code”:”conndrop”,”msg”:”Connect failed”,”params”: onvisitorerror
visitorsessionstart onvisitorsessionstart
visitorsessionend “reason”:”error” onvisitorsessionend
visibility hidden (background) visible (foreground)

If the SDK is already connected, calling connect() again does nothing.

Upon connecting, the SDK sends the following information to the Presence Service:

  • Device type
  • Operating system
  • Device ID

Glance.PresenceVisitor.presence(map<string, string> data)

presence() notifies the Presence Service that a visitor is using the application. presence() can only be called once the application has connected to the Presence service with connect(). data is a property map which is delivered to the Agent as a JSON object in the onpresence event. Standard properties that may be in the data map are:

url: A string indicating what area of the application the visitor is currently using.

You may specify custom properties in the call to presence(), but they must be prefixed with “c_” to prevent conflicts with standard properties.

Presence is not intended to transfer large data sets. The maximum number of properties allowed is 20 with a limit of 2,000 characters per property and 10,000 total size. The maximum length of a property name is 64 characters. Attempting to send presence data which exceeds these limits results in an EventInvalidParameter event.

An application may call presence() whenever a visitor accesses a new area of the application. This allows an Agent to see what area of the application a visitor is using, even before establishing the screenshare session.

If an application’s connection has been “blurred” by another application, calling presence() causes the application to reconnect to presence and take focus. A best practice is to only call presence() when a user interacts with the application. presence() should be called on average no more than once per minute for typical application usage.

Glance.Visitor.OnEvent

While connected to the Presence Service, the following Events may fire on the event thread, calling the Glance.Visitor.OnEvent handler:

EventException An unexpected exception occurred
EventInvalidParameter The application passed an invalid parameter to an API call
EventPresenceConnected The application successfully connected to the Presence Service, or reconnected after a connection drop. Applications can call any “signal” method after receiving this event.
EventPresenceNotConfigured Presence is not enabled for the group or is not correctly configured
EventPresenceConnectFail There was an error connecting to the Presence Service, or the connection dropped. The event properties include:
reason: Diagnostic text message suitable for logging. Applications can continue to call presence() and signal methods anyway, as those methods will retry the connection.
EventPresenceSignal The agent has signaled the visitor. The event properties are parsed from the JSON sent by the agent. This event fires for signals other than showTerms or startSession
EventPresenceStartSession The agent has signaled the visitor to start a session. If the Visitor API is initialized, the SDK automatically handles the session start and does not fire this event.
EventPresenceShowTerms The agent has signaled the visitor to show terms and conditions. The Glance SDK provides a default UI for displaying terms and conditions.
Properties:
termsurl: the terms and conditions url
EventPresenceBlur The presence connection is closed because another client has connected with the same visitor ID. The next time the application calls Glance.Presence.Visitor.presence(), the SDK will reconnect to the Presence Service.
EventPresenceSendFail The application attempted to send a message while presence was disconnected.

Glance.PresenceVisitor.signalAgent(string eventName, PropertyMap data)

Send a message to the agent. data is a property map that will be delivered to the Agent as an event. It is an error to call signalAgent if presence is not connected. If the connection is blurred, signalAgent automatically reconnects the client to the Presence Service.

Standard events are:

vent Name data Agent Event
terms status “displayed” “accepted”

Custom events may be sent using signalAgent. However any custom events must be prefixed with “c_” to avoid potential conflicts with the Glance event namespace.

Glance.PresenceVisitor.signalVisibility(bool visible)

Application should call this when the application goes to the background or is activated, in order to signal the application visibility status to the agent.

Glance.Presence.Visitor.disconnect()

Disconnect from the Presence service and terminate the Presence thread. Once disconnect is complete, EventDisconnected is fired. It is an error to call connect() again before EventDisconnected is received. A best practice is to call connect() when the application starts and disconnect() when the application exits.

Most applications will:

  • use the default UI
  • call Visitor::Init() when the application first loads. This serves to initialize both the Visitor and the PresenceVisitor apis.
  • call PresenceVisitor::Connect() once EventVisitorInitialized fires
  • call PresenceVisitor::presence(url => [area name]}) whenever the user enters a new area of the application
  • call PresenceVisitor::signalVisibility() when the application becomes active or goes into the background
  • call PresenceVisitor::Disconnect() once the application exits

Note that even if Connect() fails, subsequent calls to presence() will attempt to connect again. If connect() succeeds but the connection drops, the SDK will automatically attempt to reconnect.

Agent Presence API

GlancePresence.Agent

The agent side presence API will be implemented at a future date.

Default UI

There will be a Glance.VisitorUI.showTerms() method which will display a T&C message box with a link to a terms and conditions web page as specified in the EventPresenceShowTerms “termsurl” property, and Accept and Decline buttons.

If the visitor clicks Accept, the default UI starts the session using the visitor ID as the session key.

If there is a Presence connection open, the default UI notifies the Agent as the terms and conditions are displayed, accepted, or declined using the Glance.Presence.Visitor.signalTerms() method.

EventPresenceShowTerms

If an agent sends a showTerms signal via presence with the Default UI enabled, the default UI calls Glance.VisitorUI.showTerms().

By continuing to use the site, you agree to the use of cookies. Learn More