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:
| Session Key | Description |
|---|---|
| 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. |
void StartSession()
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 EventConnectedToSession event.
Calling StartSession while already in a session results in an EventInvalidState event.
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.
StartParams
Parameters which specify how a session should start.
| Parameter | Description |
|---|---|
| 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. |
| paused | Session should start in a paused (hidden) state. Applies to "show" sessions. |
| presenceStart | Session is being started via presence invoke. |
Unused parameters
The following properties of StartParams are not used or not applicable to the GlanceVisitor API:
showguestInfoFlagsencryptrequestRCinstantJoinviewerCloseableDisplayParams
DisplayParams
Parameters that specify what to show when the session starts. DisplayParams consists of:
| Parameter | Description |
|---|---|
displayName | Controls what display, device, or application is shown. By default, the Glance SDK displays the current application. To show a whole monitor or device, call GetDisplayName to get the names of currently connected monitors and devices, and pass the return value as displayName. Pass main as display name in order to show the user's primary monitor. To show a specific application other than the current application, pass Applications for displayName and useapplication to specify the application to show. |
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. |
captureWidth / captureHeight | Similar to scale, setting captureWidth and captureHeight scales the captured display to fit the specified capture width and height. |
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 GetDisplayType. |
application |
EndSession()
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
GetSessionInfo
Returns information about the currently running session, if any. SessionInfo includes:
| Name | Description |
|---|---|
callId | The id of this call. Pass this value as mainCallId when starting a child session of this session. If there is no session running, callid will be 0. |
nGuests | Number of guests (Agents) currently in the session |
glanceAddress | Not used for this type of session |
key | Session key |
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 |
Pause(pause)
If pause is true, pause the session so that Agents viewing the session see only a white screen with an informational message.
If pause is false, resume the session.
EnableRC(enable)
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.
ShowDisplay(displayParams)
Show the monitor, application, or device indicated in displayParams. See additional information on DisplayParams.
LeaveChildSession(sessionType)
Close the child session specified by sessionType.
Displays
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.
GetDisplayCount()
Returns the total number of connected monitors, devices, and webcams that are available for screen share.
GetMainMonitor()
Returns the index of the user's primary monitor.
IdentifyMonitors()
Draw a number on each connected monitor so that the user can identify which number corresponds to which monitor.
GetDisplayType(n)
Returns the type of display (Monitor, Device) at index n.
GetDisplayName(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
termsUrl
Child Sessions
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 EventChildSessionStarted, EventChildSessionEnded, 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 Glance client tags agent video sessions with session type "agentVideo", browser HD video sessions have type "agentVideoHD".
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.
HD Agent Video Child Sessions
Agents on Chrome browsers can start HD Agent Video sessions. The Mac SDK will display HD video using a web view. The Windows SDK does not have built-in functionality for displaying HD video, however, if the application includes an embedded browser (such as the Chromium Embedded Framework or the Edge WebView2 control) it may handle events from the SDK to display the child video session in the embedded browser. Please contact Glance for details and sample code.
Screen Share Session Events
The following events may be fired while using the GlanceVisitor API.
| Event | Type | Description |
|---|---|---|
| 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 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 an 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: • SessionEndReasonThisSide: The session was intentionally ended by a call to EndSession() • SessionEndReasonOtherSide: The session was ended by the Agent • SessionEndReasonCantConnect: The session ended because the Glance SDK was never able to connect to the Glance screen share service. • SessionEndReasonConnDrop: The session ended because the connection dropped and could not be re-established. • SessionEndReasonKilled: The session was killed due to too many simultaneous sessions. • SessionEndTimedout: The session ended because no Agent joined. • SessionEndReasonError: The session ended due to an unexpected error. |
| 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 be 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. Properties: • sessionkey: The session key of the child session • sessiontype: The session type specified by the Agent, for example "agentVideo" • timestamp: Internal use only • username: The Glance username for the Agent |
| EventJoinChildSessionFailed | Info | The Visitor received an invitation to join a child session but was unable to join it. |