Link profundo para um aplicativo

Os links profundos no Microsoft Teams são ferramentas poderosas que permitem aos usuários navegar diretamente para conteúdo ou ações específicas em um aplicativo. Os links profundos são configurados para executar várias ações, como abrir uma guia, iniciar uma caixa de diálogo de instalação do aplicativo ou navegar dentro do aplicativo.

Cenários de links profundos

Aqui estão alguns dos cenários em que você pode usar um link profundo:

• Instalação do aplicativo: você pode usar links profundos que permitem aos usuários saber mais sobre um aplicativo e instalá-lo em diferentes escopos.
• Bots e conectores: você pode usar links profundos em mensagens de bots e conectores para informar os usuários sobre alterações na guia ou em seus itens.
• Navegar até uma página específica: você pode criar links profundos que permitem que os usuários naveguem para páginas específicas em seu aplicativo.
• Aplicativo personalizado: você pode gerar links profundos para um aplicativo personalizado. No entanto, se um aplicativo no Microsoft Teams Store compartilhar a mesma ID do aplicativo que a ID do aplicativo personalizado, o link profundo abrirá o aplicativo na Teams Store em vez do aplicativo personalizado.
• Para dispositivos móveis: Você também pode criar um link profundo para um aplicativo para dispositivos móveis depois que seu aplicativo for aprovado para o cliente móvel do Teams. Para que o link profundo funcione no Teams iOS, você precisa da ID da equipe do Apple App Store Connect. Para obter mais informações, consulte como atualizar a ID da equipe do Apple App Store Connect.

Link profundo para abrir uma caixa de diálogo de instalação do aplicativo

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

• Configurar o link profundo manualmente usando a ID do aplicativo
• Configurar link profundo usando TeamsJS

Configurar o link profundo manualmente usando a ID do aplicativo

Com o link profundo, você pode abrir uma caixa de diálogo de instalação do aplicativo diretamente do cliente do Teams usando a ID do aplicativo.

ID do aplicativo para diferentes tipos de aplicativos

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

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

Configurar link profundo usando TeamsJS

Os aplicativos podem usar a biblioteca de clientes JavaScript do Microsoft Teams (TeamsJS) para iniciar a caixa de diálogo de instalação do aplicativo, eliminando a necessidade de geração manual de links profundos. 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 */ }

// Open an app install dialog from your tab
microsoftTeams.executeDeepLink("https://teams.microsoft.com/l/app/<appId>");

Para obter mais informações, confira appInstallDialog.

Link profundo para procurar dentro do seu aplicativo

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

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

• Configurar o link profundo para navegar dentro do seu aplicativo manualmente
• Configurar o link profundo para uma guia usando o TeamsJS
• Configurar link profundo para navegar entre as guias

Configurar o link profundo para navegar dentro do seu aplicativo manualmente

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 sintaxe ligeiramente diferente, pois apenas a guia configurável tem uma channel propriedade associada ao objeto de contexto. Para obter mais informações sobre escopos de guia, consulte manifesto do aplicativo.

Parâmetros de consulta

Para obter mais informações sobre como obter os parâmetros de consulta para os tipos de guia internos, consulte Configurar os tipos de guia internos no Microsoft Teams.

Configurar o link profundo para uma guia usando o TeamsJS

Você pode configurar links profundos em seu aplicativo por meio do TeamsJS para permitir que os usuários naveguem em diferentes páginas dentro de seu aplicativo. O comportamento de navegação de um aplicativo do Teams estendido pelo 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 onde o link profundo é direcionado, seu aplicativo será aberto diretamente no host. No entanto, se o aplicativo Teams estiver sendo executado em um host diferente de onde o link profundo é direcionado, o aplicativo será aberto primeiro no navegador.

O código a seguir demonstra como navegar até uma entidade específica no aplicativo Teams:

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 */ }

microsoftTeams.executeDeepLink(/*deepLink*/);

• Para obter mais informações, consulte navegar em um aplicativo de guia.
• Para obter mais informações sobre a funcionalidade de páginas, consulte pages.navigateToApp() e o namespace de páginas para outras opções de navegação.
• Para abrir diretamente um link profundo usando app.openLink(), consulte a função app.openLink().

Configurar link profundo para navegar entre as guias

A funcionalidade de páginas da biblioteca TeamsJS fornece suporte para navegação entre guias em um aplicativo. Especificamente, o pages.currentApp namespace oferece uma função navigateTo(NavigateWithinAppParams) para permitir a navegação para uma guia específica no aplicativo atual e uma função navigateToDefaultPage() para navegar até a primeira guia definida no manifesto do aplicativo. O código a seguir ilustra como navegar até uma guia específica e padrão:

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*/});
}

if (pages.currentApp.isSupported()) {
    const navPromise = pages.currentApp.navigateToDefaultPage();
    navPromise.
        then((result) => {/*Successful navigation*/}).
        catch((error) => {/*Failed navigation*/});
}
else {/*Handle situation where capability isn't supported*/}

Configurar navegação do botão Voltar

Quando um aplicativo tem várias guias, um usuário pode usar o botão voltar do aplicativo host do Microsoft 365 para voltar no histórico de navegação. No entanto, o histórico não inclui as ações que um usuário executa em uma guia. Para aprimorar a experiência do botão Voltar, você pode manter sua própria pilha de navegação interna e configurar um manipulador personalizado para seleções de botão Voltar. Isso pode ser feito por meio da registerBackButtonHandler() função no pages.backStack namespace.

Depois de registrar o manipulador, ele ajuda você a resolver a solicitação de navegação antes que o sistema tome uma ação. Se o manipulador for capaz de gerenciar a solicitação, ele deverá retornar true para que o sistema saiba que nenhuma ação adicional é necessária. Se a pilha interna estiver vazia, ela deverá retornar false para que o sistema possa chamar a navigateBack() função e executar a ação apropriada.

Retornar o foco para o aplicativo host

Depois que o usuário começa a usar elementos em uma guia, por padrão, o foco permanece com os elementos do iFrame até que o usuário selecione fora dele. Se o iFrame fizer parte da navegação do usuário com atalhos de teclado (a tecla Tab ou a tecla F6), você poderá se concentrar no aplicativo host. Você pode se concentrar no aplicativo host usando a pages.returnFocus() função. A returnFocus() função aceita um booliano indicando a direção para avançar o foco no aplicativo host; true para frente e false para trás. Geralmente, para frente realça a barra de pesquisa e para trás realça a barra de aplicativos.

Link profundo para um chat com o aplicativo

Você pode permitir que os usuários do aplicativo naveguem até um chat pessoal com o aplicativo configurando o link profundo manualmente.

Compartilhar um link profundo para uma guia

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 guia. Por exemplo, se seu aplicativo de guia 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é a guia que se concentra no item específico.

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

microsoftTeams.shareDeepLink({ subEntityId: <subEntityId>, subEntityLabel: <subEntityLabel>, subEntityWebUrl: <subEntityWebUrl> })

Link profundo para guias da Estrutura do SharePoint

Os links profundos das guias da Estrutura do SharePoint (SPFx) permitem que os usuários naveguem diretamente para guias específicas em um site do SharePoint ou aplicativo do Teams. Isso aprimora a experiência do usuário, fornecendo acesso rápido a conteúdo e funcionalidades relevantes.

Parâmetros de consulta

Link profundo para abrir uma caixa de diálogo

Um link profundo de caixa de diálogo é uma serialização do TaskInfo objeto com dois outros detalhes, o APP_ID e, opcionalmente, o 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.

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

Link profundo para compartilhar conteúdo na fase de reunião

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

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

Link profundo para o painel lateral da reunião

Você pode gerar um link profundo para o painel lateral da reunião em uma reunião.

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 conforme mostrado no seguinte 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, confira o 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 está definido como false no link profundo.
• O link profundo é selecionado fora da janela ou componente da reunião.
• O link profundo não corresponde à reunião atual, por exemplo, se o link profundo for criado a partir de outra reunião.

Link profundo para invocar o Stageview

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

Práticas recomendadas

• Os links profundos só funcionarão corretamente se a guia tiver sido configurada usando a biblioteca v0.4 ou posterior, pois ela possui uma ID de entidade. Os links profundos para guias sem IDs de entidade ainda vão para a guia, mas não podem fornecer a sub'EntityId para a guia.
• No Microsoft Windows, o Teams não pode lidar com links profundos INTERNET_MAX_URL_LENGTH que excedem 2048 caracteres devido ao limite na API ShellExecuteEx do Windows.
• Ao criar um link profundo, verifique se o caminho para o cliente do Teams e outros metadados se encaixam dentro desse limite.
• Se o seu link profundo contiver dados grandes, inclua um identificador exclusivo no link que seu aplicativo pode usar para buscar os dados necessários do serviço de back-end.

Exemplo de código