本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 內嵌 Amazon WorkSpaces 應用程式串流工作階段
<a name="embed-streaming-sessions"></a>

您可以在網站中內嵌 WorkSpaces 應用程式串流工作階段，為使用者建立動態、互動式和自訂的體驗。內嵌 WorkSpaces 應用程式串流工作階段可讓您的使用者直接從您的網站與 3D 模型、地圖和資料集互動。例如，使用者可以在其 WorkSpaces 應用程式串流工作階段中檢視訓練指示或教育資料。

**Topics**
+ [內嵌 Amazon WorkSpaces 應用程式串流工作階段的先決條件](embed-streaming-sessions-prerequisites.md)
+ [內嵌 Amazon WorkSpaces 應用程式串流工作階段的建議和用量考量](embed-streaming-sessions-recommendations-considerations.md)
+ [步驟 1：指定要內嵌 Amazon WorkSpaces 應用程式串流工作階段的主機網域](specify-host-domain-embedded-streaming-sessions.md)
+ [步驟 2：建立使用者驗證的串流 URL](create-streaming-url-user-authentication.md)
+ [步驟 3：下載內嵌 Amazon WorkSpaces 應用程式檔案](download-embed-files.md)
+ [步驟 4. 設定您的網站以與 Amazon WorkSpaces 應用程式整合](configure-website-for-integration.md)
+ [內嵌 Amazon WorkSpaces 應用程式串流工作階段的常數、函數和事件](constants-functions-events-embedded-sessions.md)

# 內嵌 Amazon WorkSpaces 應用程式串流工作階段的先決條件
<a name="embed-streaming-sessions-prerequisites"></a>

若要在網站中嵌入 WorkSpaces 應用程式串流工作階段，您必須具有下列項目：
+ 已設定的 WorkSpaces 應用程式環境，其中包含 WorkSpaces 應用程式映像、機群和堆疊。如需有關如何建立這些資源的資訊，請參閱 *WorkSpaces 應用程式管理指南*中的下列主題：
  +  [教學課程：使用 WorkSpaces 應用程式主控台建立自訂 WorkSpaces 應用程式映像](tutorial-image-builder.md) 或 [使用映像助理 CLI 操作，以程式設計方式建立 Amazon WorkSpaces 應用程式映像](programmatically-create-image.md)
  + [在 Amazon WorkSpaces 應用程式中建立機群](set-up-stacks-fleets-create.md)
  + [在 Amazon WorkSpaces 應用程式中建立堆疊](set-up-stacks-fleets-install.md)
+ 使用者身分驗證的串流 URL。SAML 2.0 和 WorkSpaces 應用程式使用者集區目前不支援做為內嵌 WorkSpaces 應用程式串流工作階段的身分驗證方法。
+ 或者，您可以將自訂網域用於內嵌 WorkSpaces 應用程式串流工作階段。您可以使用自訂網域，以便為使用者顯示自己的公司 URL，而不是 WorkSpaces 應用程式 URL。如果您的使用者使用封鎖第三方 Cookie 的網頁瀏覽器，則需要有自訂網域。
**注意**  
您可以使用 Amazon CloudFront 設定自訂網域。如需詳細資訊，請參閱[搭配使用自訂網域與 WorkSpaces 應用程式](https://aws.amazon.com/blogs/desktop-and-application-streaming/using-custom-domains-with-amazon-appstream-2-0/)。

  當您使用自訂網域時，您必須：
  + 建立使用相同網域的串流 URL。
  + 將 **appstream-custom-url-domain**新增至將託管內嵌 WorkSpaces 應用程式串流工作階段的網頁標頭。如為標頭值，請使用反向 Proxy 向使用者顯示的網域。如需詳細資訊，請參閱[使用自訂網域的設定需求](create-streaming-url-user-authentication.md#configuration-requirements-custom-domains)。

# 內嵌 Amazon WorkSpaces 應用程式串流工作階段的建議和用量考量
<a name="embed-streaming-sessions-recommendations-considerations"></a>

請考慮下列內嵌 WorkSpaces 應用程式串流工作階段的建議和用量備註。
+ 若要為使用者維持對內嵌 WorkSpaces 應用程式串流體驗的最大控制，建議您設定持續約 5 秒的短期串流 URLs。任何使用者都可以檢查網頁的內容並檢視其來源。這個部分包括 iframe 的文件物件模型 (DOM) 及 src (source) URL。如果 URL 在使用者複製時仍然有效，則該使用者可以將 URL 貼到單獨的瀏覽器索引標籤中，並使用標準 WorkSpaces 應用程式入口網站使用者介面串流工作階段，而無需內嵌選項。
+ 當自訂網域用於內嵌 WorkSpaces 應用程式串流工作階段時，不支援並行工作階段。當使用者在相同網頁上或跨兩個不同的瀏覽器索引標籤啟動兩個內嵌 WorkSpaces 應用程式串流工作階段時，會發生並行工作階段。您無法讓單一使用者具有並行工作階段，但可以有多個使用者。例如，使用者登入您的應用程式、您的應用程式產生串流 URL 以提供給客戶 (視為唯一使用者計費)、客戶載入串流 URL，然後客戶會指派至您所指定集區內的 appstream 執行個體。

# 步驟 1：指定要內嵌 Amazon WorkSpaces 應用程式串流工作階段的主機網域
<a name="specify-host-domain-embedded-streaming-sessions"></a>

若要在網頁中內嵌 WorkSpaces 應用程式串流工作階段，請先更新您的堆疊以指定網域來託管內嵌串流工作階段。這是安全措施，以確保只有授權的網站網域可以嵌入 WorkSpaces 應用程式串流工作階段。WorkSpaces 應用程式會將您指定的網域新增至 **Content-Security-Policy**(CSP) 標頭。如需詳細資訊，請參閱 Mozilla [MDN Web Docs](https://developer.mozilla.org/en-US/) 文件中的[內容安全政策 (CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP)。

如果要更新堆疊以指定要裝載嵌入式串流工作階段的網域，請使用以下任一方法：
+ WorkSpaces 應用程式主控台
+ `EmbedHostDomains` API 動作 
+ `embed-host-domains` AWS 命令列界面 (AWS CLI) 命令

若要使用 WorkSpaces 應用程式主控台指定主機網域，請執行下列步驟。

1. 在 https：//[https://console.aws.amazon.com/appstream2/home](https://console.aws.amazon.com/appstream2/home) 開啟 WorkSpaces 應用程式主控台。

1. 在左側導覽窗格中，選取 **Stacks (堆疊)**，然後選取您要使用的堆疊。

1. 選擇**編輯**。

1. 展開**內嵌 WorkSpaces 應用程式 （選用）**。

1. 在**主機網域**中，指定有效的網域。例如：**training.example.com**。
**注意**  
只有 HTTPS [TCP 連接埠 443] 支援內嵌串流工作階段。

1. 選擇**更新**。

# 步驟 2：建立使用者驗證的串流 URL
<a name="create-streaming-url-user-authentication"></a>

您必須建立串流 URL 來驗證內嵌 WorkSpaces 應用程式串流工作階段的使用者。SAML 2.0 和使用者集區目前不支援嵌串流工作階段。若要建立串流 URL，請使用下列其中一種方式：
+ WorkSpaces 應用程式主控台
+ [CreateStreamingURL](https://docs.aws.amazon.com/appstream2/latest/APIReference/API_CreateStreamingURL.html) API 動作 
+ [create-streaming-url](https://docs.aws.amazon.com/cli/latest/reference/appstream/create-streaming-url.html) AWS CLI 命令

## 使用自訂網域的設定需求
<a name="configuration-requirements-custom-domains"></a>

無論您是使用自訂網域來套用公司品牌，還是確保內嵌 WorkSpaces 應用程式串流工作階段可與封鎖第三方 Cookie 的瀏覽器搭配使用，組態需求都相同。

針對封鎖第三方 Cookie 的 Web 瀏覽器，須使用自訂網域。WorkSpaces 應用程式使用瀏覽器 Cookie 來驗證串流工作階段，並讓使用者重新連線至作用中工作階段，而不需每次都提示您提供登入資料。根據預設，WorkSpaces 應用程式串流 URLs會包含 **appstream.com**做為網域。當您在網站中嵌入串流工作階段時，**appstream.com** 會被視為第三方網域。因此，當使用者使用會根據預設封鎖第三方 Cookie 的新版瀏覽器時，串流工作階段就可能會遭封鎖。

若要避免在此案例中內嵌 WorkSpaces 應用程式串流工作階段遭到封鎖，請依照下列步驟執行：

1. 指定自訂網域來託管您的內嵌 WorkSpaces 應用程式串流工作階段。

   當您設定自訂網域時，請確定網域是您計劃內嵌 WorkSpaces 應用程式之網頁的子網域。舉例來說，如果您更新堆疊以指定 **training.example.com** 為主機網域，您就可以建立一個稱為 **content.training.example.com** 的嵌入串流工作階段子網域。

1. 為使用相同自訂子網域的內嵌 WorkSpaces 應用程式串流工作階段建立串流 URL。若要建立串流 URL，請使用 [CreateStreamingURL](https://docs.aws.amazon.com/appstream2/latest/APIReference/API_CreateStreamingURL.html) API 動作或 [create-streaming-url](https://docs.aws.amazon.com/cli/latest/reference/appstream/create-streaming-url.html) AWS CLI 命令。在此案例中，您無法使用 WorkSpaces 應用程式主控台建立串流 URL。

   若要為內嵌 WorkSpaces 應用程式串流工作階段建立串流 URL，請在 URL 中將**appstream2.***區域***.aws.amazon.com**取代為您自己的網域。

   根據預設，WorkSpaces 應用程式串流 URLs 的格式如下：

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

   如果您的子網域是 **content.training.example.com**，則您新的串流 URL 會採用以下格式：

   ```
   https://content.training.example.com/authenticate?parameters=authenticationcode
   ```
**注意**  
建立自訂網域時，您只能在設定該網域的 AWS 區域中，針對內嵌 WorkSpaces 應用程式串流工作階段使用網域。如果您計畫支援多個區域中的自訂網域，請針對每個適用的區域建立自訂網域。此外，只有 HTTPS [TCP 連接埠 443] 支援內嵌串流工作階段。

1. 新增 **appstream-custom-url-domain** 至將託管嵌入串流工作階段的網頁標頭中。如為標頭值，請使用反向 Proxy 向使用者顯示的網域。例如：

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

   設定自訂網域，並建立會指定相同網域的串流 URL，就可將 Cookie 儲存為第一方 Cookie。如需有關如何使用 Amazon CloudFront 設定自訂網域的資訊，請參閱[搭配使用自訂網域與 WorkSpaces 應用程式](https://aws.amazon.com/blogs/desktop-and-application-streaming/using-custom-domains-with-amazon-appstream-2-0/)。

在您為內嵌 WorkSpaces 應用程式串流工作階段設定自訂網域後，如果您URLs 未重新導向至您的自訂網域，或您的自訂網域未正確顯示給使用者，請參閱下列疑難排解主題：
+ [我為內嵌 WorkSpaces 應用程式串流工作階段設定自訂網域，但我的 WorkSpaces 應用程式串流 URLs 不會重新導向至我的自訂網域。](troubleshooting-general.md#embedded-streaming-sessions-streaming-urls-not-redirected-to-custom-domain)

# 步驟 3：下載內嵌 Amazon WorkSpaces 應用程式檔案
<a name="download-embed-files"></a>

若要託管內嵌 WorkSpaces 應用程式串流工作階段，您必須下載並設定提供的 WorkSpaces 應用程式 API JavaScript 檔案。

1. 在[網站網頁的內嵌 WorkSpaces 應用程式](https://clients.amazonappstream.com/embed.html)上，選擇步驟 1 中的連結，以下載 WorkSpaces 應用程式內嵌套件 .zip 檔案 **appstream\$1embed\$1<version>.zip**。

1. 瀏覽至您下載該壓縮檔案的位置，然後解壓縮檔案。

1. 在解壓縮的檔案中有一個名稱為 **appstream-embed** 的資料夾。除了 **COPYRIGHT.txt** 和 **THIRD\$1PARTY\$1NOTICES.txt **檔案之外，此資料夾也包含以下兩個檔案：
   + **appstream-embed.js** — 提供內嵌 WorkSpaces 應用程式 API。此 JavaScript 檔案包含用於設定和控制內嵌 WorkSpaces 應用程式串流工作階段的函數和 API 動作。
   + **embed-sample.html** — 說明如何使用內嵌 WorkSpaces 應用程式 API 來初始化串流工作階段、呼叫函數和接聽事件。此範例檔案會展開本主題中的資訊，以為開發人員提供使用範例。

# 步驟 4. 設定您的網站以與 Amazon WorkSpaces 應用程式整合
<a name="configure-website-for-integration"></a>

下列各節提供如何設定網頁以託管內嵌 WorkSpaces 應用程式串流工作階段的相關資訊。

**Topics**
+ [匯入 appstream-embed JavaScript 檔案](#import-embed-javascript-file)
+ [初始化和設定 `AppStream.Embed` 界面物件](#initialize-configure-embed-interface-object)
+ [WorkSpaces 應用程式使用者介面中的隱藏項目範例](#examples-hiding-user-interface-items)

## 匯入 appstream-embed JavaScript 檔案
<a name="import-embed-javascript-file"></a>

1. 在您計劃嵌入 WorkSpaces 應用程式串流工作階段的網頁上，新增下列程式碼，將 **appstream-embed.js** 檔案匯入網頁：

   ```
   <script type="text/javascript" src="./appstream_embed.js"> </script>
   ```

1. 接下來，建立一個空白的容器 div。您設定的 div ID 會傳遞至 WorkSpaces 應用程式內嵌建構函數。之後此就會用於注入 iframe 以供串流工作階段使用。若要建立 div，請加入下列程式碼：

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

## 初始化和設定 `AppStream.Embed` 界面物件
<a name="initialize-configure-embed-interface-object"></a>

若要在 JavaScript 中初始化 `AppStream.Embed` 界面物件，您必須使用串流 URL 和使用者介面組態的選項建立 `AppStream.Embed` 物件。這些選項，以及您建立的 div ID 都會儲存在名稱為 `appstreamOptions` 的物件中。

以下範例程式碼將說明如何初始化 `AppStream.Embed` 界面物件。

```
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);
```

在程式碼中，用您自己的值取代 *sessionURL* 和 *userInterfaceConfig*。

**注意**  
為 *userInterfaceConfig* 指定的值會隱藏整個 WorkSpaces 應用程式工具列。此值 (加入為範例) 為選擇性。

***sessionUrl***  
您使用 WorkSpaces 應用程式主控台、[CreateStreamingURL](https://docs.aws.amazon.com/appstream2/latest/APIReference/API_CreateStreamingURL.html) API 動作或 [create-streaming-url](https://docs.aws.amazon.com/cli/latest/reference/appstream/create-streaming-url.html) AWS CLI 命令建立的串流 URL。此參數有大小寫之分。  
**類型：**字串  
**必要**：是

***userInterfaceConfig***  
產生使用者界面元素初始狀態的組態。組態為金鑰值配對。  
金鑰 `AppStream.Embed.Options.HIDDEN_ELEMENTS`指定初始化內嵌 WorkSpaces 應用程式串流工作階段時最初隱藏的使用者介面物件。之後您可以使用 `getInterfaceState` 參數還原隱藏和顯示的物件。  
此值是常數陣列 (工具列按鈕)。如需可以使用的常數清單，請參閱 [使用 `HIDDEN_ELEMENTS`](constants-functions-events-embedded-sessions.md#constants-hidden-elements)。  
**類型**：對應 (*金鑰：**值*)  
**必要**：否

## WorkSpaces 應用程式使用者介面中的隱藏項目範例
<a name="examples-hiding-user-interface-items"></a>

本節中的範例示範如何在使用者的內嵌 WorkSpaces 應用程式串流工作階段期間隱藏 WorkSpaces 應用程式使用者介面中的項目。

**Topics**
+ [範例 1：隱藏整個 WorkSpaces 應用程式工具列](#example-hide-the-entire-tooolbar)
+ [範例 2：隱藏 WorkSpaces 應用程式工具列上的特定按鈕](#example-hide-a-specific-toolbar-button)
+ [範例 3：在 WorkSpaces 應用程式工具列上隱藏多個按鈕](#example-hide-multiple-toolbar-buttons)

### 範例 1：隱藏整個 WorkSpaces 應用程式工具列
<a name="example-hide-the-entire-tooolbar"></a>

若要防止使用者在內嵌串流工作階段期間存取 WorkSpaces 應用程式工具列上的任何按鈕，請使用 `AppStream.Embed.Elements.TOOLBAR` 常數。此常數可讓您隱藏所有 WorkSpaces 應用程式工具列按鈕。

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

### 範例 2：隱藏 WorkSpaces 應用程式工具列上的特定按鈕
<a name="example-hide-a-specific-toolbar-button"></a>

您可以顯示 WorkSpaces 應用程式工具列，同時防止使用者在內嵌串流工作階段期間存取特定工具列按鈕。若要執行此操作，請為您要隱藏的按鈕指定常數。以下程式碼會使用 `AppStream.Embed.Elements.FILES_BUTTON` 常數來隱藏 **My Files** (我的檔案) 按鈕。這可阻止使用者在嵌入串流工作階段期間存取永久性儲存選項。

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

### 範例 3：在 WorkSpaces 應用程式工具列上隱藏多個按鈕
<a name="example-hide-multiple-toolbar-buttons"></a>

您可以顯示 WorkSpaces 應用程式工具列，同時防止使用者在內嵌串流工作階段期間存取多個工具列按鈕。若要執行此操作，請指定您要隱藏的按鈕常數。以下程式碼會使用 `AppStream.Embed.Elements.END_SESSION_BUTTON` 和 `AppStream.Embed.Elements.FULLSCREEN_BUTTON` 常數來隱藏 **End Session (結束工作階段)** 和 **Fullscreen (全螢幕)** 按鈕。

**注意**  
以逗號分隔每個常數，前後沒有空格。

```
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]}
 };
```

# 內嵌 Amazon WorkSpaces 應用程式串流工作階段的常數、函數和事件
<a name="constants-functions-events-embedded-sessions"></a>

下列主題提供常數、函數和事件的參考資訊，您可以用來設定內嵌 WorkSpaces 應用程式串流工作階段。

**Topics**
+ [使用 `HIDDEN_ELEMENTS`](#constants-hidden-elements)
+ [`AppStream.Embed` 物件的功能](#functions-embed-object)
+ [內嵌 WorkSpaces 應用程式串流工作階段的事件](#events-embedded-streaming-sessions)
+ [新增事件接聽程式和結束內嵌 WorkSpaces 應用程式串流工作階段的範例](#examples-add-event-listeners-end-embedded-streaming-session)

初始化內嵌 WorkSpaces 應用程式串流工作階段時，下列 WorkSpaces 應用程式使用者介面元素可以傳入`HIDDEN_ELEMENTS`組態選項。

## 使用 `HIDDEN_ELEMENTS`
<a name="constants-hidden-elements"></a>

初始化內嵌 WorkSpaces 應用程式串流工作階段時，下列 WorkSpaces 應用程式使用者介面元素可以做為常數傳遞至`HIDDEN_ELEMENTS`組態選項。

```
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
```

以下三個元素可做為字串傳遞至 HIDDEN\$1ELEMENTS，而不是以常數傳遞。


| String | Description | 
| --- | --- | 
| 'adminCommandsButton' | 當您連線到 WorkSpaces 應用程式映像建置器時，WorkSpaces 應用程式工具列右上角會顯示 Admin Commands 按鈕。 WorkSpaces 將此字串傳遞至 HIDDEN\$1ELEMENTS 會隱藏 Admin Commands (管理命令) 按鈕。 | 
| 'softKeyboardButton' | 在已啟用觸控功能的裝置上的 WorkSpaces 應用程式串流工作階段期間，使用者可以點選 WorkSpaces 應用程式工具列上的鍵盤圖示，以顯示螢幕鍵盤。將此字串傳遞至 HIDDEN\$1ELEMENTS 會隱藏鍵盤圖示。 | 
| 'keyboardShortcutsButton' | 在已啟用觸控功能的裝置上的 WorkSpaces 應用程式串流工作階段期間，使用者可以點選 WorkSpaces 應用程式工具列上的 Fn 圖示，以顯示鍵盤快速鍵。將此字串傳遞至 HIDDEN\$1ELEMENTS 會隱藏 Fn 圖示。 | 

## `AppStream.Embed` 物件的功能
<a name="functions-embed-object"></a>

下表列出可在 `AppStream.Embed` 物件上執行的功能。


| 函式 | Description | 
| --- | --- | 
| AppStream.Embed(containerId:string, options:object) | AppStream.Embed 物件建構函數。此建構函數會初始化並與 AppStream.Embed 物件通訊，而且會使用 div 容器 ID。該 ID 會於注入 iframe 時使用，也會注入包含 appstreamOptions (sessionURL 和 HIDDEN\$1ELEMENTS) 組態選項的物件。 | 
| endSession() | 此函數會結束串流工作階段，但不會破壞 iframe。如果您指定一個重新導向 URL，iframe 會嘗試載入 URL。根據頁面的 CORS 標頭，URL 可能無法載入。 | 
| launchApp(appId:string) | 此函數會以程式設計的方式，使用影像建立期間指定的應用程式 ID 啟動應用程式。 | 
| launchAppSwitcher() | 此函數會將 AppSwitcher命令傳送至 WorkSpaces 應用程式入口網站。此操作會觸發執行個體上的 AppSwitcher 命令。 | 
| getSessionState() | 此函數會傳回 sessionStatus 的物件。如需詳細資訊，請參閱[內嵌 WorkSpaces 應用程式串流工作階段的事件](#events-embedded-streaming-sessions)。 | 
| getUserInterfaceState() | 此函數會傳回 `UserInterfaceState` 的物件。此物件包含以下項目的金鑰值配對： `sessionStatus`：狀態列舉 `sessionTerminationReason`：String `sessionDisconnectionReason`：String  如需詳細資訊，請參閱[內嵌 WorkSpaces 應用程式串流工作階段的事件](#events-embedded-streaming-sessions)。  | 
| addEventListener(name, callback) | 此函數會新增回呼功能，以在指定的活動觸發時呼叫。如需可觸發的事件清單，請參閱 [內嵌 WorkSpaces 應用程式串流工作階段的事件](#events-embedded-streaming-sessions)。 | 
| removeEventListener(name, callback) | 此函數會刪除指定事件的回呼。 | 
| destroy() | 此函數會刪除 iframe 並清理資源。此函數不會影響進行中的串流工作階段。 | 

## 內嵌 WorkSpaces 應用程式串流工作階段的事件
<a name="events-embedded-streaming-sessions"></a>

下表列出可在內嵌 WorkSpaces 應用程式串流工作階段期間觸發的事件。


| 事件 | 資料 | Description | 
| --- | --- | --- | 
| AppStream.Embed.Events.SESSION\$1STATE\$1CHANGE |  `sessionStatus`: `State enumeration` `sessionTerminationReason`：String `sessionDisconnectionReason`：String  | 此事件會在有任何工作階段狀態變更發生時觸發。此事件包含已變更的狀態的對應。若要擷取完整工作階段狀態，請使用 `getSessionState()` 函數。 以下是工作階段狀態： `AppStream.Embed.SessionStatus.Unknown`：工作階段尚未開始且未保留 `AppStream.Embed.SessionStatus.Reserved`：工作階段已保留，但尚未開始。 `AppStream.Embed.SessionStatus.Started`：使用者已連線至工作階段並開始串流。 `AppStream.Embed.SessionStatus Disconnected `：使用者已與工作階段中斷連線。 `AppStream.Embed.SessionStatus.Ended`：工作階段已標示為已結束或已過期。  | 
| AppStream.Embed.Events.SESSION\$1INTERFACE\$1STATE\$1CHANGE | `hiddenElements`: 字串陣列  `isFullscreen`：Boolean `isSoftKeyboardVisible`：Boolean  | 此事件會在有任何工作階段狀態變更發生時觸發。此事件包含已變更的狀態的對應。若要擷取完整工作階段狀態，請使用 getSessionState() 函數。 | 
| AppStream.Embed.Events.SESSION\$1ERROR | `errorCode`: 數字 `errorMessage`：String  | 工作階段期間發生任何錯誤都會觸發此事件。 | 

## 新增事件接聽程式和結束內嵌 WorkSpaces 應用程式串流工作階段的範例
<a name="examples-add-event-listeners-end-embedded-streaming-session"></a>

本節中的範例說明如何執行以下動作：
+ 新增內嵌 WorkSpaces 應用程式串流工作階段的事件接聽程式。
+ 以程式設計方式結束內嵌 WorkSpaces 應用程式串流工作階段。

### 範例 1：為內嵌 WorkSpaces 應用程式串流工作階段新增事件接聽程式
<a name="example-add-event-listeners"></a>

若要在嵌入串流工作階段期間變更工作階段狀態、變更工作階段介面狀態和新增工作階段錯誤的事件偵聽程式，請使用以下程式碼：

```
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);
```

在此範例中，`AppStream.Embed.Events.SESSION_STATE_CHANGE`、`AppStream.Embed.Events.SESSION_INTERFACE_STATE_CHANGE` 和 `AppStream.Embed.Events.SESSION_ERROR` 為事件名稱。

`updateSessionStateCallback`、`updateUserInterfaceStateCallback` 和 `errorCallback` 函數是您實作的函數。系統會將這些函數傳送至 `addEventListener` 函數，並在觸發事件時呼叫。

### 範例 2：以程式設計方式結束內嵌 WorkSpaces 應用程式串流工作階段
<a name="programmatically-end-embedded-streaming-session"></a>

若要結束內嵌 WorkSpaces 應用程式串流工作階段，請使用下列函數：

```
appstreamEmbed.endSession();
```