Especificar os requisitos de tempo de execução do host do Microsoft 365 no manifesto do aplicativo

Qualquer aplicativo do Teams que use o manifesto versão 1.13 ou posterior está disponível em outros aplicativos de hub do Microsoft 365 (Outlook e Microsoft 365 Copilot) por padrão. No entanto, se o aplicativo também incluir recursos ainda sem suporte em determinados hubs, ele poderá ser carregado apenas parcialmente, resultando em experiências de usuário não planejadas.

Por exemplo, considere um aplicativo definido com o esquema de manifesto do aplicativo versão 1.17 e que inclua um bot e uma guia de configuração que represente as configurações do bot. O aplicativo seria carregado no Outlook e no Microsoft 365 Copilot, mas só exibiria a guia de configuração do bot para o usuário sem o próprio bot.

Para garantir que as experiências de aplicativo de alta qualidade alcancem sua base de usuários pretendida, especifique os requisitos de tempo de execução do aplicativo no manifesto do aplicativo. Isso permite que você personalize seu comportamento em hubs aplicáveis do Microsoft 365 ou omita-o da exibição em contextos que você não está pronto para dar suporte.

Especificar os requisitos de tempo de execução do aplicativo é útil em cenários como:

• Dependências unidirecionais: quando a única finalidade de um recurso de aplicativo é dar suporte a outro recurso em seu aplicativo, você pode garantir que ele só apareça se o recurso de aplicativo principal for carregado. Por exemplo, se seu aplicativo incluir uma guia e uma extensão de mensagem, e a guia funcionar como uma página de configurações para os usuários configurarem a funcionalidade de extensão de mensagem, você poderá especificar que a guia de configurações não seja carregada em hosts que não dão suporte à sua extensão de mensagem.

• Dependências mútuas: Quando seu aplicativo tem recursos específicos que devem ser carregados juntos para funcionar corretamente, você pode garantir que seu aplicativo esteja disponível apenas em hubs do Microsoft 365 que dão suporte a todos os recursos. Por exemplo, se os recursos de guia, bot e extensão de mensagem trabalharem juntos para dar suporte a um cenário de usuário principal em seu aplicativo, você poderá especificar que esses recursos sejam sempre carregados juntos ou não sejam carregados.

• Requisitos de capacidade: Quando seu aplicativo tiver recursos com requisitos de tempo de execução que não têm suporte em hubs específicos do Microsoft 365, você poderá garantir que esses recursos sejam omitidos perfeitamente (em vez de carregados, mas não funcionais) da experiência do aplicativo em execução nesses hubs. Por exemplo, se seu aplicativo incluir uma exibição de dashboard baseada em guias de itens que podem ser abertos como uma caixa de diálogo e cada caixa de diálogo contiver informações que são enviadas a um bot, você poderá especificar que as caixas de diálogo baseadas em bot são os principais recursos necessários para que seu aplicativo seja carregado em um determinado hub.

Suporte ao hub do Microsoft 365

Os seguintes aplicativos do hub do Microsoft 365 dão suporte à capacidade de especificar requisitos de tempo de execução no manifesto do aplicativo:

Especificar relações entre recursos do aplicativo (elementRelationshipSet)

Você pode especificar relações entre os recursos individuais do seu aplicativo incluindo um elementRelationshipSet no manifesto do aplicativo. Use esse objeto para especificar dependências unidirecionais e dependências mútuas entre os recursos do aplicativo.

Os seguintes recursos de manifesto do aplicativo podem ser especificados como tendo dependências unidirecionais ou mútuas:

• Guias: pessoal (staticTabs) e configurável (configurableTabs)
• Extensões de mensagem (composeExtensions), incluindo comandos individuais
• Bots (bots)

Cada funcionalidade do aplicativo é definida pela propriedade recém-introduzida, id, que mapeia para botId para bots, entityId para guias estáticas e id para guias configuráveis e extensões de mensagem. O Teams e outros hubs do Microsoft 365 dão suporte a aplicativos que contêm uma única guia configurável, uma única extensão de mensagem ou ambas. A id propriedade preparará seu aplicativo para o futuro se o suporte ao hub se expandir para acomodar várias instâncias desses recursos.

Dependências unidirecionais

Use a oneWayDependencies matriz para descrever casos em que um componente do seu aplicativo depende de outro componente. Para cada objeto na matriz, especifique o componente dependente (element) e o componente do qual ele depende (dependsOn). Você também pode especificar comandos individuais que exigem suporte para recursos específicos do aplicativo. Se esses recursos não tiverem suporte no host de runtime, eles não serão disponibilizados para o usuário (embora todos os outros comandos sejam executados).

O snippet JSON a seguir mostra comandos de extensão de mensagem específicos que têm uma dependência unidirecional em um bot:

    "elementRelationshipSet": {
      "oneWayDependencies" : [
        {
          "element" : {
            "name" : "composeExtensions",
            "id" : "composeExtension-id",
            "commandIds": ["exampleCmd1", "exampleCmd2"]
          },
          "dependsOn" : [
              {"name" : "bots", "id" : "bot-id"}
            ]
        }
      ]
    }

Dependências mútuas

Use a matriz para agrupar os mutualDependencies recursos do aplicativo que devem ser carregados juntos para dar suporte à função pretendida. Cada objeto na matriz representa um conjunto de recursos de aplicativo mutuamente dependentes. O snippet JSON a seguir mostra um bot, uma guia estática, uma extensão de mensagem e uma guia configurável que são mutuamente dependentes entre si:

    "elementRelationshipSet": {
      "mutualDependencies" : [
        [
                {"name" : "bots", "id" : "bot-id"}, 
                {"name" : "staticTabs", "id" : "staticTab-id"},
                {"name" : "composeExtensions", "id" : "composeExtension-id"},
                {"name" : "configurableTabs", "id": "configurableTab-id"}
        ]
      ]
    },

Especificar requisitos de tempo de execução para recursos específicos do aplicativo (requirementSet%)

Nas definições de recursos de aplicativos individuais, você pode especificar requisitos específicos de tempo de execução do TeamsJS usando um requirementSetarquivo . Isso garante que o recurso do aplicativo seja carregado apenas em hubs do Microsoft 365 com suporte para os recursos críticos do TeamsJS.

Os seguintes recursos do TeamsJS podem ser especificados como requisitos de tempo de execução para staticTabs, composeExtensionse bots:

• Caixas de diálogo baseadas em HTML (dialog.url)
• Caixas de diálogo baseadas em HTML para o Bot Framework (dialog.url.bot)
• Caixas de diálogo do Cartão Adaptável (dialog.adaptiveCard)
• Caixas de diálogos do Cartão Adaptável para Bot Framework (dialog.adaptiveCard.bot)

O snippet JSON a seguir mostra uma guia estática que requer que seu host dê suporte a caixas de diálogo HTML (chamadas de módulos de tarefa no TeamsJS v1.x) invocadas de guias e bots:

    "staticTabs": [
        {
            "entityId": "idForPage",
            "name": "Display name of tab",
            "contentUrl": "https://contoso.com/content?host=msteams",
            "contentBotId": "Specifies to the app that tab is an Adaptive Card Tab. You can either provide the contentBotId or contentUrl.",
            "websiteUrl": "https://contoso.com/content",
            "scopes": [
                "personal"
            ],
            "requirementSet": {
                "hostMustSupportFunctionalities": [
                  {"name": "dialogUrl"},
                  {"name": "dialogUrlBot"}
                ]
            }
        }
    ],

Exemplos de código

Confira também

• Esquema de manifesto do aplicativo Microsoft 365
• Estender aplicativos do Teams pelo Microsoft 365
• Caixas de diálogo de compilação
• Use o TeamsJS para diferenciar sua experiência com o aplicativo