Incorporar sessões de streaming do AppStream 2.0

Você pode criar uma experiência dinâmica, interativa e personalizada para os usuários, incorporando uma sessão de streaming do AppStream 2.0 ao seu site. As sessões de streaming incorporadas do AppStream 2.0 permitem que os usuários interajam com modelos 3D, mapas e conjuntos de dados diretamente do seu site. Por exemplo, os usuários podem visualizar instruções de treinamento ou materiais educacionais ao lado da sessão de streaming do AppStream 2.0.

Pré-requisitos

Para incorporar uma sessão de streaming do AppStream 2.0 a um site, é necessário:

• Um ambiente configurado do AppStream 2.0 que inclua uma imagem, frota e pilha do AppStream 2.0. Para obter informações sobre como criar esses recursos, consulte os seguintes tópicos no Guia de administração do AppStream 2.0:

  • Tutorial: Crie uma imagem AppStream 2.0 personalizada usando o console AppStream 2.0 ou Criar sua imagem do AppStream 2.0 de forma programática usando as operações da CLI do Assistente de Imagens

  • Criar uma frota

  • Criar um stack

• Um URL de streaming para autenticação de usuário. O SAML 2.0 e os grupos de usuários do AppStream 2.0 ainda não são compatíveis como métodos de autenticação para sessões de streaming incorporadas do AppStream 2.0.

• Você também pode usar domínios personalizados para sessões de streaming incorporadas do AppStream 2.0. Você pode usar domínios personalizados para que o URL de sua empresa seja exibido aos usuários em vez de um URL do AppStream 2.0. Domínios personalizados são necessários se seus usuários tiverem navegadores da Web que bloqueiam cookies de terceiros.

  nota

  Você pode configurar domínios personalizados usando o Amazon CloudFront. Para obter informações, consulte Using Custom Domains with AppStream 2.0.

  Ao usar um domínio personalizado, você deve:

  • Criar um URL de streaming que use o mesmo domínio.

  • Adicione appstream-custom-url-domain ao cabeçalho da página da web que hospedará as sessões de streaming incorporadas do AppStream 2.0. Para o valor de cabeçalho, use o domínio que o proxy reverso exibe para os usuários. Para obter mais informações, consulte Requisitos de configuração para uso de domínios personalizados.

Recomendações e considerações de uso

Considere as seguintes recomendações e observações sobre o uso para sessões de streaming incorporadas do AppStream 2.0.

• Para manter o controle máximo sobre a experiência de streaming incorporado do AppStream 2.0 para os usuários, recomendamos que você configure URLs de streaming de curta duração que durem aproximadamente 5 segundos. Qualquer usuário pode inspecionar o conteúdo de uma página da Web e visualizar sua fonte. Isso inclui o modelo de objeto do documento (DOM) e o URL de src (origem) do iframe. Se o URL ainda for válido quando um usuário o copiar, esse usuário poderá colar o URL em uma guia separada do navegador e fazer streaming da sessão com a interface de usuário padrão do portal do AppStream 2.0, sem as opções de incorporação.

• As sessões simultâneas não são compatíveis quando domínios personalizados são usados para sessões de streaming incorporadas do AppStream 2.0. As sessões simultâneas ocorrem quando os usuários iniciam duas sessões de streaming incorporadas do AppStream 2.0 na mesma página da web ou em duas guias de navegador diferentes. Não é possível ter um único usuário com sessões simultâneas, mas é possível ter vários usuários. Por exemplo, um usuário faz login em sua aplicação, o que gera um URL de streaming para fornecer ao cliente (isso conta como um usuário exclusivo para fins de cobrança). Depois, um cliente carrega o URL de streaming e é atribuído a uma instância appstream dentro do grupo especificado.

Etapa 1: Especificar um domínio de host para sessões de streaming incorporadas do AppStream 2.0

Para incorporar uma sessão de streaming do AppStream 2.0 em uma página da web, atualize sua pilha para especificar o domínio que hospedará a sessão de streaming incorporada. Essa é uma medida de segurança para garantir que apenas domínios de sites autorizados possam incorporar sessões de streaming do AppStream 2.0. O AppStream 2.0 adiciona o domínio ou os domínios que você especifica ao cabeçalho Content-Security-Policy (CSP). Para obter mais informações, consulte Política de Segurança de Conteúdo (CSP) na documentação MDN Web Docs do Mozilla.

Para atualizar sua pilha para especificar o domínio para hospedar a sessão de streaming incorporada, use qualquer um dos seguintes métodos:

• O console do AppStream 2.0

• A ação de API EmbedHostDomains.

• O comando embed-host-domains da AWS Command Line Interface (AWS CLI)

Para especificar um domínio de host usando o console do AppStream 2.0, execute as etapas a seguir.

1. Abra o console do AppStream 2.0 em https://console.aws.amazon.com/appstream2.

2. No painel de navegação à esquerda, selecione Stacks (Pilhas) e selecione a pilha desejada.

3. Escolha Editar.

4. Expanda a opção Incorporar o AppStream 2.0 (opcional).

5. Em Host Domains (Domínios de Host), especifique um domínio válido. Por exemplo: training.example.com.

   nota

   As sessões de streaming incorporadas só são permitidas via HTTPS [porta TCP 443].

6. Escolha Atualizar.

Etapa 2: Criar um URL de streaming para autenticação de usuário

Você deve criar um URL de streaming para autenticar usuários em sessões de streaming incorporadas do AppStream 2.0. No momento, o SAML 2.0 e os grupos de usuários não são compatíveis para sessões de streaming incorporadas. Para criar um URL de streaming, use um dos seguintes métodos:

• Console do AppStream 2.0

• A ação da API CreateStreamingURL

• O comando create-streaming-url da AWS CLI

Requisitos de configuração para uso de domínios personalizados

Não importa se você usa domínios personalizados para aplicar a marca da sua empresa ou para garantir que as sessões de streaming incorporadas do AppStream 2.0 funcionem com navegadores que bloqueiam cookies de terceiros, os requisitos de configuração são os mesmos.

Os domínios personalizados são necessários para navegadores da web que bloqueiam cookies de terceiros. O AppStream 2.0 usa cookies do navegador para autenticar sessões de streaming e permite que os usuários se reconectem a uma sessão ativa sem que precisem fornecer as credenciais de login todas as vezes. Por padrão, os URLs de streaming do AppStream 2.0 incluem appstream.com como domínio. Quando você incorpora uma sessão de streaming ao seu site, appstream.com é tratado como domínio de terceiros. Como resultado, as sessões de streaming podem ser bloqueadas quando navegadores modernos são usados para bloquear cookies de terceiros por padrão.

Para evitar que sessões de streaming incorporadas do AppStream 2.0 sejam bloqueadas nesse cenário, siga estas etapas:

1. Especifique um domínio personalizado para hospedar as sessões de streaming incorporadas do AppStream 2.0.

   Ao configurar um domínio personalizado, verifique se o domínio é um subdomínio da página da web na qual planeja incorporar o AppStream 2.0. Por exemplo, se atualizar sua pilha para especificar training.example.com como o domínio do host, você poderá criar um subdomínio chamado content.training.example.com para suas sessões de streaming incorporadas.

2. Crie um URL de streaming para sessões de streaming incorporadas do AppStream 2.0 que use o mesmo subdomínio personalizado. Para criar o URL de streaming, use a ação de API CreateStreamingURL ou o comando create-streaming-url da AWS CLI. Você não pode usar o console do AppStream 2.0 para criar um URL de streaming nesse cenário.

   Para criar um URL de streaming para sessões de streaming incorporadas do AppStream 2.0, no URL, substitua appstream2.região.aws.amazon.com por seu próprio domínio.

   Por padrão, os URLs de streaming do AppStream 2.0 são formatados da seguinte forma:

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

   Se o seu subdomínio for content.training.example.com, o novo URL de streaming seguirá este formato:

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

   nota

   Ao criar um domínio personalizado, você só poderá usar o domínio para sessões de streaming incorporadas do AppStream 2.0 na região da AWS para a qual ele foi configurado. Se você planeja oferecer suporte a domínios personalizados em várias regiões, crie um domínio personalizado para cada região aplicável. Além disso, as sessões de streaming incorporadas só são permitidas via HTTPS [porta TCP 443].

3. Adicione appstream-custom-url-domain ao cabeçalho da página da Web que hospedará as sessões de streaming incorporadas. Para o valor de cabeçalho, use o domínio que o proxy reverso exibe para os usuários. Por exemplo:

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

   Definir um domínio personalizado e criar um URL de streaming que especifique o mesmo domínio permite que os cookies sejam salvos como cookies primários. Para obter informações sobre como configurar domínios personalizados usando o Amazon CloudFront, consulte Using Custom Domains with AppStream 2.0.

Depois de configurar um domínio personalizado para as sessões de streaming incorporadas do AppStream 2.0, se os URLs de streaming não redirecionarem para seu domínio personalizado ou se esse domínio não for exibido corretamente para os usuários, consulte os seguintes tópicos de solução de problemas:

• Eu configurei um domínio personalizado para minhas sessões de streaming AppStream 2.0 incorporadas, mas meu streaming AppStream 2.0 URLs não está redirecionando para meu domínio personalizado.

Etapa 3: Fazer download dos arquivos incorporados do AppStream 2.0

Para hospedar sessões de streaming incorporadas do AppStream 2.0, você deve fazer download e configurar o arquivo JavaScript de API do AppStream 2.0 fornecido.

1. Na página da web Embedding AppStream 2.0 in Your Website, escolha o link na etapa 1 para fazer download do arquivo .zip do kit de incorporação do AppStream 2.0, appstream_embed_<versão>.zip.

2. Navegue até o local onde você baixou o arquivo .zip e extraia o conteúdo do arquivo.

3. O conteúdo extraído do arquivo contém uma pasta, appstream-embed. Além dos arquivos Copyright.txt e Third_Party_Notices.txt , essa pasta contém os dois arquivos a seguir:

   • appstream-embed.js: fornece a API incorporada do AppStream 2.0. Esse arquivo JavaScript inclui as funções e as ações de API para configurar e controlar a sessão de streaming incorporada do AppStream 2.0.

   • embed-sample.html: descreve como usar a API incorporada do AppStream 2.0 para inicializar uma sessão de streaming, chamar funções e receber eventos. Este arquivo de exemplo expande as informações neste tópico para fornecer um exemplo de caso de uso para desenvolvedores.

Etapa 4. Configurar o site para a integração com o AppStream 2.0

As seções a seguir fornecem informações sobre como configurar uma página da web para hospedar sessões de streaming incorporadas do AppStream 2.0.

Índice

• Importar o arquivo JavaScript incorporado ao appstream
• Inicializar e configurar o objeto de interface AppStream.Embed
• Exemplos para ocultar itens na interface de usuário do AppStream 2.0

Importar o arquivo JavaScript incorporado ao appstream

1. Na página da web onde você pretende incorporar a sessão de streaming do AppStream 2.0, importe o arquivo appstream-embed.js para a página da web adicionando o seguinte código:

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

2. Em seguida, crie um div de contêiner vazio. O ID do div que você define é enviado ao construtor incorporado do AppStream 2.0. Ele é usado, então, para injetar um iframe à sessão de streaming. Para criar o div, adicione o seguinte código:

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

Inicializar e configurar o objeto de interface AppStream.Embed

Para inicializar o objeto de interface AppStream.Embed em JavaScript, você deve adicionar o código que cria um objeto AppStream.Embed com opções para o URL de streaming e a configuração de interface do usuário. Essas opções e o ID do div que você criou são armazenados em um objeto chamado appstreamOptions.

O código de exemplo a seguir mostra como inicializar o objeto de interface 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);

No código, substitua SessionURL e UserInterfaceConfig por seus próprios valores.

nota

O valor especificado para userInterfaceConfig oculta toda a barra de ferramentas do AppStream 2.0. Esse valor, que é incluído como exemplo, é opcional.

sessionUrl

O URL de streaming que você criou usando o console do AppStream 2.0, a ação de API CreateStreamingURL ou o comando create-streaming-url da AWS CLI. Esse parâmetro diferencia maiúsculas de minúsculas.

Tipo: string

Obrigatório: Sim

userInterfaceConfig

A configuração que gera o estado inicial dos elementos da interface do usuário. A configuração é um par de chave/valor.

A chave AppStream.Embed.Options.HIDDEN_ELEMENTS especifica os objetos da interface de usuário que ficam ocultos quando a sessão de streaming incorporada do AppStream 2.0 é inicializada. Posteriormente, você pode retornar objetos ocultos e visíveis usando o parâmetro getInterfaceState.

O valor é uma matriz de constantes (botões da barra de ferramentas). Para obter uma lista de constantes que podem ser usadas, consulte Trabalhar com HIDDEN_ELEMENTS.

Tipo: Mapa (chave:valor)

Obrigatório: não

Exemplos para ocultar itens na interface de usuário do AppStream 2.0

Os exemplos desta seção mostram como ocultar itens da interface de usuário do AppStream 2.0 durante as sessões de streaming incorporadas do AppStream 2.0.

Exemplos

• Exemplo 1: ocultar toda a barra de ferramentas do AppStream 2.0
• Exemplo 2: ocultar um botão específico na barra de ferramentas do AppStream 2.0
• Exemplo 3: ocultar vários botões na barra de ferramentas do AppStream 2.0

Exemplo 1: ocultar toda a barra de ferramentas do AppStream 2.0

Para evitar que os usuários acessem os botões na barra de ferramentas do AppStream 2.0 durante sessões de streaming incorporadas, use a constante AppStream.Embed.Elements.TOOLBAR. Essa constante permite ocultar todos os botões da barra de ferramentas do 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]}
 };

Exemplo 2: ocultar um botão específico na barra de ferramentas do AppStream 2.0

Você pode exibir a barra de ferramentas do AppStream 2.0 e, ao mesmo tempo, impedir que os usuários acessem um botão específico da barra de ferramentas durante sessões de streaming incorporadas. Para fazer isso, especifique a constante para o botão que você deseja ocultar. O código a seguir usa a constante AppStream.Embed.Elements.FILES_BUTTON para ocultar o botão My Files (Meus arquivos) . Isso impede que os usuários acessem opções de armazenamento persistente durante as sessões de streaming incorporadas.

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

Exemplo 3: ocultar vários botões na barra de ferramentas do AppStream 2.0

Você pode exibir a barra de ferramentas do AppStream 2.0 e, ao mesmo tempo, impedir que os usuários acessem mais de um botão da barra de ferramentas durante sessões de streaming incorporadas. Para fazer isso, especifique as constantes para os botões que você deseja ocultar. O código a seguir usa as constantes AppStream.Embed.Elements.END_SESSION_BUTTON e AppStream.Embed.Elements.FULLSCREEN_BUTTON para ocultar os botões End Session (Encerrar sessão) e Fullscreen (Modo de tela inteira).

nota

Separe cada constante com uma vírgula, sem espaço anterior ou posterior.

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

Constantes, funções e eventos para sessões de streaming incorporadas do AppStream 2.0

Os tópicos a seguir fornecem informações de referência para constantes, funções e eventos que você pode usar para configurar sessões de streaming incorporadas do AppStream 2.0.

Índice

• Trabalhar com HIDDEN_ELEMENTS
• Funções para o objeto AppStream.Embed
• Eventos para sessões de streaming incorporadas do AppStream 2.0
• Exemplos de como adicionar receptores de eventos e encerrar uma sessão de streaming incorporada do AppStream 2.0

Os elementos a seguir da interface de usuário do AppStream 2.0 podem ser enviados para a opção de configuração HIDDEN_ELEMENTS quando uma sessão de streaming incorporada do AppStream 2.0 é inicializada.

Trabalhar com HIDDEN_ELEMENTS

Os elementos a seguir da interface de usuário do AppStream 2.0 podem ser enviados como constantes para a opção de configuração HIDDEN_ELEMENTS quando uma sessão de streaming incorporada do AppStream 2.0 é inicializada.

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

Os três elementos a seguir podem ser passados como strings para HIDDEN_ELEMENTS, em vez de como constantes.

Segmento	Descrição
'adminCommandsButton'	Quando você tem um construtor de imagens do AppStream 2.0 conectado, o botão Comandos de administrador é exibido no canto superior direito da barra de ferramentas do AppStream 2.0. Passar essa string para HIDDEN_ELEMENTS oculta o botão Admin Commands (Comandos de administrador).
'softKeyboardButton'	Durante sessões de streaming do AppStream 2.0 em dispositivos habilitados para toque, os usuários podem tocar no ícone do teclado na barra de ferramentas do AppStream 2.0 para exibir o teclado na tela. Passar essa string para HIDDEN_ELEMENTS oculta o ícone do teclado.
'keyboardShortcutsButton'	Durante sessões de streaming do AppStream 2.0 em dispositivos habilitados para toque, os usuários podem tocar no ícone Fn na barra de ferramentas do AppStream 2.0 para exibir os atalhos de teclado. Passar essa string para HIDDEN_ELEMENTS oculta o ícone Fn.

Funções para o objeto AppStream.Embed

A tabela a seguir lista as funções que podem ser executadas no objeto AppStream.Embed.

Função	Descrição
AppStream.Embed(containerId:string, options:object)	O construtor do objeto AppStream.Embed. Este construtor inicializa e se comunica com o objeto AppStream.Embed e usa um ID de contêiner div. O ID é usado para injetar o iframe. Ele também injeta um objeto que inclui as opções de configuração para appstreamOptions (SessionURL e HIDDEN_ELEMENTS).
endSession()	Essa função encerra a sessão de streaming, mas não destrói o iframe. Se você especificar um URL de redirecionamento, o iframe tentará carregar o URL. Dependendo dos cabeçalhos CORS da página, o URL pode não ser carregado.
launchApp(appId:string)	Esta função inicia programaticamente um aplicativo com o ID do aplicativo especificado durante a criação da imagem.
launchAppSwitcher()	Essa função envia o comando AppSwitcher ao portal do AppStream 2.0. Isso aciona o comando AppSwitcher na instância.
getSessionState()	Essa função retorna um objeto para sessionStatus. Para obter mais informações, consulte Eventos para sessões de streaming incorporadas do AppStream 2.0.
getUserInterfaceState()	Essa função retorna um objeto para UserInterfaceState. O objeto contém os pares de chave/valor para o seguinte: sessionStatus: enumeração de estado sessionTerminationReason: string sessionDisconnectionReason: string Para obter mais informações, consulte Eventos para sessões de streaming incorporadas do AppStream 2.0.
addEventListener(name, callback)	Essa função adiciona uma função de retorno de chamada para quando o evento especificado é acionado. Para obter uma lista dos eventos que podem ser acionados, consulte Eventos para sessões de streaming incorporadas do AppStream 2.0.
removeEventListener(name, callback)	Essa função remove o retorno de chamada para os eventos especificados.
destroy()	Essa função exclui o iframe e limpa os recursos. Essa função não afeta as sessões de streaming que estão em andamento.

Eventos para sessões de streaming incorporadas do AppStream 2.0

A tabela a seguir lista os eventos que podem ser acionados durante sessões de streaming incorporadas do AppStream 2.0.

Evento	Dados	Descrição
AppStream.Embed.Events.SESSION_STATE_CHANGE	sessionStatus: State enumeration sessionTerminationReason: string sessionDisconnectionReason: string	Esse evento é acionado quando ocorre qualquer alteração no estado da sessão. O evento inclui um mapa dos estados que foram alterados. Para recuperar o estado da sessão completa, use a função getSessionState(). Veja a seguir os estados da sessão: AppStream.Embed.SessionStatus.Unknown: a sessão não foi iniciada e não está reservada AppStream.Embed.SessionStatus.Reserved: a sessão está reservada, mas não foi iniciada. AppStream.Embed.SessionStatus.Started: o usuário se conectou à sessão e iniciou o streaming. AppStream.Embed.SessionStatus Disconnected : o usuário se desconectou da sessão. AppStream.Embed.SessionStatus.Ended: a sessão foi marcada como encerrada ou expirada.
AppStream.Embed.Events.SESSION_INTERFACE_STATE_CHANGE	hiddenElements: matriz de strings isFullscreen: booliano isSoftKeyboardVisible: booliano	Esse evento é acionado quando ocorre qualquer alteração no estado da sessão. O evento inclui um mapa dos estados que foram alterados. Para recuperar o estado da sessão completa, use a função getSessionState().
AppStream.Embed.Events.SESSION_ERROR	errorCode: número errorMessage: string	Esse evento é acionado quando ocorrem erros durante uma sessão.

Exemplos de como adicionar receptores de eventos e encerrar uma sessão de streaming incorporada do AppStream 2.0

Os exemplos nesta seção mostram como fazer o seguinte:

• Adicionar receptores de eventos para sessões de streaming incorporadas do AppStream 2.0.

• Encerrar programaticamente uma sessão de streaming incorporada do AppStream 2.0.

Exemplo 1: adicionar receptores de eventos para sessões de streaming incorporadas do AppStream 2.0

Para adicionar listeners de eventos para alterações de estado de sessão, alterações de estado da interface da sessão e erros de sessão durante as sessões de streaming incorporadas, use o seguinte código:

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

Neste exemplo, AppStream.Embed.Events.SESSION_STATE_CHANGE, AppStream.Embed.Events.SESSION_INTERFACE_STATE_CHANGE e AppStream.Embed.Events.SESSION_ERROR são nomes de eventos.

As funções updateSessionStateCallback, updateUserInterfaceStateCallback e errorCallback são as que você implementa. Essas funções são passadas para a função addEventListener e chamadas quando um evento é acionado.

Exemplo 2: encerrar programaticamente uma sessão de streaming incorporada do AppStream 2.0

Para encerrar sessões de streaming incorporadas do AppStream 2.0, use a seguinte função:

appstreamEmbed.endSession();