The Screen Share API is implemented on the GlanceVisitor class, and can be used to start and control screen Share sessions.
Starting and Stopping a Session
Call one of the
StartSession methods to start a screen Share session. If the session successfully starts, an
EventConnectedToSession event will fire. If the session fails to start,
EventStartSessionFailed will fire.
If using the Default UI, calling
StartSession will display a message box with a link to terms and conditions before actually starting the session. If using One-Click Connect,
StartSession is called automatically by the Glance SDK. See One-Click Connect.
Every screen share session has a unique session key which will be required for the Agent to view the session. A session key may be a Visitor ID, a unique key randomly generated by Glance, or a key specified by the application:
|Visitor ID||When using a Visitor ID as session key, an Agent using a CRM that is integrated with Glance can view the session without having to exchange the session key over the phone.|
|Random Key||Glance can optionally generate a unique random key. A random key will include digits only. The length of the random key is a configurable group setting. The application will typically display the session key in the user interface, to be read to the Agent over the phone.|
|Specified Key||The application can specify a key to use for the session. A session key has the same length and character restrictions as Visitor ID.|
Start a Glance screen share session to show the application.
If a Visitor ID has been specified in a call to
init, Glance will use that Visitor ID as the session key.
If no Visitor ID has been specified in a call to
init, Glance will choose a random session key. If the session successfully starts, the session key will be included on the properties of the
StartSession while already in a session results in an
void StartSession(String sessionKey)
Start a Glance screen share session with the specified session key. Pass
GLANCE_KEYTYPE_RANDOM to start a session with a random key.
void StartSession(StartParams sp)
Start a Glance session with the specified parameters.
Parameters which specify how a session should start.
|mainCallId||If this session is a “child session” of another session, pass the numeric call id of the parent session in mainCallId. Passing a mainCallId associates the sessions in the Glance database. Pass 0 (default) if the session being started is the main session.|
|maxGuests||Maximum number of guests who may join the session. Pass 0 (default) for no limit, other than the limit imposed by the group settings and subscriptions.|
|key||The session key, or “GLANCE_KEYTYPE_RANDOM” to have Glance choose a random key.|
|displayParams||See DisplayParams below|
|forceTunnel||Force the session to use a tunneling protocol. Specify false (default) to have the Glance SDK automatically fall back to tunneling if and only if the TCP socket protocol fails to connect.|
|reportErrors||Pass true if the Glance SDK should record errors to the session record. Pass false (default) to only log errors to a local log.|
|persist||Pass true if the session should continue even if the Agent leaves the session. Pass false (default) if the session should automatically end when the last Agent leaves the session.|
The following properties of StartParams are not used or not applicable to the GlanceVisitor API:
Parameters that specify what to show when the session starts. displayParams consists of:
|scale||A floating point numeric scale factor for the screen capture. A scale factor of 1.0 (default) captures the screen at full resolution. scale is typically used when showing a device or webcam.|
|captureWidthcaptureHeight||Similar to scale, setting
|video||True to share using “video mode”, appropriate when sharing a device or webcam at low resolution. Only set video to true if sharing a display of type “video” as returned by
End the session. The application should wait for
EventSessionEnded before attempting to start a new session or exiting the application.
The Screen Share API is implemented on the
GlanceVisitor class, and can be used to control screen Share sessions.
Controlling a Screen Share Session
Returns information about the currently running session, if any.
|callId||The id of this call. Pass this value as
|nGuests||Number of guests (Agents) currently in the session|
|glanceAddress||Not used for this type of session|
|hostName||Not used for Visitor Sessions|
|rcRequested||Not used for Visitor Sessions|
|isGuest||False for Visitor Sessions|
|isReverse||False for Visitor Sessions|
|rcEnabled||True if remote control is currently enabled|
|sbEnabled||True if showback is currently enabled|
|gesturesEnabled||True if gestures are enabled|
|isPaused||True if the session is paused|
|isConnected||True if the participant is currently connected|
|isShowing||True if currently showing|
|isViewing||True if currently viewing|
|displayName||Name of the display currently being shown|
If pause is true, pause the session so that Agents viewing the session only a white screen with an informational message.
If pause is false, resume the session.
If enable is true, enable remote control so that the Agent can control the Visitor’s desktop. If enable is false, disables remote control. Agent must have Remote Control privileges. Desktop only.
Show the monitor, application, or device indicated in
displayParams. See additional information on DisplayParams.
Close the child session specified by
Documentation and sample code for masking the screen or specific UI elements is provided in the platform-specific README files.
Each monitor or device connected to the Visitor’s computer is a “display” which can be shared with the agent. Displays can be referenced by index, a number ranging from 0 to GetDisplayCount() -1.
Returns the total number of connected monitors, devices, and webcams that are available for screen share.
Returns the index of the user’s primary monitor.
Draw a number on each connected monitor so that the user can identify which number corresponds to which monitor.
Returns the type of display (Monitor, Device) at index n.
Returns the name of the display at index n, suitable for passing as the
displayName in the
DisplayParams. Note that display index can change as devices or monitors are connected or disconnected from the Visitor’s computer.
Default UI Configuration
During a screen share session, the Agent may choose to show the Visitor the Agent’s webcam, screen, or an application. These Agent initiated sessions are “child sessions” of the original screen share session; they are associated together in the session metadata, and ending the parent session ends all child sessions.
The Glance SDK notifies the application about events related to child sessions by firing events
EventJoinChildSessionFailed. The Glance SDK automatically opens a viewer to view child sessions, so the application is not required to take action to handle these events.
The Agent side tags each child session with a session type. The standard Glance client tags agent video sessions with session type “agentVideo.”
Configuring the Viewer for Child Video Sessions
By default, the Glance SDK opens a child session viewer in a new floating window. Applications may use
SetVideoViewerContext() to set a ViewerContext in order to embed a child session viewer in an existing application window.
True Agent Video Child Sessions
The Glance client version 4.7 and later is capable of generating true agent video. An embedded browser is required to view these sessions in the application.
Screen Share Session Events
The following events may be fired while using the GlanceVisitor API.
|EventInvalidParameter||Assert||A parameter passed to an SDK method is not valid.|
|EventInvalidState||Assert||A method was called and the application was in an invalid state.|
|EventVisitorInitialized||Info||Visitor initialization has completed.|
|EventPrivilegeViolation||Error||The application attempted to do carry out an operation not allowed by the group settings.|
|EventUpgradeAvailable||Info||An upgrade to the Glance SDK is available.|
|EventUpgradeRequired||Error||The Glance SDK must be upgraded in order to connect to the Glance service.|
|EventCompositionDisabled||Info||Windows Desktop Composition was disabled in order to improve screen capture performance on Windows.|
|EventConnectedToSession||Info||The Glance SDK successfully connected to the session.|
|EventSwitchingToView||Info||The Agent is switching to show and the application is switching to view the Agent’s session|
|EventStartSessionFailed||Error||`StartSession` was called and the session failed to start. `EventStartSessionFailed` fires if the SDK is unable to connect to the internet, or if there is a service outage or group configuration error. **Properties:** The “error” property will contain an error code if the problem was inability to connect to the internet.|
|EventSessionEnded||Info|| The session and any child sessions have all ended. **Properties:** The “reason” property will be one of the following codes:
|EventTunneling||Info||The Glance SDK was unable to connect using a TCP socket, typically due to a firewall restriction, and is connected to the Glance Screen Share Service using a tunneling protocol. No action is needed on the part of the application to handle this event, but the session performance may slightly degraded.|
|EventConnectionWarning||Warning||The connection has dropped. The Glance SDK will attempt to automatically reconnect for up to one minute. If the reconnect attempt succeeds, EventClearWarning fires. Otherwise the session ends with EventSessionEnded.|
|EventClearWarning||Info||The dropped connection has been reestablished.|
|EventGuestCountChange||Info||An Agent has joined or left the session.|
|EventRCDisabled||Info||There was an attempt to allow remote control, but remote control is not enabled for the account.|
|EventDeviceDisconnected||Info||The device being shared has been disconnected from the Visitor’s computer.|
|EventDeviceReconnected||Info||The device being shared has been reconnected.|
|EventException||Error||An unexpected error has occurred.|
|EventScreenshareInvitation||Not used with GlanceVisitor API|
|EventMessageReceived||Info||The Agent sent a custom message through the screen share session. **Properties:** The message properties are determined by the Agent client sending the message.|
|EventChildSessionStarted||Info|| A child session has started. The Glance SDK automatically joins child sessions.
|EventChildSessionEnded||Info|| A child session has ended.
|EventJoinChildSessionFailed||Info||The Visitor received an invitation to join a child session but was unable to join it.|