Visitor Presence API – SDK
The Visitor Presence API is implemented on the
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.
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.
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.
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|
e.g. no gserver configured for sdk version
|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.
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.
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|
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.
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.
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.
PresenceVisitor API Recommended Usage
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
The agent side presence API will be implemented at a future date.
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
If an agent sends a showTerms signal via presence with the Default UI enabled, the default UI calls