Link profundo para um aplicativo

  • Artigo

Links profundos são configurados para executar várias ações, como abrir uma guia, iniciar uma caixa de diálogo de instalação de aplicativo ou navegar dentro do aplicativo. Use links profundos em mensagens de bot e conector para informar os usuários sobre alterações na guia ou em seus itens.

Você pode criar links profundos para um aplicativo personalizado. No entanto, se um aplicativo na Microsoft Teams Store compartilhar a mesma ID do aplicativo personalizado, o link profundo abrirá o aplicativo da Teams Store em vez do aplicativo personalizado. Você também pode criar um link profundo para o aplicativo para dispositivos móveis, depois que seu aplicativo for aprovado para a plataforma móvel do Teams. Para que o link profundo funcione no Teams iOS, você precisa da ID da Equipe de Conexão App Store Apple. Para obter mais informações, confira como atualizar a ID da Equipe do App Store Connect da Apple.

Links profundos permitem que os usuários saibam mais sobre um aplicativo e instalem-no em diferentes escopos. Você também pode criar links profundos para que os usuários do aplicativo acessem páginas específicas em seu aplicativo. Neste artigo, saiba como criar um link profundo:

Observação

Este tópico reflete a versão 2.0.x da biblioteca de clientes JavaScript do Microsoft Teams (TeamsJS). Se você estiver usando uma versão anterior, consulte a visão geral da biblioteca do TeamsJS para obter diretrizes sobre as diferenças entre o TeamsJS mais recente e as versões anteriores.

Links profundos permitem que os usuários do aplicativo abram uma caixa de diálogo de instalação de aplicativo para saber mais informações sobre o aplicativo ou instalá-lo em contextos diferentes. Você pode criar um link profundo para o aplicativo das seguintes maneiras:

Aqui está o formato de link profundo que você precisa para abrir uma caixa de diálogo de instalação de aplicativo do cliente do Teams usando a ID do aplicativo:

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

Onde <your-app-id> está sua ID do aplicativo (f46ad259-0fe5-4f12-872d-c737b174bcb4).

ID do aplicativo para diferentes tipos de aplicativos

A tabela a seguir lista os diferentes tipos de IDs de aplicativo usados para diferentes tipos de aplicativos para links profundos:

Tipo de aplicativo Tipo de ID do aplicativo
Aplicativo personalizado carregado no Teams ID do manifesto
Aplicativos enviados ao catálogo da organização ID do catálogo da organização
Aplicativos enviados à Teams Store ID da loja

Para obter mais informações, confira como localizar a ID com base na ID do manifesto do aplicativo.

Os aplicativos podem usar a biblioteca do TeamsJS para iniciar a caixa de diálogo de instalação do aplicativo, eliminando a necessidade de geração de link profundo manual. Aqui está um exemplo de como disparar a caixa de diálogo de instalação do aplicativo usando o TeamsJS em seu aplicativo:

// 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, consulte módulo appInstallDialog.

Os usuários do aplicativo podem navegar pelo conteúdo no Teams na sua guia usando o TeamsJS. Você pode usar um link profundo para navegar em seu aplicativo se sua guia precisar conectar usuários com outros conteúdos no Teams, como em um canal, mensagem, outra guia ou para abrir uma caixa de diálogo de agendamento. Em poucas instâncias, a navegação também pode ser realizada usando o TeamsJS e recomendamos usar recursos tipados do TeamsJS sempre que possível.

O TeamsJS permite que os aplicativos do Teams estendidos no Outlook e no Microsoft 365 marcar se o host der suporte à funcionalidade que você está tentando usar. 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 APIs em recursos por meio de namespaces. Por exemplo, antes de usar uma API no pages namespace, você pode marcar o valor pages.isSupported() booliano retornado e tomar as medidas apropriadas no contexto da interface do usuário do aplicativo e do aplicativo.

Para obter mais informações sobre recursos e as APIs no TeamsJS, consulte Criar guias e outras experiências hospedadas com a biblioteca do TeamsJS.

Você pode configurar links profundos para navegar em seu aplicativo das seguintes maneiras:

Use o seguinte formato para um link profundo em um bot, conector ou extensão de mensagem cartão:

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. Isso acontece no Chrome e no aplicativo de área de trabalho do Teams, quando eles estão em execução no Linux.

  • Se o bot enviar a mesma URL de link profundo em um Action.OpenUrl, a guia Teams será aberta na guia navegador atual quando o usuário selecionar o link.

Os parâmetros de consulta são:

Nome do parâmetro Descrição Exemplo
appId  A ID do centro de administração do Microsoft Teams. fe4a8eba-2a31-4737-8e33-e5fae6fee194
entityId  A ID da guia, que você forneceu ao configurar a guia. Ao gerar uma URL para vinculação profunda, continue a usar a ID da entidade como um nome de parâmetro na URL. Ao configurar a guia, 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  Um rótulo para o item na guia a ser usado ao exibir o link profundo. Lista de tarefas 123 ou Tarefa 456
context.subEntityId  Uma ID para o item dentro da guia. Ao gerar uma URL para vinculação profunda, continue a usar subEntityId como o nome do parâmetro na URL. Ao configurar a guia, 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. Essa propriedade só está disponível em guias configuráveis com um escopo de equipe. Ele não está disponível em guias estáticas, que tem um escopo pessoal . 19:cbe3683f25094106b826c9cada3afbe0@thread.skype
context.chatId  ID de chat disponível no contexto da guia para chat de grupo e reunião. 17:b42de192376346a7906a7dd5cb84b673@thread.v2
context.contextType  O chat é o único com contextType suporte para reuniões. chat
&openInMeeting=false Use openInMeeting para controlar a experiência do usuário quando a guia de destino estiver associada a uma reunião. Se o usuário interagir com o link profundo em uma experiência de reunião contínua, o Teams abrirá o aplicativo no painel lateral da reunião. Defina esse valor para false sempre abrir o aplicativo na guia 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 escopos de guia, consulte o manifesto do aplicativo.
  • Os links profundos funcionarão corretamente somente se a guia estiver configurada usando a biblioteca v0.4 ou posterior, pois ela tem uma ID de entidade. Links profundos para guias sem IDs de entidade ainda vão para a guia, mas não podem fornecer a ID da sub-entidade para a guia.

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

Verifique se todos os parâmetros de consulta e os espaços em branco estão codificados corretamente no URI. Você deve seguir os exemplos anteriores usando o último exemplo:

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;

Você pode configurar links profundos em seu aplicativo por meio do TeamsJS para permitir que os usuários do aplicativo naveguem por páginas diferentes em seu aplicativo. O código a seguir demonstra como navegar até uma entidade específica em seu aplicativo do 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 navegação em um aplicativo de guias, confira navegar em um aplicativo de guias. 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 um link profundo usando a função app.openLink().

O comportamento de navegação de um aplicativo do Teams estendido 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 o aplicativo Teams estiver em execução no host em que o link profundo é direcionado, seu aplicativo será aberto diretamente no host. No entanto, se o aplicativo Teams estiver em execução em um host diferente de onde o link profundo é direcionado, o aplicativo será aberto primeiro no navegador.

Você pode permitir que os usuários de aplicativo naveguem até um chat pessoal com o aplicativo configurando o link profundo manualmente usando o seguinte formato:

https://teams.microsoft.com/l/entity/<appId>/conversations?tenantId=<tenantId>, onde appId está sua ID do aplicativo. Para saber mais sobre as diferentes IDs de aplicativo usadas, consulte ID do aplicativo para diferentes tipos de aplicativos.

Você pode compartilhar links profundos para entidades em aplicativos do Teams para navegar até o conteúdo e as informações em seu aplicativo de guias. Por exemplo, se o aplicativo de guias contiver uma lista de tarefas, os membros da equipe poderão criar e compartilhar links para tarefas individuais. Quando o usuário do aplicativo seleciona o link, ele navega até sua guia que se concentra no item específico.

Adicione uma ação de link de cópia a cada item de qualquer maneira que melhor se adapte à interface do usuário. Quando o usuário tomar essa ação, chame pages.shareDeepLink() para exibir uma caixa de diálogo contendo um link que o usuário 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> })

Você precisa substituir os seguintes parâmetros pelas informações apropriadas:

  • 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

  • Esse link profundo é diferente dos links fornecidos pelo item de menu Copiar para a guia , que gera apenas um link profundo que aponta para essa guia.
  • shareDeepLink não funciona em plataformas móveis do Teams.

Você pode usar o seguinte formato de link profundo em um bot, conector ou extensão de mensagem cartão: https://teams.microsoft.com/l/entity/<appId>/<EntityId>?webUrl=<entityWebUrl>/<EntityName>.

Observação

  • Quando um bot envia uma TextBlock mensagem com um link profundo, uma nova guia do navegador é aberta quando os usuários selecionam o link. Isso acontece no Chrome e no aplicativo da área de trabalho do Microsoft Teams em execução no Linux.
  • Se o bot enviar a mesma URL de link profundo em um Action.OpenUrl, a guia Teams será aberta no navegador atual quando o usuário selecionar o link. 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 uma URL de fallback a ser usada se o cliente não der suporte à renderização da guia – https://tasklist.example.com/123 ou https://tasklist.example.com/list123/task456.

  • entityName: um rótulo para o item na guia a ser usado ao exibir o link profundo, 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

Um link profundo da caixa de diálogo é uma serialização do TaskInfo objeto com dois outros detalhes, o APP_ID e, 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 a URL do link profundo ao usar 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 aplicativos de terceiros, use o aplicativo id do manifesto ou do APP_ID centro de administração do Teams, pois eles são idênticos. Para aplicativos personalizados ou aplicativos personalizados criados para sua organização (aplicativos LOB), use o APP_ID do centro de administração do Teams ou use o API do Graph. A matriz validDomains no manifesto para APP_ID deve conter o domínio para url se url estiver presente na URL de link profundo. A ID do aplicativo já é conhecida quando uma caixa de diálogo é invocada de uma guia ou de um 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 deve ser especificado como um bot no manifesto do aplicativo, que você não pode enviá-lo para nenhum bot.

Observação

APP_ID e BOT_APP_ID pode ser o mesmo em muitos casos, se um aplicativo tiver um bot recomendado para usar como ID de um aplicativo e se houver um.

Gerar um link profundo para compartilhar conteúdo para o estágio em reuniões

Você também pode gerar um link profundo para compartilhar o aplicativo para o estágio e iniciar ou ingressar em uma reunião.

Para que links profundos compartilhem conteúdo para o estágio, consulte link profundo para compartilhar conteúdo para o estágio em reuniões.

Observação

  • Gerar um link profundo para compartilhar conteúdo para o estágio em reuniões só está disponível na versão prévia do desenvolvedor público.
  • O link profundo para compartilhar conteúdo para o estágio na reunião tem suporte somente no cliente da área de trabalho do Teams.

Você pode gerar um link profundo para o painel do lado da reunião em uma reunião. Use o seguinte formato para um link profundo para o painel lateral 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 padrão, um link profundo é aberto em um painel lateral da reunião. Para abrir um link profundo diretamente em um aplicativo em vez do painel lateral da reunião, adicione openInMeeting=false o formato de link profundo:

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

Para obter mais informações, consulte link profundo para uma guia.

Um link profundo não é aberto no painel lateral da reunião nos seguintes cenários:

  • Não há nenhuma reunião ativa.
  • O aplicativo não tem sidePanel contexto declarado no manifesto do aplicativo.
  • openInMeeting é definido como false no link profundo.
  • O link profundo é selecionado fora da janela ou componente da reunião.
  • O link profundo não corresponderá à reunião atual, por exemplo, se o link profundo for criado a partir de outra reunião.

Você pode invocar Stageview por meio de um link profundo de sua guia encapsulando a URL de link profundo 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 Stageview. Para obter mais informações, consulte invocar Stageview por meio de um link profundo.

Exemplo de código

Nome do exemplo Descrição .NET Node.js
Link profundo que consome A ID da sub-entidade Este exemplo mostra como usar um link profundo de um chat de bot para uma guia que consome a ID da Sub entidade. Ele também mostra links profundos para:
– Navegando até um aplicativo
– Navegando até um chat
– Abrir uma caixa de diálogo de perfil
– Abrir uma caixa de diálogo de agendamento		 View View