Partilhar via

Ligação avançada para uma aplicação

  • Artigo

As ligações avançadas no Microsoft Teams são ferramentas avançadas que permitem aos utilizadores navegar diretamente para conteúdos ou ações específicos numa aplicação. As ligações avançadas são configuradas para efetuar várias ações, como abrir um separador, iniciar uma caixa de diálogo de instalação da aplicação ou navegar na aplicação.

Observação

Este tópico reflete a versão 2.0.x da biblioteca de cliente JavaScript do Microsoft Teams (TeamsJS). Se estiver a utilizar uma versão anterior, consulte a descrição geral da biblioteca do TeamsJS para obter orientações sobre as diferenças entre as versões mais recentes do TeamsJS e versões anteriores.

Eis alguns dos cenários em que pode utilizar uma ligação avançada:

  • Instalação de aplicações: pode utilizar ligações avançadas que permitem aos utilizadores saber mais sobre uma aplicação e instalá-la em diferentes âmbitos.
  • Bots e conectores: pode utilizar ligações avançadas em bots e mensagens de conectores para informar os utilizadores sobre as alterações ao seu separador ou aos respetivos itens.
  • Navegar para uma página específica: pode criar ligações avançadas que permitem aos utilizadores navegar para páginas específicas na sua aplicação.
  • Aplicação personalizada: pode gerar ligações avançadas para uma aplicação personalizada. No entanto, se uma aplicação na Microsoft Teams Store partilhar o mesmo ID da aplicação que o ID da aplicação personalizada, a ligação avançada abre a aplicação a partir da Loja Teams em vez da aplicação personalizada.
  • Para dispositivos móveis: também pode criar uma ligação avançada para uma aplicação para dispositivos móveis depois de a sua aplicação ser aprovada para o cliente móvel do Teams. Para que a ligação avançada funcione no Teams iOS, precisa do ID da Equipa do Apple App Store Connect. Para obter mais informações, veja como atualizar o ID da Equipa do Apple App Store Connect.

As ligações avançadas permitem que os utilizadores da aplicação abram uma caixa de diálogo de instalação da aplicação para saberem qualquer informação sobre a aplicação ou instalá-la em diferentes contextos. Pode criar uma ligação avançada para uma aplicação das seguintes formas:

Com uma ligação avançada, pode abrir uma caixa de diálogo de instalação de aplicações diretamente a partir do cliente do Teams com o ID da aplicação.

https://teams.microsoft.com/l/app/<your-app-id>?tenantId=<tenantId>

<your-app-id> é o ID da aplicação (fxxxxxxx-0xxx-4xxx-8xxx-cxxxxxxxxxxx).

ID da Aplicação para diferentes tipos de aplicações

A tabela seguinte lista os diferentes tipos de IDs de aplicação utilizados para diferentes tipos de aplicações para ligações avançadas:

Tipo de aplicação Tipo de ID da aplicação
Aplicação personalizada carregada no Teams ID do Manifesto
Aplicações submetidas para o catálogo de organizações ID do catálogo da organização
Aplicações submetidas para a Loja Teams ID da Loja

Para obter mais informações, veja como localizar o ID com base no ID do manifesto da aplicação.

As aplicações podem utilizar a biblioteca de cliente JavaScript (TeamsJS) do Microsoft Teams para iniciar a caixa de diálogo de instalação da aplicação, eliminando a necessidade de geração manual de ligações profundas. Eis um exemplo de como acionar a caixa de diálogo de instalação da aplicação com o TeamsJS na sua aplicação:

// Open an app install dialog from your tab
if(appInstallDialog.isSupported()) {
    const dialogPromise = appInstallDialog.openAppInstallDialog({ appId: "<appId>" });
    dialogPromise.
      then((result) => {/*Successful operation*/}).
      catch((error) => {/*Unsuccessful operation*/});
}
else { /* handle case where capability isn't supported */ }

Para obter mais informações, confira appInstallDialog.

Os utilizadores da aplicação podem procurar conteúdos no Teams a partir do seu separador através do TeamsJS. Pode utilizar uma ligação avançada para navegar na sua aplicação se o separador precisar de ligar utilizadores a outros conteúdos no Teams, como um canal, mensagem, outro separador ou para abrir uma caixa de diálogo de agendamento. Em alguns casos, a navegação também pode ser realizada com o TeamsJS e recomendamos que utilize as capacidades digitadas do TeamsJS sempre que possível.

Pode configurar ligações avançadas para navegar na sua aplicação das seguintes formas:

As guias pessoais têm um escopo personal, enquanto as guias de canal e grupo usam escopos team ou group. Os dois tipos de separador têm uma sintaxe ligeiramente diferente, uma vez que apenas o separador configurável tem uma channel propriedade associada ao respetivo objeto de contexto. Para obter mais informações sobre âmbitos de separadores, veja o manifesto da aplicação.

Para criar uma ligação avançada num bot, conector ou extensão de mensagem card, utilize o seguinte formato:

https://teams.microsoft.com/l/entity/<appId>/<entityId>?tenantId=<tenantId>&webUrl=<entityWebUrl>&label=<entityLabel>&context=<context>&openInMeeting=false

  • Se o bot enviar uma mensagem contendo um TextBlock com um link profundo, uma nova guia do navegador será aberta quando o usuário selecionar o link. Isto acontece no Chrome e na aplicação de ambiente de trabalho do Teams quando estão a ser executados no Linux.

  • Se o bot enviar o mesmo URL de ligação avançada para um Action.OpenUrl, o separador Teams é aberto no separador do browser atual quando o utilizador seleciona a ligação.

Parâmetros de consulta

Nome do parâmetro Descrição
appId  O ID do centro de administração do Microsoft Teams.

Exemplo: fe4a8eba-2a31-4737-8e33-e5fae6fee194
entityId  O ID do separador, que forneceu ao configurar o separador. Ao gerar um URL para ligação profunda, continue a utilizar o ID da entidade como um nome de parâmetro no URL. Ao configurar o separador, o objeto de contexto refere-se ao entityId como page.id.

Exemplo: Lista de tarefas 123
entityWebUrl ou subEntityWebUrl  Um campo opcional com uma URL de fallback a ser usada se o cliente não for compatível com a renderização da guia.

Exemplo: https://tasklist.example.com/123
ou
https://tasklist.example.com/list123/task456
entityLabel ou subEntityLabel  Uma etiqueta para o item no separador utilizar ao apresentar a ligação avançada.

Exemplo: Lista de Tarefas 123 ou Tarefa 456
context.subEntityId  Um ID para o item no separador. Ao gerar um URL para ligação profunda, continue a utilizar subEntityId como o nome do parâmetro no URL. Ao configurar o separador, o objeto de contexto refere-se ao subEntityId como page.subPageId.

Exemplo: Tarefa 456
context.channelId  ID do canal do Microsoft Teams que está disponível na guia contexto. Esta propriedade só está disponível em separadores configuráveis com um âmbito de equipa. Não está disponível em separadores estáticos, que têm um âmbito pessoal .

Exemplo: 19:cbe3683f25094106b826c9cada3afbe0@thread.skype
context.chatId  ID de chat que está disponível no contexto de separador para chat de grupo e reunião.

Exemplo: 17:b42de192376346a7906a7dd5cb84b673@thread.v2
context.contextType  O chat é o único suportado contextType para reuniões.

Exemplo: chat
openInMeeting Utilize openInMeeting para controlar a experiência do utilizador quando o separador de destino está associado a uma reunião. Se o utilizador interagir com a ligação avançada numa experiência de reunião em curso, o Teams abre a aplicação no painel do lado da reunião. Defina este valor como para false abrir sempre a aplicação no separador chat da reunião em vez do painel lateral, independentemente da reunião status. O Teams ignora qualquer valor diferente de false.

Exemplo: false

Importante

  • Certifique-se de que todos os parâmetros de consulta e os espaços em branco estão codificados corretamente com URI. Segue-se um exemplo de parâmetros de consulta codificados com URI:

    var encodedWebUrl = encodeURIComponent('https://tasklist.example.com/123/456&label=Task 456');
var encodedContext = encodeURIComponent(JSON.stringify({"subEntityId": "task456"}));
var taskItemUrl = 'https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=' + encodedWebUrl + '&context=' + encodedContext;

  • A ligação avançada a uma aplicação do Teams com URI codificado não é suportada no Outlook.

Pode configurar ligações avançadas na sua aplicação através do TeamsJS para permitir que os utilizadores procurem páginas diferentes na sua aplicação. O comportamento de navegação de uma aplicação do Teams expandida no Microsoft 365 Office depende de dois fatores:

  1. O destino para o qual o link profundo aponta.
  2. O host em que o aplicativo Teams está em execução

Se a aplicação Teams estiver em execução no anfitrião onde a ligação avançada é direcionada, a sua aplicação é aberta diretamente no anfitrião. No entanto, se a aplicação Teams estiver em execução num anfitrião diferente de onde a ligação avançada é direcionada, a aplicação é aberta primeiro no browser.


Suporte para ligações avançadas no TeamsJS

O TeamsJS permite que as aplicações do Teams expandidas para o Outlook e o Microsoft 365 marcar se o anfitrião suportar a capacidade que está a tentar utilizar. Para verificar o suporte de um host de uma funcionalidade, você pode usar a função isSupported() associada ao namespace da API. O TeamsJS organiza as APIs em capacidades através de espaços de nomes. Por exemplo, antes de utilizar uma API no pages espaço de nomes, pode marcar o valor pages.isSupported() booleano devolvido e tomar a ação adequada no contexto da IU da sua aplicação e da aplicação. Para obter mais informações, veja Criar separadores e outras experiências alojadas com a biblioteca do TeamsJS.

O código seguinte demonstra como navegar para uma entidade específica na sua aplicação Teams:

Você pode acionar a navegação de sua guia usando a função pages.navigateToApp() conforme mostrado no código a seguir:

if (pages.isSupported()) {
  const navPromise = pages.navigateToApp({ appId: <appId>, pageId: <pageId>, webUrl: <webUrl>, subPageId: <subPageId>, channelId:<channelId>});
  navPromise.
     then((result) => {/*Successful navigation*/}).
     catch((error) => {/*Failed navigation*/});
}
else { /* handle case where capability isn't supported */ }

A capacidade de páginas da biblioteca do TeamsJS fornece suporte para navegação entre separadores numa aplicação. Especificamente, o pages.currentApp espaço de nomes oferece uma função navigateTo(NavigateWithinAppParams) para permitir a navegação para um separador específico na aplicação atual e uma função navigateToDefaultPage() para navegar para o primeiro separador definido no manifesto da aplicação. O código seguinte ilustra como navegar para um separador específico e predefinido:

O código seguinte ilustra como navegar para um separador específico:

if (pages.currentApp.isSupported()) {
    const navPromise = pages.currentApp.navigateTo({pageId: <pageId>, subPageId: <subPageId>});
    navPromise.
        then((result) => {/*Successful navigation*/}).
        catch((error) => {/*Failed navigation*/});
}
else {/*Handle situation where capability isn't supported*/
    const navPromise = pages.navigateToApp({appId: <appId>, pageId: <pageId>});
    navPromise.
        then((result) => {/*Successful navigation*/}).
        catch((error) => {/*Failed navigation*/});
}

Observação

A navegação da aplicação de separador só é suportada no novo cliente do Teams.

Configurar a navegação do botão anterior

Quando uma aplicação tem vários separadores, um utilizador pode utilizar o botão anterior da aplicação anfitriã do Microsoft 365 para retroceder no histórico de navegação. No entanto, o histórico não inclui as ações que um utilizador executa num separador. Se quiser melhorar a experiência do botão anterior, pode manter a sua própria pilha de navegação interna e configurar um processador personalizado para seleções de botões anteriores. Isto pode ser feito através da registerBackButtonHandler() função no pages.backStack espaço de nomes.

Depois de registar o processador, ajuda-o a resolver o pedido de navegação antes de o sistema tomar medidas. Se o processador conseguir gerir o pedido, deverá devolver true para que o sistema saiba que não é necessária mais nenhuma ação. Se a pilha interna estiver vazia, deverá devolver false para que o sistema possa chamar a navigateBack() função e tomar a ação adequada.

Devolver o foco à aplicação anfitriã

Após o utilizador começar a utilizar elementos num separador, por predefinição, o foco permanece com os elementos do seu iFrame até que o utilizador selecione fora do mesmo. Se o iFrame fizer parte do utilizador que navega com atalhos de teclado (a Tecla de Tabulação ou a tecla F6), pode concentrar-se na aplicação anfitriã. Pode focar-se na aplicação anfitriã com a pages.returnFocus() função . A returnFocus() função aceita um Valor booleano que indica a direção para avançar o foco na aplicação anfitriã; true para avançar e false retroceder. Geralmente, reencaminhar realça a barra de pesquisa e realça a barra da aplicação para trás.

Pode permitir que os utilizadores da aplicação naveguem para uma conversa pessoal com a aplicação ao configurar a ligação avançada manualmente.

https://teams.microsoft.com/l/entity/<appId>/conversations?tenantId=<tenantId>

appId é o seu ID de aplicação. Para obter mais informações, veja ID da aplicação para diferentes tipos de aplicações.

Pode partilhar ligações avançadas para entidades nas aplicações do Teams para navegar para os conteúdos e informações na sua aplicação de separador. Por exemplo, se a sua aplicação de separador contiver uma lista de tarefas, os membros da equipa podem criar e partilhar ligações para tarefas individuais. Quando o utilizador da aplicação seleciona a ligação, navega para o separador que se foca no item específico.

Adicione uma ação de ligação de cópia a cada item da forma mais adequada à sua IU. Quando o utilizador efetuar esta ação, chame pages.shareDeepLink() para apresentar uma caixa de diálogo com uma ligação que o utilizador pode copiar para a área de transferência. Ao fazer essa chamada, passe uma ID para o item. Obtém-na novamente no contexto em que a ligação é seguida e o separador é recarregado.

pages.shareDeepLink({ subPageId: <subPageId>, subPageLabel: <subPageLabel>, subPageWebUrl: <subPageWebUrl> })

Tem de substituir os seguintes parâmetros pelas informações adequadas:

Nome do parâmetro Descrição
subPageId Um identificador exclusivo para o item na sua página ao qual está a ligar profundamente.
subPageLabel Uma etiqueta para o item utilizar para apresentar a ligação avançada.
subPageWebUrl Um URL de contingência a utilizar se o cliente não conseguir compor a página.

Para obter mais informações, consulte pages.shareDeepLink().

Observação

  • Esta ligação avançada é diferente das ligações fornecidas pelo item de menu Copiar ligação para separador , o que gera apenas uma ligação avançada que aponta para este separador.
  • shareDeepLink não funciona em plataformas móveis do Teams.

As ligações avançadas para separadores de Estrutura do SharePoint (SPFx) permitem que os utilizadores naveguem diretamente para separadores específicos num site do SharePoint ou numa aplicação do Teams. Isto melhora a experiência do utilizador ao fornecer acesso rápido a conteúdos e funcionalidades relevantes.

Pode utilizar o seguinte formato de ligação avançada num bot, conector ou extensão de mensagem card:

https://teams.microsoft.com/l/entity/<appId>/<EntityId>?webUrl=<entityWebUrl>/<EntityName>.

Observação

  • Quando um bot envia uma TextBlock mensagem com uma ligação avançada, é aberto um novo separador do browser quando os utilizadores selecionam a ligação. Isso acontece no Chrome e no aplicativo da área de trabalho do Microsoft Teams em execução no Linux.
  • Se o bot enviar o mesmo URL de ligação avançada num Action.OpenUrl, o separador Teams é aberto no browser atual quando o utilizador seleciona a ligação. Nenhuma nova guia do navegador está aberta.

Parâmetros de consulta

Valor Descrição
APP_ID O seu ID de manifesto.

Exemplo: fxxxxxxx-0xxx-4xxx-8xxx-cxxxxxxxxxxx
entityID O ID do item que forneceu ao configurar o separador.

Exemplo: tasklist123
entityWebUrl Um URL de contingência a utilizar se o cliente não suportar a composição do separador.

Exemplo: https://tasklist.example.com/123 ou https://tasklist.example.com/list123/task456
entityName Uma etiqueta para o item no separador utilizar ao apresentar a ligação avançada.

Exemplo: Task List 123 ou Task 456

Uma ligação avançada de caixa de diálogo é uma serialização do TaskInfo objeto com dois outros detalhes, e APP_ID opcionalmente o BOT_APP_ID.

  • https://teams.microsoft.com/l/task/APP_ID?url=<TaskInfo.url>&height=<TaskInfo.height>&width=<TaskInfo.width>&title=<TaskInfo.title>&completionBotId=BOT_APP_ID

  • https://teams.microsoft.com/l/task/APP_ID?card=<TaskInfo.card>&height=<TaskInfo.height>&width=<TaskInfo.width>&title=<TaskInfo.title>&completionBotId=BOT_APP_ID

Para os tipos de dados e valores permitidos para <TaskInfo.url>, <TaskInfo.card>, <TaskInfo.height>, <TaskInfo.width> e <TaskInfo.title>, consulte objeto TaskInfo.

Dica

Codificar o URL da ligação avançada ao utilizar o card parâmetro, por exemplo, a função JavaScriptencodeURI().

A tabela a seguir fornece informações sobre APP_ID e BOT_APP_ID:

Valor Tipo Obrigatório Descrição
APP_ID string Sim - Para aplicações de terceiros, utilize a aplicação id a partir do manifesto ou do APP_ID centro de administração do Teams, uma vez que são idênticas.

- Para aplicações personalizadas ou aplicações personalizadas criadas para a sua organização (aplicações LOB), utilize o APP_ID do centro de administração do Teams ou utilize o API do Graph.

- A matriz validDomains no manifesto para APP_ID tem de conter o domínio para url se url estiver presente no URL de ligação profunda. O ID da aplicação já é conhecido quando uma caixa de diálogo é invocada a partir de um separador ou bot, razão pela qual não está incluída no TaskInfo.
BOT_APP_ID string Não Se um valor para completionBotId for especificado, o objeto result será enviado usando uma mensagem task/submit invoke para o bot especificado. Especificar BOT_APP_ID tem de ser especificado como um bot no manifesto da aplicação, que não pode enviar para nenhum bot.

Observação

APP_ID e BOT_APP_ID pode ser o mesmo em muitos casos, se uma aplicação tiver um bot recomendado para utilizar como ID de uma aplicação e se existir um.

Ligação avançada para partilhar conteúdo na fase da reunião

Também pode gerar uma ligação avançada para partilhar a aplicação no palco e iniciar ou participar numa reunião.

Para obter ligações avançadas para partilhar conteúdo em palco, consulte a ligação avançada para partilhar conteúdo para realizar reuniões.

Observação

  • A geração de uma ligação avançada para partilhar conteúdos em reuniões só está disponível na pré-visualização do programador público.
  • A ligação avançada para partilhar conteúdo para a fase da reunião é suportada apenas no cliente de ambiente de trabalho do Teams.

Pode gerar uma ligação avançada para o painel do lado da reunião numa reunião.

Utilize o seguinte formato para uma ligação avançada para o painel do lado da reunião:

https://teams.microsoft.com/l/entity/<appId>/<entityId>?webUrl=<entityWebUrl>&label=<entityLabel>&context=<context>.

Por predefinição, é aberta uma ligação avançada num painel do lado da reunião. Para abrir uma ligação avançada diretamente numa aplicação em vez do painel do lado da reunião, adicione openInMeeting=false conforme mostrado no seguinte formato de ligação avançada:

https://teams.microsoft.com/l/entity/<appId>/<entityId>?webUrl=<entityWebUrl>&label=<entityLabel>&context=<context>&openInMeeting=false

Para obter mais informações, veja ligação avançada a um separador.

Não é aberta uma ligação avançada no painel do lado da reunião nos seguintes cenários:

  • Não há nenhuma reunião ativa.
  • A aplicação não tem sidePanel o contexto declarado no manifesto da aplicação.
  • openInMeeting está definido como false na ligação avançada.
  • A ligação avançada está selecionada fora da janela ou componente da reunião.
  • A ligação avançada não corresponde à reunião atual, por exemplo, se a ligação avançada for criada a partir de outra reunião.

Pode invocar o Stageview através de uma ligação avançada a partir do separador ao encapsular o URL da ligação avançada na app.openLink(url) API. O link profundo também pode ser passado por meio de uma ação OpenURL no cartão. A openMode propriedade definida na API determina a resposta de Stageview. Para obter mais informações, veja invocar o Stageview através de uma ligação avançada.

Práticas recomendadas

  • As ligações profundas só funcionam corretamente se o separador tiver sido configurado com a biblioteca v0.4 ou posterior, uma vez que tem um ID de entidade. As ligações avançadas para separadores sem IDs de entidade ainda vão para o separador, mas não podem fornecer o sub'EntityId ao separador.
  • No Microsoft Windows, o Teams não consegue processar ligações profundas que excedam os 2048 carateres devido ao limite na API ShellExecuteEx do INTERNET_MAX_URL_LENGTH Windows.
  • Ao criar uma ligação avançada, certifique-se de que o caminho para o cliente do Teams e outros metadados se enquadra neste limite.
  • Se a ligação avançada contiver dados grandes, inclua um identificador exclusivo na ligação que a sua aplicação pode utilizar para obter os dados necessários do serviço de back-end.

Exemplo de código

Nome do exemplo Descrição .NET Node.js
Consumo de ligações profundas subEntityId Este exemplo mostra como utilizar uma ligação avançada de um chat de bot para um separador que consome o subEntityId. Também mostra ligações avançadas para:
- Navegar para uma aplicação
- Navegar para uma conversa
- Abrir uma caixa de diálogo de perfil
- Abrir uma caixa de diálogo de agendamento		 View View
Navegação da aplicação de separador Este exemplo mostra como navegar entre separadores na aplicação. NA View