Constants, Functions, and Events for Embedded Amazon AppStream 2.0 Streaming Sessions - Amazon AppStream 2.0
Working with HIDDEN_ELEMENTSFunctions for the AppStream.Embed ObjectEvents for Embedded AppStream 2.0 Streaming SessionsExamples for Adding Event Listeners and Ending an Embedded AppStream 2.0 Streaming Session

Constants, Functions, and Events for Embedded Amazon AppStream 2.0 Streaming Sessions

The following topics provide reference information for constants, functions, and events that you can use to configure embedded AppStream 2.0 streaming sessions.

The following AppStream 2.0 user interface elements can be passed into the HIDDEN_ELEMENTS configuration option when an embedded AppStream 2.0 streaming session is initialized.

Working with HIDDEN_ELEMENTS

The following AppStream 2.0 user interface elements can be passed as constants into the HIDDEN_ELEMENTS configuration option when an embedded AppStream 2.0 streaming session is initialized. 

AppStream.Embed.Elements.TOOLBAR
AppStream.Embed.Elements.FULLSCREEN_BUTTON
AppStream.Embed.Elements.END_SESSION_BUTTON
AppStream.Embed.Elements.TOOLBAR
AppStream.Embed.Elements.CATALOG_BUTTON
AppStream.Embed.Elements.WINDOW_SWITCHER_BUTTON
AppStream.Embed.Elements.FILES_BUTTON
AppStream.Embed.Elements.CLIPBOARD_BUTTON
AppStream.Embed.Elements.COPY_LOCAL_BUTTON
AppStream.Embed.Elements.PASTE_REMOTE_BUTTON
AppStream.Embed.Elements.SETTINGS_BUTTON
AppStream.Embed.Elements.STREAMING_MODE_BUTTON
AppStream.Embed.Elements.SCREEN_RESOLUTION_BUTTON
AppStream.Embed.Elements.REGIONAL_SETTINGS_BUTTON
AppStream.Embed.Elements.FULLSCREEN_BUTTON
AppStream.Embed.Elements.END_SESSION_BUTTON

The following three elements can be passed as strings into HIDDEN_ELEMENTS, rather than as constants.

String Description
'adminCommandsButton' When you are connected to an AppStream 2.0 image builder, the Admin Commands button displays on the top right corner of the AppStream 2.0 toolbar. Passing this string into HIDDEN_ELEMENTS hides the Admin Commands button.
'softKeyboardButton' During AppStream 2.0 streaming sessions on touch-enabled devices, users can tap the keyboard icon on the AppStream 2.0 toolbar to display the on-screen keyboard. Passing this string into HIDDEN_ELEMENTS hides the keyboard icon.
'keyboardShortcutsButton' During AppStream 2.0 streaming sessions on touch-enabled devices, users can tap the Fn icon on the AppStream 2.0 toolbar to display keyboard shortcuts. Passing this string into HIDDEN_ELEMENTS hides the Fn icon.

Functions for the AppStream.Embed Object

The following table lists the functions that can be performed on the AppStream.Embed object.

Function Description
AppStream.Embed(containerId:string, options:object) The AppStream.Embed object constructor. This constructor initializes and communicates with the AppStream.Embed object, and it uses a div container ID. The ID is used to inject the iframe. It also injects an object that includes the configuration options for appstreamOptions (sessionURL and HIDDEN_ELEMENTS).
endSession() This function ends the streaming session, but does not destroy the iframe. If you specify a redirect URL, the iframe attempts to load the URL. Depending on the CORS headers of the page, the URL may not load.
launchApp(appId:string) This function programmatically launches an application with the application ID that was specified during image creation.
launchAppSwitcher() This function sends the AppSwitcher command to the AppStream 2.0 portal. This triggers the AppSwitcher command on the instance.
getSessionState() This function returns an object for sessionStatus. For more information, see Events for Embedded AppStream 2.0 Streaming Sessions.
getUserInterfaceState()

This function returns an object for UserInterfaceState. The object contains the key-value pairs for the following:

sessionStatus: State enumeration

sessionTerminationReason: String

sessionDisconnectionReason: String

For more information, see Events for Embedded AppStream 2.0 Streaming Sessions.
addEventListener(name, callback) This function adds a callback function to call when the specified event is triggered. For a list of the events that can be triggered, see Events for Embedded AppStream 2.0 Streaming Sessions.
removeEventListener(name, callback) This function removes the callback for the specified events.
destroy() This function deletes the iframe and cleans up resources. This function does not affect streaming sessions that are in progress.

Events for Embedded AppStream 2.0 Streaming Sessions

The following table lists the events that can be triggered during embedded AppStream 2.0 streaming sessions.

Event Data Description
AppStream.Embed.Events.SESSION_STATE_CHANGE

sessionStatus: State enumeration

sessionTerminationReason: String

sessionDisconnectionReason: String

This event is triggered when any session state change occurs. The event includes a map of the states that changed. To retrieve the full session state, use the getSessionState() function.

Following are the session states:

AppStream.Embed.SessionStatus.Unknown — The session has not started and is not reserved

AppStream.Embed.SessionStatus.Reserved — The session is reserved but has not started.

AppStream.Embed.SessionStatus.Started — The user connected to the session and started streaming.

AppStream.Embed.SessionStatus Disconnected — The user disconnected from the session.

AppStream.Embed.SessionStatus.Ended — The session was marked as ended or expired.
AppStream.Embed.Events.SESSION_INTERFACE_STATE_CHANGE

hiddenElements: Array of strings

isFullscreen: Boolean

isSoftKeyboardVisible: Boolean

 This event is triggered when any session state change occurs. The event includes a map of the states that changed. To retrieve the full session state, use the getSessionState() function.
AppStream.Embed.Events.SESSION_ERROR

errorCode: Number

errorMessage: String

 This event is triggered when any errors occur during a session.

Examples for Adding Event Listeners and Ending an Embedded AppStream 2.0 Streaming Session

The examples in this section show how to do the following:

  • Add event listeners for embedded AppStream 2.0 streaming sessions.

  • Programmatically end an embedded AppStream 2.0 streaming session.

Example 1: Add event listeners for embedded AppStream 2.0 streaming sessions

To add event listeners for session state changes, session interface state changes, and session errors during embedded streaming sessions, use the following code:

appstreamEmbed.addEventListener(AppStream.Embed.Events.SESSION_STATE_CHANGE, updateSessionStateCallback);

appstreamEmbed.addEventListener(AppStream.Embed.Events.SESSION_INTERFACE_STATE_CHANGE, updateUserInterfaceStateCallback);

appstreamEmbed.addEventListener(AppStream.Embed.Events.SESSION_ERROR, errorCallback);

In this example, AppStream.Embed.Events.SESSION_STATE_CHANGE, AppStream.Embed.Events.SESSION_INTERFACE_STATE_CHANGE, and AppStream.Embed.Events.SESSION_ERROR are event names.

The updateSessionStateCallback, updateUserInterfaceStateCallback, and errorCallback functions are ones that you implement. These functions are passed into the addEventListener function and called when an event is triggered.

Example 2: Programmatically end an embedded AppStream 2.0 streaming session

To end an embedded AppStream 2.0 streaming sessions, use the following function:

appstreamEmbed.endSession();