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

  • Artigo

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. Utilize ligações avançadas em mensagens de bot e conector para informar os utilizadores sobre as alterações ao seu separador ou aos respetivos itens.

Pode criar 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. Também pode criar uma ligação avançada para a aplicação para dispositivos móveis, depois de a sua aplicação ser aprovada para a plataforma 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 aos utilizadores saber mais sobre uma aplicação e instalá-la em diferentes âmbitos. Também pode criar ligações avançadas para os utilizadores da sua aplicação acederem a páginas específicas na sua aplicação. Neste artigo, saiba como criar uma ligação avançada:

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.

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

Eis o formato de ligação avançada de que precisa para abrir uma caixa de diálogo de instalação da aplicação a partir do cliente do Teams com o ID da aplicação:

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

Onde <your-app-id> está o ID da aplicação (f46ad259-0fe5-4f12-872d-c737b174bcb4).

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 do TeamsJS para iniciar a caixa de diálogo de instalação da aplicação, eliminando a necessidade de geração manual de ligações avançadas. 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 sobre o appInstallDialog módulo, veja appInstallDialog module (Módulo 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 num canal, mensagem, outro separador ou para abrir uma caixa de diálogo de agendamento. Em poucas instâncias, a navegação também pode ser realizada com o TeamsJS e recomendamos que utilize as capacidades digitadas do TeamsJS sempre que possível.

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 sobre as capacidades e as APIs no TeamsJS, consulte Criar separadores e outras experiências alojadas com a biblioteca do TeamsJS.

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

Observação

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 grandes quantidades de dados, 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.

Utilize o seguinte formato para uma ligação avançada num bot, conector ou extensão de mensagem card:

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.

Os parâmetros de consulta são:

Nome do parâmetro Descrição Exemplo
appId  O ID do centro de administração do Microsoft Teams. 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. 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. 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. 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. 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 . 19:cbe3683f25094106b826c9cada3afbe0@thread.skype
context.chatId  ID de chat que está disponível no contexto de separador para chat de grupo e reunião. 17:b42de192376346a7906a7dd5cb84b673@thread.v2
context.contextType  O chat é o único suportado contextType para reuniões. 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. false

Observação

  • As guias pessoais têm um escopo personal, enquanto as guias de canal e grupo usam escopos team ou group. Os dois tipos de guia têm uma sintaxe ligeiramente diferente, pois apenas a guia configurável possui uma propriedade channel associada ao seu objeto de contexto. Para obter mais informações sobre os âmbitos dos separadores, veja o manifesto da aplicação.
  • 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 ID de subentidade ao separador.

Exemplos:

  • Link para uma guia estática (pessoal) propriamente dita:

    https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123&label=Task List 123

  • Link para um item dentro tarefa na guia estática (pessoal):

    https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123/456&label=Task 456&context={"subEntityId": "task456"}

  • Link para uma guia configurável em si:

    https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123&label=Task List 123&context={"channelId": "19:cbe3683f25094106b826c9cada3afbe0@thread.skype"}

  • Link para um item de tarefa na guia configurável:

    https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123/456&label=Task 456&context={"subEntityId": "task456","channelId": "19:cbe3683f25094106b826c9cada3afbe0@thread.skype"}

  • Link para um aplicativo de guia adicionado a uma reunião ou chat em grupo:

    https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123/456&label=Task 456?context={"chatId": "17:b42de192376346a7906a7dd5cb84b673@thread.v2","contextType":"chat"}

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 da aplicação naveguem em páginas diferentes na sua aplicação. 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 */ }

Para obter mais informações sobre como usar a funcionalidade páginas, consulte pages.navigateToApp() e o namespace pages para outras opções de navegação. Se necessário, abra diretamente uma ligação avançada com a função app.openLink( ).

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.

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 manualmente a ligação avançada com o seguinte formato:

https://teams.microsoft.com/l/entity/<appId>/conversations?tenantId=<tenantId>, onde appId está o ID da aplicação. Para saber mais sobre os diferentes IDs de aplicações utilizados, 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. Você o obtém novamente no contexto quando o link é seguido e sua guia é recarregada.

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

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

  • subPageId: um identificador exclusivo para o item da sua página à qual você tem uma vinculação profunda.
  • subPageLabel: Um rótulo para o item a ser usado para exibir o link profundo.
  • subPageWebUrl: uma URL de fallback a ser usada se o cliente não puder renderizar 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.

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.

Os parâmetros de consulta são:

  • appID: sua ID de manifesto, por exemplo, fe4a8eba-2a31-4737-8e33-e5fae6fee194.

  • entityID: a ID do item que você forneceu ao configurar a guia. Por exemplo, tasklist123.

  • entityWebUrl: um parâmetro opcional com um URL de contingência a utilizar se o cliente não suportar a composição do separador – https://tasklist.example.com/123 ou https://tasklist.example.com/list123/task456.

  • entityName: uma etiqueta para o item no separador a utilizar ao apresentar a ligação avançada, como Task List 123 ou Task 456.

Exemplo: https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123&TaskList

Uma ligação avançada de caixa de diálogo é uma serialização do TaskInfo objeto com outros dois detalhes: e, opcionalmente, APP_ID 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.

Gerar uma ligação avançada para partilhar conteúdo para realizar reuniões

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

Exemplo:

https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123/456&label=Task 456&context={"chatId": "17:b42de192376346a7906a7dd5cb84b673@thread.v2","contextType":"chat"}

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 o 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.

Exemplo de código

Nome do exemplo Descrição .NET Node.js
Ligação avançada que consome o ID de Subentidade Este exemplo mostra como utilizar uma ligação avançada de um chat de bot para um separador que consome o ID de Subentidade. 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 Exibir
Navegação da aplicação de separador Este exemplo mostra como navegar entre separadores na aplicação. NA View