Screen Share

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:

  • show
  • guestInfoFlags
  • encrypt
  • requestRC
  • instantJoin
  • viewerCloseable
  • DisplayParams

DisplayParams

Parameters that specify what to show when the session starts. DisplayParams consists of:

Parameter Description
DisplayParams 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.
captureWidthcaptureHeight 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 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 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
 EventChildSessionEnded  Info  A child session has ended.

 

Properties:

  • sessiontype: The session type specified by the Agent, for example”agentVideo”
EventJoinChildSessionFailed Info The Visitor received an invitation to join a child session but was unable to join it.