Amazon AppStream 2.0
Administration Guide

Embed AppStream 2.0 Streaming Sessions

You can create a dynamic, interactive, and customized experience for your users by embedding an AppStream 2.0 streaming session within your website. Embedded AppStream 2.0 streaming sessions let your users interact with 3D models, maps, and datasets directly from your website. For example, users can view training instructions or educational materials alongside their AppStream 2.0 streaming session.

Prerequisites

To embed an AppStream 2.0 streaming session in a website, you must have the following:

Recommendations and Usage Considerations

Consider the following recommendations and usage notes for embedded AppStream 2.0 streaming sessions.

  • To maintain maximum control over the embedded AppStream 2.0 streaming experience for your users, we recommend that you configure short-lived streaming URLs that last approximately 5 seconds. Any user can inspect the contents of a webpage and view its source. This includes the document object model (DOM) and the src (source) URL of the iframe. If the URL is still valid when a user copies it, that user can paste the URL in a separate browser tab and stream the session with the standard AppStream 2.0 portal user interface, without the embed options.

  • Concurrent sessions are not supported when custom domains are used for embedded AppStream 2.0 streaming sessions. Concurrent sessions occur when users start two embedded AppStream 2.0 streaming sessions either on the same webpage or across two different browser tabs.

Step 1: Specify a Host Domain for Embedded AppStream 2.0 Streaming Sessions

To embed an AppStream 2.0 streaming session in a webpage, first update your stack to specify the domain to host the embedded streaming session. This a security measure to ensure that only authorized website domains can embed AppStream 2.0 streaming sessions. To do so, use any of the following methods:

  • The AppStream 2.0 console

  • The EmbedHostDomains API action

  • The embed-host-domains AWS command line interface (AWS CLI) command

To specify a host domain by using the AppStream 2.0 console, perform the following steps.

  1. Open the AppStream 2.0 console at https://console.aws.amazon.com/appstream2.

  2. In the left navigation pane, choose Stacks, and select the stack that you want.

  3. Choose Edit.

  4. Expand Embed AppStream 2.0 (Optional).

  5. In Host Domains, specify a valid domain. For example: training.example.com.

  6. Choose Update.

Step 2: Create a Streaming URL for User Authentication

You must create a streaming URL to authenticate users for embedded AppStream 2.0 streaming sessions. SAML 2.0 and user pools are currently not supported for embedded streaming sessions. To create a streaming URL, use one of the following methods:

Configuration Requirements for Using Custom Domains

Whether you use custom domains to apply your company branding or to ensure that embedded AppStream 2.0 streaming sessions work with browsers that block third-party cookies, the configuration requirements are the same.

For web browsers that block third-party cookies, custom domains are required. AppStream 2.0 uses browser cookies to authenticate streaming sessions and lets users reconnect to an active session without being prompted to provide their user name and password every time. By default, AppStream 2.0 streaming URLs include appstream.com as the domain. When you embed a streaming session within your website, appstream.com is treated as a third-party domain. As a result, streaming sessions may be blocked when modern browsers are used that block third-party cookies by default.

To avoid embedded AppStream 2.0 streaming sessions from being blocked in this scenario, follow these steps:

  1. Specify a custom domain to host your embedded AppStream 2.0 streaming sessions.

    When you configure your custom domain, make sure that the domain is a subdomain of the webpage in which you plan to embed AppStream 2.0. For example, if you update your stack to specify training.example.com as the host domain, you can create a subdomain called content.training.example.com for your embedded streaming sessions.

  2. Create a streaming URL for embedded AppStream 2.0 streaming sessions that uses the same custom subdomain. To create the streaming URL, use the CreateStreamingURL API action or the create-streaming-url AWS CLI command. You cannot use the AppStream 2.0 console to create a streaming URL in this scenario.

    To create a streaming URL for embedded AppStream 2.0 streaming sessions, in the URL, replace appstream2.region.aws.amazon.com with your own domain.

    By default, AppStream 2.0 streaming URLs are formatted as follows:

    https://appstream2.region.aws.amazon.com/authenticate?parameters=authenticationcode

    If your subdomain is content.training.example.com, your new streaming URL follows this format:

    https://content.training.example.com/authenticate?parameters=authenticationcode

    Note

    When you create a custom domain, you can use the domain for embedded AppStream 2.0 streaming sessions only in the AWS Region for which it was configured. If you plan to support custom domains in multiple Regions, create a custom domain for each applicable Region.

  3. Add appstream-custom-url-domain to the header of the webpage that will host the embedded streaming sessions. For the header value, use the domain that your reverse proxy displays to users. For example:

    Header name: appstream-custom-url-domain Header value: training.example.com

    Setting a custom domain and creating a streaming URL that specifies the same domain lets the cookies be saved as first-party cookies. For information about how to configure custom domains by using Amazon CloudFront, see Using Custom Domains with AppStream 2.0.

Step 3: Download the Embedded AppStream 2.0 Files

To host embedded AppStream 2.0 streaming sessions, you must download and configure the provided AppStream 2.0 API JavaScript file.

  1. On the Embedding AppStream 2.0 in Your Website webpage, choose the link in step 1 to download the AppStream 2.0 Embed Kit .zip file, appstream_embed_<version>.zip.

  2. Navigate to the location where you downloaded the .zip file, and extract the contents of the file.

  3. The extracted contents of the file comprise one folder, appstream-embed. In addition to the COPYRIGHT.txt and THIRD_PARTY_NOTICES.txt file, this folder contains the following two files:

    • appstream-embed.js — Provides the embedded AppStream 2.0 API. This JavaScript file includes the functions and API actions for configuring and controlling your embedded AppStream 2.0 streaming session.

    • embed-sample.html — Describes how to use the embedded AppStream 2.0 API to initialize a streaming session, call functions, and listen for events. This sample file expands on the information in this topic, to provide an example use case for developers.

Step 4. Configure Your Website for Integration with AppStream 2.0

The following sections provide information about how to configure your webpage to host embedded AppStream 2.0 streaming sessions.

Import the appstream-embed JavaScript File

  1. On the webpage where you plan to embed the AppStream 2.0 streaming session, import the appstream-embed.js file into the webpage by adding the following code:

    <script type>="text/javascript" src="./appstream_embed.js"> </script>
  2. Next, create an empty container div. The ID of the div that you set is passed into the AppStream 2.0 embed constructor. It's then used to inject an iframe for the streaming session. To create the div, add the following code:

    <div id="appstream-container"> </div>

Initialize and Configure the AppStream.Embed Interface Object

To initialize the AppStream.Embed interface object in JavaScript, you must add code that creates an AppStream.Embed object with options for the streaming URL and user interface configuration. These options, and the div ID that you created, are stored in an object called appstreamOptions.

The following example code shows how to initialize the AppStream.Embed interface object.

var appstreamOptions = { sessionURL: 'https://appstream2.region.aws.amazon.com/authenticate?parameters=authenticationcode...', userInterfaceConfig:{[AppStream.Embed.Options.HIDDEN_ELEMENTS]:AppStream.Embed.Elements.TOOLBAR} }; appstreamEmbed = new AppStream.Embed("appstream-container", appstreamOptions);

In the code, replace sessionURL and userInterfaceConfig with your own values.

Note

The value specified for userInterfaceConfig hides the entire AppStream 2.0 toolbar. This value, which is included as an example, is optional.

sessionUrl

The streaming URL that you created by using the AppStream 2.0 console, the CreateStreamingURL API action, or the create-streaming-url AWS CLI command. This parameter is case-sensitive.

Type: String

Required: Yes

userInterfaceConfig

The configuration that generates the initial state of the user interface elements. The configuration is a key-value pair.

The key, AppStream.Embed.Options.HIDDEN_ELEMENTS, specifies the user interface objects that are initially hidden when the embedded AppStream 2.0 streaming session is initialized. Later, you can return both hidden and visible objects by using the getInterfaceState parameter.

The value is an array of constants (toolbar buttons). For a list of constants that you can use, see Constants for HIDDEN_ELEMENTS.

Type: Map (key:value)

Required: No

Examples for Hiding the Entire AppStream 2.0 Toolbar or Specific Toolbar Buttons

The following examples show how to hide one or more buttons on the AppStream 2.0 toolbar from users during their embedded AppStream 2.0 streaming sessions.

Example 1: Hide the entire AppStream 2.0 toolbar

To prevent users from accessing any button on the AppStream 2.0 toolbar during embedded streaming sessions, use the AppStream.Embed.Elements.TOOLBAR constant. This constant lets you hide all AppStream 2.0 toolbar buttons.

var appstreamOptions = { sessionURL: 'https://appstream2.region.aws.amazon.com/authenticate?parameters=authenticationcode...', userInterfaceConfig:{[AppStream.Embed.Options.HIDDEN_ELEMENTS]:[AppStream.Embed.Elements.TOOLBAR]} };

Example 2: Hide a specific button on the AppStream 2.0 toolbar

You can display the AppStream 2.0 toolbar, while preventing users from accessing a specific toolbar button during embedded streaming sessions. To do so, specify the constant for the button that you want to hide. The following code uses the AppStream.Embed.Elements.FILES_BUTTON constant to hide the My Files button. This prevents users from accessing persistent storage options during embedded streaming sessions.

var appstreamOptions = { sessionURL: 'https://appstream2.region.aws.amazon.com/authenticate?parameters=authenticationcode...', userInterfaceConfig:{[AppStream.Embed.Options.HIDDEN_ELEMENTS]:[AppStream.Embed.Elements.FILES_BUTTON]} };

Example 3: Hide multiple buttons on the AppStream 2.0 toolbar

You can display the AppStream 2.0 toolbar, while preventing users from accessing more than one toolbar button during embedded streaming sessions. To do so, specify the constants for the buttons that you want to hide. The following code uses the AppStream.Embed.Elements.END_SESSION_BUTTON and AppStream.Embed.Elements.FULLSCREEN_BUTTON constants to hide the End Session and Fullscreen buttons.

Note

Separate each constant with a comma, with no preceding or following space.

var appstreamOptions = { sessionURL: 'https://appstream2.region.aws.amazon.com/authenticate?parameters=authenticationcode... (https://appstream2.region.aws.amazon.com/#/)', userInterfaceConfig:{[AppStream.Embed.Options.HIDDEN_ELEMENTS]:[AppStream.Embed.Elements.END_SESSION_BUTTON,AppStream.Embed.Elements.FULLSCREEN_BUTTON]} };

Constants, Functions, and Events for Embedded 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.

Constants for HIDDEN_ELEMENTS

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.

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

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 following examples 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();