埋め込み AppStream 2.0 ストリーミングセッション - Amazon AppStream 2.0

埋め込み AppStream 2.0 ストリーミングセッション

ウェブサイト内に AppStream 2.0 ストリーミングセッションを埋め込むことで、ユーザー向けにカスタマイズした動的でインタラクティブなエクスペリエンスを作成できます。埋め込み AppStream 2.0 ストリーミングセッションにより、ユーザーはウェブサイトから直接、3D モデル、マップ、データセットを操作できます。たとえば、ユーザーはトレーニング手順や教材を表示しながら、AppStream 2.0 ストリーミングセッションを表示できます。

前提条件

ウェブサイトに AppStream 2.0 ストリーミングセッションを埋め込むには、以下のものが必要です。

  • AppStream 2.0 イメージ、フリート、およびスタックを含む、構成済みの AppStream 2.0 環境。リソースの作成方法の詳細については、AppStream 2.0 管理者ガイドの以下のトピック を参照してください。

  • ユーザー認証用のストリーミング URL。現在、SAML 2.0 および AppStream 2.0 ユーザープールは、埋め込み AppStream 2.0 ストリーミングセッションの認証方法としてサポートされていません。

  • オプションで、カスタムドメインを埋め込み AppStream 2.0 ストリーミングセッションに使用できます。カスタムドメインを使用すると、AppStream 2.0 の URL ではなく自社の URL をユーザーに表示できます。ユーザーがサードパーティー Cookie をブロックするウェブブラウザを使用している場合は、カスタムドメインが必要です。

    注記

    Amazon CloudFront を使用してカスタムドメインを設定できます。詳細については、Using Custom Domains with AppStream 2.0 を参照してください。

    カスタムドメインを使用する場合は、以下の操作を行う必要があります。

    • 同じドメインを使用するストリーミング URL を作成する。

    • 埋め込み AppStream 2.0 ストリーミングセッションをホストするウェブページのヘッダーに appstream-custom-url-domain を追加します。ヘッダー値には、リバースプロキシによってユーザーに表示されるドメインを使用します。詳細については、「カスタムドメインを使用するための設定要件」を参照してください。

推奨事項と使用上の考慮事項

埋め込み AppStream 2.0 ストリーミングセッションについて、以下の推奨事項と考慮事項があります。

  • 埋め込み AppStream 2.0 ストリーミングのユーザーエクスペリエンスを最大限に制御するには、有効期間が短い (5 秒ほどの) ストリーミング URL を設定することをお勧めします。いずれのユーザーもウェブページのコンテンツを調べて、そのソースを表示できます。ソースには、ドキュメントオブジェクトモデル (DOM) と iframe の src (ソース) URL が含まれています。ユーザーがその URL をコピーし、別のブラウザタブに貼り付けることができれば、埋め込みオプションを使用することなく、標準の AppStream 2.0 ポータルユーザーインターフェイスを使用して、セッションをストリーミングできます。

  • 埋め込み AppStream 2.0 ストリーミングセッションにカスタムドメインが使用されている場合、同時セッションはサポートされません。同時セッションは、ユーザーが同じウェブページまたは 2 つの異なるブラウザタブで 2 つの埋め込み AppStream 2.0 ストリーミングセッションを開始したときに発生します。1 人のユーザーが同時セッションを持つことはできませんが、複数のユーザーを持つことはできます。例えば、ユーザーがアプリケーションにログインし、アプリケーションが顧客に提供するストリーミング URL を生成し (請求では一意のユーザーとしてカウントされます)、顧客がストリーミング URL をロードすると、その顧客は指定されたプール内の appstream インスタンスに割り当てられます。

ステップ 1: 埋め込み AppStream 2.0 ストリーミングセッションのホストドメインを指定する

ウェブページに AppStream 2.0 ストリーミングセッションを埋め込むには、まずスタックを更新して、埋め込みストリーミングセッションをホストするドメインを指定します。これは、承認されたウェブサイトドメインのみが AppStream 2.0 ストリーミングセッションを埋め込むことができるようにするためのセキュリティ対策です。AppStream 2.0 は、指定したドメインを Content-Security-Policy (CSP) ヘッダーに追加します。詳細については、Mozilla MDN Web Docs ドキュメントの「コンテンツセキュリティポリシー (CSP)」を参照してください。

スタックを更新して埋め込みストリーミングセッションをホストするドメインを指定するには、次のいずれかの方法を使用します。

  • AppStream 2.0 コンソール

  • EmbedHostDomains API アクション

  • embed-host-domains AWS コマンドラインインターフェイス (AWS CLI) コマンド

AppStream 2.0 コンソールを使用してホストドメインを指定するには、以下の手順を実行します。

  1. AppStream 2.0 コンソール (https://console.aws.amazon.com/appstream2) を開きます。

  2. 左側のナビゲーションペインで [スタック] を選択し、必要なスタックを選択します。

  3. [Edit] を選択します。

  4. [Embed AppStream 2.0 (埋め込み AppStream 2.0) (オプション)] を展開します。

  5. [Host Domains (ホストドメイン)] で、有効なドメインを指定します。例: training.example.com

    注記

    埋め込みストリーミングセッションは、HTTPS (TCP ポート 443)経由でのみサポートされます。

  6. [Update] (更新) を選択します。

ステップ 2: ユーザー認証用のストリーミング URL を作成する

埋め込み AppStream 2.0 ストリーミングセッションのユーザーを認証するためのストリーミング URL を作成する必要があります。現在、SAML 2.0 とユーザープールは埋め込みストリーミングセッションではサポートされていません。ストリーミング URL を作成するには、以下のいずれかの方法を使用します。

カスタムドメインを使用するための設定要件

カスタムドメインを使用する目的が、会社のブランディングを適用することであっても、サードパーティー Cookie をブロックするブラウザで埋め込み AppStream 2.0 ストリーミングセッションが動作するようにすることであっても、設定要件は同じです。

サードパーティー Cookie をブロックするウェブブラウザの場合は、カスタムドメインが必要です。AppStream 2.0 は、ブラウザの Cookie を使用してストリーミングセッションを認証し、ユーザーは毎回ユーザー名とパスワードを入力することなく、アクティブなセッションに再接続できます。デフォルトでは、AppStream 2.0 ストリーミング URL にはドメインとして appstream.com が含まれます。ウェブサイトにストリーミングセッションを埋め込むと、appstream.com はサードパーティードメインとして扱われます。その結果、サードパーティー Cookie をデフォルトでブロックする最新のブラウザを使用していると、ストリーミングセッションがブロックされる場合があります。

このシナリオで埋め込み AppStream 2.0 ストリーミングセッションがブロックされないようにするには、以下の手順に従います。

  1. 埋め込み AppStream 2.0 ストリーミングセッションをホストするカスタムドメインを指定します。

    カスタムドメインを設定するときは、そのドメインが、AppStream 2.0 を埋め込む予定のウェブページのサブドメインであることを確認します。たとえば、スタックを更新してホストドメインとして training.example.com を指定する場合、埋め込みストリーミングセッション用に content.training.example.com というサブドメインを作成できます。

  2. この同じカスタムサブドメインを使用する埋め込み AppStream 2.0 ストリーミングセッション用のストリーミング URL を作成します。ストリーミング URL を作成するには、CreateStreamingURL API アクションまたは create-streaming-url AWS CLI コマンドを使用します。このシナリオでは、AppStream 2.0 コンソールを使用してストリーミング URL を作成することはできません。

    埋め込み AppStream 2.0 ストリーミングセッション用のストリーミング URL を作成するには、URL で appstream2.region.aws.amazon.com を独自のドメインに置き換えます。

    デフォルトでは、AppStream 2.0 ストリーミング URL は以下の形式になっています。

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

    サブドメインが content.training.example.com の場合、新しいストリーミング URL は以下の形式になります。

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

    カスタムドメインを作成する場合、そのドメインを埋め込み AppStream 2.0 ストリーミングセッションに使用できるのは、そのドメインが設定された AWS リージョンでのみです。複数のリージョンでカスタムドメインをサポートする予定の場合は、該当するリージョンごとにカスタムドメインを作成します。また、埋め込みストリーミングセッションは HTTPS (TCP ポート 443)経由でのみサポートされます。

  3. 埋め込みストリーミングセッションをホストするウェブページのヘッダーに appstream-custom-url-domain を追加します。ヘッダー値には、リバースプロキシによってユーザーに表示されるドメインを使用します。例:

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

    カスタムドメインを設定し、その同じドメインを指定するストリーミング URL を作成すると、その Cookie をファーストパーティー Cookie として保存できるようになります。Amazon CloudFront を使用してカスタムドメインを設定する方法については、Using Custom Domains with AppStream 2.0 を参照してください。

埋め込み AppStream 2.0 ストリーミングセッションのカスタムドメインを設定した後、ストリーミング URL がカスタムドメインにリダイレクトされない場合、またはカスタムドメインがユーザーに対して正しく表示されない場合は、次のトラブルシューティングのトピックをご参照ください。

手順 3: 埋め込み AppStream 2.0 ファイルをダウンロードする

埋め込み AppStream 2.0 ストリーミングセッションをホストするには、提供されている AppStream 2.0 API JavaScript ファイルをダウンロードして設定する必要があります。

  1. [Embedding AppStream 2.0 in Your Website (ウェブサイトへの AppStream 2.0 の埋め込み)] ウェブページで、ステップ 1 のリンクを選択して、AppStream 2.0 Embed Kit の .zip ファイル appstream_embed_<version>.zip をダウンロードします。

  2. .zip ファイルをダウンロードした場所に移動し、ファイルの内容を抽出します。

  3. ファイルの抽出された内容は appstream-embed という 1 つのフォルダで構成されます。COPYRIGHT.txt および THIRD_PARTY_NOTICES.txt ファイルに加えて、このフォルダには以下の 2 つのファイルが含まれています。

    • appstream-embed.js — 組み込み AppStream 2.0 API を提供します。この JavaScript ファイルには、埋め込み AppStream 2.0 ストリーミングセッションを設定および制御するための関数と API アクションが含まれています。

    • embed-sample.html — 埋め込み AppStream 2.0 API を使用して、ストリーミングセッションを初期化し、関数を呼び出し、イベントをリッスンする方法について説明されています。このサンプルファイルには、このトピックの情報を応用した開発者向けのユースケースの例が示されています。

ステップ 4. AppStream 2.0 と統合するためのウェブサイトを設定する

以下のセクションでは、埋め込み AppStream 2.0 ストリーミングセッションをホストするようにウェブページを設定する方法に関する情報を提供します。

appstream-embed JavaScript ファイルをインポートする

  1. AppStream 2.0 ストリーミングセッションを埋め込む予定のウェブページで、以下コードを追加して、appstream-embed.js ファイルをウェブページにインポートします。

    <script type="text/javascript" src="./appstream_embed.js"> </script>
  2. 次に、空のコンテナ div を作成します。設定した div の ID は AppStream 2.0 組み込みコンストラクタに渡されます。その後、ストリーミングセッションの iframe を注入するために使用されます。div を作成するには、以下のコードを追加します。

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

AppStream.Embed インターフェイスオブジェクトを初期化して設定する

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

コードで、sessionURLuserInterfaceConfig を独自の値に置き換えます。

注記

userInterfaceConfig で指定された値により、AppStream 2.0 ツールバー全体が非表示になります。この値は例として含まれており、オプションです。

sessionUrl

AppStream 2.0 コンソール、CreateStreamingURL API アクション、または create-streaming-url AWS CLI コマンドを使用して作成したストリーミング URL。このパラメータは大文字と小文字が区別されます。

型: 文字列

必須: はい

userInterfaceConfig

ユーザーインターフェイス要素の初期状態を生成する設定。この設定はキーと値のペアです。

キー AppStream.Embed.Options.HIDDEN_ELEMENTS は、埋め込み AppStream 2.0 ストリーミングセッションの初期化時に最初に非表示になるユーザーインターフェイスオブジェクトを指定します。後で、getInterfaceState パラメータを使用して、非表示オブジェクトと表示オブジェクトの両方を返すことができます。

値は、定数 (ツールバーボタン) の配列です。使用できる定数のリストについては、「HIDDEN_ELEMENTS での作業」を参照してください。

タイプ: マップ (key:Value)

必須: いいえ

AppStream 2.0 ユーザーインタフェイスで項目を非表示にする例

このセクションの例では、埋め込み AppStream 2.0 ストリーミングセッション中に AppStream 2.0 ユーザーインターフェイスの項目をユーザーに対して非表示にする方法を示します。

例 1: AppStream 2.0 ツールバー全体を非表示にする

埋め込みストリーミングセッション中にユーザーが AppStream 2.0 ツールバーのボタンにアクセスできないようにするには、AppStream.Embed.Elements.TOOLBAR 定数を使用します。この定数を使用すると、すべての AppStream 2.0 ツールバーボタンを非表示にすることができます。

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

例 2: AppStream 2.0 ツールバーの特定のボタンを非表示にする

埋め込みストリーミングセッション中にユーザーが AppStream 2.0 ツールバーを表示できるが、特定のツールバーボタンにアクセスできないようにします。そのためには、非表示にするボタンの定数を指定します。以下のコードは、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: AppStream 2.0 ツールバーの複数のボタンを非表示にする

埋め込みストリーミングセッション中にユーザーが AppStream 2.0 ツールバーを表示できるが、複数のツールバーボタンにアクセスできないようにします。そのためには、非表示にするボタンの定数を指定します。以下のコードは、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]} };

埋め込み AppStream 2.0 ストリーミングセッションの定数、関数、イベント

以下のトピックでは、埋め込み AppStream 2.0 ストリーミングセッションの設定に使用できる定数、関数、イベントのリファレンス情報を提供します。

以下の AppStream 2.0 ユーザーインターフェイス要素は、埋め込み AppStream 2.0 ストリーミングセッションの初期化時に HIDDEN_ELEMENTS 設定オプションに渡すことができます。

HIDDEN_ELEMENTS での作業

以下の AppStream 2.0 ユーザーインターフェイス要素は、埋め込み AppStream 2.0 ストリーミングセッションの初期化時に 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

次の 3 つの要素は、定数としてではなく、文字列として HIDDEN_ELEMENTS に渡すことができます。

文字列 説明
'adminCommandsButton' AppStream 2.0 Image Builder に接続すると、AppStream 2.0 ツールバーの右上隅に [Admin Commands (管理者コマンド)] ボタンが表示されます。この文字列を HIDDEN_ELEMENTS に渡すと、[Admin Commands] ボタンが非表示になります。
'softKeyboardButton' ユーザーは、タッチ対応デバイスでの AppStream 2.0 ストリーミングセッション中に、AppStream 2.0 ツールバーのキーボードアイコンをタップしてオンスクリーンキーボードを表示できます。この文字列を HIDDEN_ELEMENTS に渡すと、キーボードアイコンが非表示になります。
'keyboardShortcutsButton' タッチ対応デバイスの AppStream 2.0 ストリーミングセッション中、ユーザーは AppStream 2.0 ツールバーの [Fn] アイコンをタップしてキーボードショートカットを表示できます。この文字列を HIDDEN_ELEMENTS に渡すと、Fn アイコンが非表示になります。

AppStream.Embed オブジェクトの関数

以下の表では、AppStream.Embed オブジェクトで実行できる関数を示しています。

関数 説明
AppStream.Embed(containerId:string, options:object) AppStream.Embed オブジェクトコンストラクタ。このコンストラクタは AppStream.Embed オブジェクトを初期化し、このオブジェクトとやり取りします。また、div コンテナ ID を使用します。ID は iframe を注入するために使用されます。さらに、appstreamOptions の設定オプション (sessionURL および HIDDEN_ELEMENTS) を含むオブジェクトを注入します。
endSession() この関数は、ストリーミングセッションを終了しますが、iframe は破棄しません。リダイレクト URL を指定している場合、iframe では URL のロードが試みられます。ページの CORS ヘッダーによっては、URL がロードされない場合があります。
launchApp(appId:string) この関数は、イメージの作成中に指定されたアプリケーション ID に対応するアプリケーションをプログラムで起動します。
launchAppSwitcher() この関数は、AppSwitcher コマンドを AppStream 2.0 ポータルに送信します。これにより、インスタンスに対して AppSwitcher コマンドがトリガーされます。
getSessionState() この関数は、sessionStatus のオブジェクトを返します。詳細については、「埋め込み AppStream 2.0 ストリーミングセッションのイベント」を参照してください。
getUserInterfaceState()

この関数は、UserInterfaceState のオブジェクトを返します。オブジェクトには、以下のキーと値のペアが含まれます。

sessionStatus: 状態の列挙

sessionTerminationReason: 文字列

sessionDisconnectionReason: 文字列

詳細については、「埋め込み AppStream 2.0 ストリーミングセッションのイベント」を参照してください。

addEventListener(name, callback) この関数は、指定されたイベントのトリガー時に呼び出すコールバック関数を追加します。トリガーできるイベントのリストについては、「埋め込み AppStream 2.0 ストリーミングセッションのイベント」を参照してください。
removeEventListener(name, callback) この関数は、指定されたイベントのコールバックを削除します。
destroy() この関数は、iframe を削除し、リソースをクリーンアップします。この関数は、進行中のストリーミングセッションには影響しません。

埋め込み AppStream 2.0 ストリーミングセッションのイベント

以下の表では、埋め込み AppStream 2.0 ストリーミングセッション中にトリガーできるイベントを示しています。

イベント データ 説明
AppStream.Embed.Events.SESSION_STATE_CHANGE

sessionStatus: State enumeration

sessionTerminationReason: 文字列

sessionDisconnectionReason: 文字列

このイベントは、セッション状態の変更が生じたときにトリガーされます。このイベントには、変更された状態のマップが含まれます。完全なセッション状態を取得するには、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_INTERFACE_STATE_CHANGE

hiddenElements: 文字列の配列

isFullscreen: ブール値

isSoftKeyboardVisible: ブール値

このイベントは、セッション状態の変更が生じたときにトリガーされます。このイベントには、変更された状態のマップが含まれます。完全なセッション状態を取得するには、getSessionState() 関数を使用します。
AppStream.Embed.Events.SESSION_ERROR

errorCode: 番号

errorMessage: 文字列

このイベントは、セッション中にエラーが発生するとトリガーされます。

イベントリスナーの追加例と埋め込み AppStream 2.0 ストリーミングセッションの終了例

このセクションの例では、次の操作を行う方法を示します。

  • 埋め込み AppStream 2.0 ストリーミングセッションのイベントリスナーを追加する。

  • 埋め込み AppStream 2.0 ストリーミングセッションをプログラムで終了する。

例 1: 埋め込み AppStream 2.0 ストリーミングセッションのイベントリスナーを追加する

埋め込みストリーミングセッション中のセッションの状態の変更、セッションインターフェイスの状態の変更、セッションエラーに対するイベントリスナーを追加するには、以下のコードを使用します。

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_CHANGEAppStream.Embed.Events.SESSION_INTERFACE_STATE_CHANGEAppStream.Embed.Events.SESSION_ERROR はイベント名です。

updateSessionStateCallbackupdateUserInterfaceStateCallbackerrorCallback は実装する関数です。これらの関数は addEventListener 関数に渡され、イベントがトリガーされると呼び出されます。

例 2: 埋め込み AppStream 2.0 ストリーミングセッションをプログラムで終了する

埋め込み AppStream 2.0 ストリーミングセッションを終了するには、以下の関数を使用します。

appstreamEmbed.endSession();