Abrir conteúdo no Stageview

  • Artigo

O Microsoft Teams fornece vários métodos para abrir o conteúdo do aplicativo em experiências de tela imersivas. A visão de estágio permite que os usuários adotem várias tarefas dentro do Teams, por exemplo, você pode abrir o conteúdo do aplicativo em uma nova janela do Teams com um chat específico no painel lateral. O Stageview foi projetado para:

  • Facilitar a multitarefa no Teams.
  • Suporte à colaboração em várias janelas do Teams.
  • Concentre-se em tarefas específicas em uma grande experiência modal.

Observação

O artigo é baseado na versão 2.0.x da biblioteca de clientes do Teams JavaScript (TeamsJS). Se você estiver usando uma versão anterior, consulte TeamsJS para obter diretrizes entre as versões mais recentes e anteriores.

Tipos de Stageview

Com base na interface do usuário e na funcionalidade, o Stageview oferece três maneiras de abrir o conteúdo do aplicativo:

Visão de estágio colaborativa

O Stageview Colaborativo permite cenários multitarefa para o conteúdo do aplicativo no Teams. Os usuários podem abrir e exibir o conteúdo do aplicativo dentro de uma nova janela do Teams enquanto acompanham uma conversa de painel lateral. Essa exibição permite envolvimento e colaboração de conteúdo significativos dentro da mesma janela.

Melhor uso: quando o conteúdo é aberto de uma conversa, como chat, canal ou guia de canal.

A captura de tela mostra a Visão de Estágio Colaborativa no Teams.

Janela multivisor de visão de estágio

O Stageview Multi-window é útil para cenários que exigem que um usuário multitarefa no Teams sem a necessidade de colaboração. Essa exibição abre o conteúdo do aplicativo em uma nova janela do Teams sem uma conversa de painel lateral permitindo que os usuários se concentrem em sua tarefa.

Melhor uso: quando o conteúdo é aberto de uma superfície nãoconversacional, como um aplicativo pessoal.

A captura de tela mostra o Stageview Multi-window no Teams.

Stageview Modal

Stageview Modal é um componente de interface do usuário de tela inteira usado para renderizar o conteúdo do aplicativo dentro da janela main do Teams. Essa exibição fornece aos usuários uma experiência focada para se envolver com o conteúdo do aplicativo. Stageview Modal é útil para exibir conteúdo avançado que não exige que um usuário faça várias tarefas. É a exibição padrão quando não há suporte para o Stageview Colaborativo e o Stageview Multi-window.

Observação

O cliente Web do Teams dá suporte apenas ao Stageview Modal.

A captura de tela mostra o Modal stageview no Teams.

Invocar Stageview

Você pode invocar Stageview no Teams por meio de um dos métodos a seguir e configurar a resposta de Stageview esperada. A tabela a seguir fornece a resposta padrão e definida para cada método de invocação do Stageview:

Método Invoke Resposta padrão Resposta definida
Cartão Adaptável Abre no Collaborative Stageview. Abre no Stageview Modal, se não houver suporte para o Stageview Colaborativo ou o Stageview Multi-window.
API stageView Abre no Collaborative Stageview. Abre no respectivo Stageview com base no openModedefinido.
Link profundo Abre no Collaborative Stageview. Abre no respectivo Stageview com base no openModedefinido.

propriedade openMode

openMode é uma propriedade na interface StageViewParams. A openMode propriedade é opcional e pode ser definida em uma API stageView ou em um link profundo para determinar o tipo de resposta stageview. A openMode propriedade tem os seguintes três valores:

  • popoutWithChat
  • popout
  • modal

A tabela a seguir fornece a resposta Stageview dos openMode valores:

Input Resposta
openMode definido como popoutWithChat Abre no Collaborative Stageview com uma conversa de painel lateral associada.
openMode definido como popout Abre no Stageview Multi-window sem uma conversa de painel lateral.
openMode definido como modal Abre no Stageview Modal.

Quando openMode não é definido, o conteúdo é aberto por padrão no Collaborative Stageview com uma conversa de painel lateral associada. A hierarquia de fallback para uma resposta stageview é popoutWithChatmodal>popout>.

Observação

  • Os openMode valores são sensíveis a casos. Se você não usar o invólucro correto, o conteúdo será aberto no Stageview Modal.
  • Quando não há suporte para a experiência pop-out, por exemplo, em um cliente Web do Teams, o conteúdo é aberto no Stageview Modal mesmo quando a openMode propriedade é definida.

Invocar visão de fase colaborativa do cartão adaptável

A visão de estágio colaborativa de um Cartão Adaptável permite que os usuários se envolvam com seu conteúdo enquanto continuam o fluxo de conversa. Se o Stageview Colaborativo for invocado de um JSON de Cartão Adaptável no cliente Web do Teams, ele será aberto em um Modal stageview.

As etapas a seguir ajudam você a entender como o Stageview Colaborativo é invocado de um Cartão Adaptável:

  1. Quando o usuário compartilha uma URL de um conteúdo de aplicativo em um chat do Teams, o bot recebe uma composeExtensions/queryLink solicitação de invocação. O bot retorna um Cartão Adaptável com o tipo tab/tabInfoAction.

  2. Depois que o usuário seleciona o botão de ação no Cartão Adaptável, o Stageview Colaborativo é aberto com base no conteúdo no Cartão Adaptável.

A representação gráfica mostra como a resposta do Stageview Colaborativo do Cartão Adaptável.

O seguinte código JSON é um exemplo para criar um botão de ação em um Cartão Adaptável:

{
  "type": "Action.Submit",
  "title": "Open",
  "data": {
    "msteams": {
      "type": "invoke",
      "value": {
        "type": "tab/tabInfoAction",
        "tabInfo": {
          "contentUrl": "contentUrl",
          "websiteUrl": "websiteUrl",
          "name": "Sales Report",
          "entityId": "entityId"
        }
      }
    }
  }
}

Práticas recomendadas para criar um Cartão Adaptável

  • A URL de conteúdo deve estar dentro da lista de no manifesto do validDomains aplicativo.
  • O tipo de solicitação de invocação deve ser composeExtensions/queryLink.
  • O invoke fluxo de trabalho deve ser semelhante ao appLinking fluxo de trabalho.
  • O Action.Submit deve ser configurado como Open para manter a consistência.

Se seu aplicativo não estiver otimizado para funcionar no cliente móvel do Teams, o Stageview para aplicativos distribuídos por meio da Microsoft Teams Store será aberto em um navegador da Web padrão.

Invocar da API stageView

A API stageView do TeamsJS permite que você abra a janela do Teams em uma experiência stageview com base na openMode definida. Se a openMode propriedade não estiver definida, a resposta padrão será uma visão de estágio colaborativa com uma conversa de painel lateral associada. Em uma experiência de Visão de Estágio Colaborativa, a conversa do painel lateral é o mesmo thread de onde o Stageview foi invocado, como chat ou chat em grupo.

Observação

A API stageView dá suporte a um parâmetro opcional threadId que permite que você traga uma conversa específica para o painel lateral Do Stageview Colaborativo. O mapeamento contentUrl para threadId permitir que você persista uma conversa ao lado do conteúdo.

Os seguintes códigos são os exemplos para cada openMode valor na API stageView:

A openMode propriedade é definida como popoutWithChat em StageViewParams para abrir no Collaborative Stageview.

  {
    "appId": "2c19df50-1c3c-11ea-9327-cd28e4b6f7ba",
    "contentUrl": "https://teams-test-tab.azurewebsites.net",
    "title": "Test tab ordering",
    "websiteUrl": "https://teams-test-tab.azurewebsites.net",
    "openMode": "popoutWithChat"
  }

Quando openMode não é definido no StageViewParams, a resposta padrão é Visão de estágio colaborativa.

  {
    "appId": "2c19df50-1c3c-11ea-9327-cd28e4b6f7ba",
    "contentUrl": "https://teams-test-tab.azurewebsites.net",
    "title": "Test tab ordering",
    "websiteUrl": "https://teams-test-tab.azurewebsites.net"
  }

Para obter mais informações sobre a API stageView, consulte módulo stageView.

Parâmetros de API stageView

Nome da propriedade Tipo Limite de caracteres Obrigatório Descrição
entityId Cadeia de caracteres 64 Opcional Uma ID exclusiva da entidade que a guia exibe.
appId Cadeia de caracteres 64 Sim A ID do aplicativo Teams que deve ser aberta.
nome Cadeia de caracteres 128 Opcional O nome de exibição da guia na interface de canal. Se nenhum valor for fornecido, o nome do aplicativo será exibido.
contentUrl Cadeia de caracteres 2048 Sim A URL https:// que aponta para a interface do usuário da entidade a ser exibida no Teams.
websiteUrl Cadeia de caracteres 2048 Sim O https:// URL para apontar, se um usuário selecionar para exibir em um navegador.
Threadid Cadeia de caracteres 2048 Opcional A ID define a conversa mostrada no painel lateral do Collaborative Stageview. Se nenhum valor for passado, threadId será herdado do contexto em que o Collaborative Stageview é aberto.
Observação: o parâmetro opcional threadId só dá suporte a threads de chat. Se um canal threadId for usado, o painel lateral não será exibido.
Openmode Cadeia de caracteres 2048 Opcional A propriedade define o comportamento aberto para o conteúdo de estágio no cliente da área de trabalho.

Para invocar Stageview por meio de um link profundo de sua guia ou aplicativo pessoal, embrulhe a URL de link profundo na API app.openLink(url) e defina a openMode propriedade para o conteúdo do chat abrir. Quando a propriedade openMode não é especificada, a resposta do Stageview de um link profundo é padrão para o Collaborative Stageview.

Para exibir um chat específico no painel lateral, você deve especificar um threadId. Caso contrário, a conversa do painel lateral traz o chat em grupo ou o thread de canal do qual o link profundo é invocado.

Observação

  • Todos os links profundos devem ser codificados antes de colar a URL. Não há suporte para URLs não codificadas.
  • Ao invocar Stageview de um determinado contexto, verifique se seu aplicativo funciona nesse contexto.
  • Ao adicionar um threadId, verifique se seu aplicativo funciona no contexto do threadId passado. Se o contexto falhar, a experiência retornará ao contexto pessoal.

Sintaxe

Sintaxe de link profundo para o Collaborative Stageview:

https://teams.microsoft.com/l/stage/{appId}/0?context={"contentUrl":"contentUrl","websiteUrl":"websiteUrl","name":"Contoso","openMode":"popoutWithChat","threadId":"threadId"}

Sintaxe de link profundo codificada para o Collaborative Stageview:

https://teams.microsoft.com/l/stage/%7BappId%7D/0?context=%7B%22contentUrl%22:%22contentUrl%22,%22websiteUrl%22:%22websiteUrl%22,%22name%22:%22Contoso%22,%22openMode%22:%22popoutWithChat%22,%22threadId%22:%22threadId%22%7D


Exemplo

URL de link profundo codificado para invocar o Collaborative Stageview:

https://teams.microsoft.com/l/stage/6d621545-9c65-493c-b069-2b978b37c117/0?context=%7B%22appId%22%3A%226d621545-9c65-493c-b069-2b978b37c117%22%2C%22contentUrl%22%3A%22https%3A%2F%2F3282-115-111-228-84.ngrok-free.app%22%2C%22websiteUrl%22%3A%22https%3A%2F%2F3282-115-111-228-84.ngrok-free.app%22%2C%22name%22%3A%22DemoStageView%22%2C%22openMode%22%3A%22popoutWithChat%22%2C%22threadId%22%3A%2219%3Abe817b823c204cde8aa174ae146251dd%40thread.v2%22%7D

Nome da propriedade Tipo Limite de caracteres Obrigatório Descrição
entityId Cadeia de caracteres 64 Opcional Uma ID exclusiva da entidade que a guia exibe.
appId Cadeia de caracteres 64 Sim A ID do aplicativo Teams que deve ser aberta.
nome Cadeia de caracteres 128 Opcional O nome de exibição da guia na interface de canal. Se nenhum valor for fornecido, o nome do aplicativo será exibido.
contentUrl Cadeia de caracteres 2048 Sim A URL https:// que aponta para a interface do usuário da entidade a ser exibida no Teams.
websiteUrl Cadeia de caracteres 2048 Sim O https:// URL para apontar, se um usuário selecionar para exibir em um navegador.
Threadid Cadeia de caracteres 2048 Opcional A ID define a conversa mostrada no painel lateral do Collaborative Stageview. Se nenhum valor for passado, threadId será herdado do contexto em que o Collaborative Stageview é aberto.
Observação: o parâmetro opcional threadId só dá suporte a threads de chat. Se um canal threadId for usado, o painel lateral não será exibido.
Openmode Cadeia de caracteres 2048 Opcional A propriedade define o comportamento aberto para o conteúdo de estágio no cliente da área de trabalho.

Se você deseja facilitar a multitarefa, aprimorar a colaboração ou fornecer uma experiência de usuário focada, o Stageview tem um modo para atender aos seus requisitos.

Perguntas frequentes


Qual visão de estágio devo usar?

O Stageview colaborativo permite que os usuários abram conteúdo junto com uma conversa de painel lateral em uma janela do Teams. Essa exibição é mais adequada para a maioria dos cenários de colaboração.


Qual é a diferença entre o Modal de Stageview e as caixas de diálogo?

Stageview Modal é útil para exibir conteúdo avançado para os usuários, como página, dashboard ou arquivo.
Caixas de diálogo (conhecidas como módulos de tarefa no TeamsJS v1.x) são úteis para exibir mensagens que precisam da atenção dos usuários ou coletar informações necessárias para passar para a próxima etapa.


Quando Stageview é invocado, o conteúdo é aberto em Estágio Colaborativo, mas é carregado na janela main Teams em vez de uma nova janela. Como abrir o conteúdo em uma nova janela?

Verifique se o contentUrl domínio é refletido com precisão na propriedade de manifesto validDomains . Para obter mais informações, consulte esquema de manifesto do aplicativo.


Por que nenhum conteúdo é exibido em uma nova janela do Teams mesmo quando 'contentUrl' corresponde a 'validDomains'?

Chame app.notifySuccess() todo o conteúdo baseado em iframe para notificar o Teams de que seu aplicativo foi carregado com êxito. Se aplicável, o Teams oculta o indicador de carregamento. Se notifySuccess não for chamado dentro de 30 segundos, o Teams pressupõe que o aplicativo está com o tempo limite e exibe uma tela de erro com uma opção de repetição. Para atualizações de aplicativo, essa etapa é aplicável a guias que já estão configuradas. Se você não executar essa etapa, uma tela de erro será exibida para os usuários existentes.


Posso incluir um link profundo no meu 'contentUrl'?

Não há suporte para links profundos no contentUrl.


Como fazer manter um thread específico mostrado ao lado do meu conteúdo?

O Stageview colaborativo de um link profundo ou uma API stageView vem com o parâmetro adicional threadId . Você pode definir explicitamente o thread de chat a ser exibido no painel lateral do seu específico contentUrl. Para obter mais informações sobre como recuperar um , confira obter thread threadIdde conversa.


Confira também

Criar links detalhados