Criar guias com Cartões Adaptáveis

  • Artigo

Aviso

As guias cartão adaptável não estão disponíveis no novo cliente do Teams. O cliente do Classic Teams deve ser preterido até 31 de março de 2024. Se seu aplicativo estiver usando guias de Cartão Adaptável, recomendamos recompilar a guia como uma guia baseada na Web. Para obter mais informações, confira Guias de compilação para o Teams.

Ao desenvolver uma guia usando o método tradicional, você pode ter estes problemas:

  • Considerações sobre HTML e CSS
  • Tempos de carregamento lentos
  • Restrições de iFrame
  • Manutenção e custos do servidor

Você pode criar guias de Cartão Adaptável no Teams. Em vez de inserir conteúdo da Web em um iFrame, você pode renderizar Cartões Adaptáveis em uma guia. Enquanto o front-end é renderizado com Cartões Adaptáveis, o back-end é alimentado por um bot. O bot é responsável por aceitar solicitações e responder adequadamente com o Cartão Adaptável renderizado.

Você pode criar suas guias com blocos de construção prontos para interface do usuário (UI) nativos na área de trabalho, na Web e em dispositivos móveis. Este artigo ajuda você a entender as alterações necessárias para serem feitas no manifesto do aplicativo. O artigo também identifica como a atividade de invocação solicita e envia informações na guia com Cartões Adaptáveis e seu efeito na caixa de diálogo modal (conhecida como módulo de tarefa no fluxo de trabalho TeamsJS v1.x).

A imagem a seguir mostra guias de build com Cartões Adaptáveis desktop e móvel:

A captura de tela mostra um exemplo do Cartão Adaptável renderizado em guias.

Pré-requisitos

Antes de começar a Cartões Adaptáveis para criar guias, você deve:

Alterações no manifesto do aplicativo

Aplicativos pessoais que renderizam guias devem incluir uma matriz staticTabs no manifesto do aplicativo. As guias cartão adaptável são renderizadas quando a propriedade contentBotId é fornecida na definição staticTab. As definições de guia estáticas devem conter uma contentBotId, especificando uma guia Cartão Adaptável ou uma contentUrl, especificando uma experiência típica de guia de conteúdo da Web hospedada.

Observação

A contentBotId propriedade está disponível no manifesto versão 1.9 ou posterior.

Forneça a propriedade contentBotId com a botId com a qual a guia Cartão Adaptável deve se comunicar. O entityId configurado para a guia Cartão Adaptável é enviado no parâmetro tabContext de cada solicitação de invocação e pode ser usado para diferenciar as Guias de Cartão Adaptável que são ativadas pelo mesmo bot. Para obter mais informações sobre outros campos de definição de guia estática, consulte esquema de manifesto.

A seguir está um exemplo de manifesto da guia Cartão Adaptável:

{
  "$schema": "https://raw.githubusercontent.com/OfficeDev/microsoft-teams-app-schema/preview/DevPreview/MicrosoftTeams.schema.json",
  "manifestVersion": "1.9",
  "id": "00000000-0000-0000-0000-000000000000",
  "version": "0.0.1",
  "developer": {
    "name": "Contoso",
    "websiteUrl": "https://contoso.yourwebsite.com",
    "privacyUrl": "https://contoso.yourwebsite.com/privacy.html",
    "termsOfUseUrl": "https://contoso.yourwebsite.com/terms.html"
  },
  "name": {
    "short": "Contoso",
    "full": "Contoso Home"
  },
  "description": {
    "short": "Add short description here",
    "full": "Add full description here"
  },
  "icons": {
    "outline": "icon-outline.png",
    "color": "icon-color.png"
  },
  "accentColor": "#D85028",
  "configurableTabs": [],
  "staticTabs": [
    {
      "entityId": "homeTab",
      "name": "Home",
      "contentBotId": "00000000-0000-0000-0000-000000000000",
      "scopes": ["personal"]
    },
    {
      "entityId": "moreTab",
      "name": "More",
      "contentBotId": "00000000-0000-0000-0000-000000000000",
      "scopes": ["personal"]
    }
  ],
  "connectors": [],
  "composeExtensions": [],
  "permissions": ["identity", "messageTeamMembers"],
  "validDomains": [
    "contoso.yourwebsite.com",
    "token.botframework.com"
  ]
}

Invocar atividades

A comunicação entre a guia Cartão Adaptável e o bot é feita por meio de invoke atividades. Cada atividade invoke tem um nome correspondente. Use o nome de cada atividade para diferenciar cada solicitação. tab/fetch e tab/submit são as atividades abordadas nesta seção.

Observação

  • Os bots precisam enviar todas as respostas para serviço URL. A URL do serviço é recebida como parte do conteúdo activity.
  • O tamanho da carga de invocação aumentou para 80 kb.

Buscar Cartão Adaptável para renderizar em uma guia

tab/fetch é a primeira solicitação de invocação que seu bot recebe quando um usuário abre uma guia Cartão Adaptável. Quando seu bot recebe a solicitação, ele envia uma resposta de continuação de guia ou uma resposta de autenticação de guia. A resposta continue inclui uma matriz para cartas, que é renderizada verticalmente na guia na ordem da matriz.

Observação

Para obter mais informações sobre a resposta de autenticação, consulte autenticação.

O código a seguir fornece exemplos de tab/fetch solicitação e resposta:

tab/fetch solicitação

// tab/fetch POST request: agents/{botId}/invoke
{
    "name": "tab/fetch",
    "value: {
        "tabContext": {
            "tabEntityId": "{tab_entity_id}"
        },
        "context": {
            "theme": "default"
            }
    },
    "conversation": {
        "id": "{generated_conversation_id}"
    },
    "imdisplayname": "{user_display_name}"
}

tab/fetch resposta

// tab/fetch **continue** POST response:
{
    "tab": {
        "type": "continue",
        "value": {
            "cards": [
                {
                    "card": adaptiveCard1,
                },
                {
                    "card": adaptiveCard2,
                },
                {
                    "card": adaptiveCard3
                }  
            ]
        },
    },
    "responseType": "tab"
}

Manipular envios do Cartão Adaptável

Depois que um Cartão Adaptável é renderizado na guia, ele pode responder às interações do usuário. Essa resposta é tratada pela solicitação tab/submit invocação.

Quando um usuário seleciona um botão na guia Cartão Adaptável, a solicitação tab/submit é disparada para o bot com os dados correspondentes por meio da função Action.Submit do Cartão Adaptável. Os dados do Cartão Adaptável estão disponíveis por meio da propriedade de dados da solicitação tab/submit. Você recebe uma das seguintes respostas à sua solicitação:

  • Um código de status HTTP 200 resposta sem corpo. Uma resposta 200 vazia não resulta em nenhuma ação executada pelo cliente.
  • A guia 200 padrão continua a resposta, conforme explicado em buscar Cartão Adaptável. Uma resposta de continuação de guia aciona o cliente para atualizar a guia Cartão Adaptável renderizada com os Cartões Adaptáveis fornecidos na matriz de cartões da resposta de continuação.

O código a seguir fornece exemplos de tab/submit solicitação e resposta:

tab/submit solicitação

// tab/submit POST request: agents/{botId}/invoke:
{
    "name": "tab/submit",
    "value": {
        "data": {
            "type": "tab/submit",
            //...<data properties>
            },
        "context": {
            "theme": "default"
            },
        "tabContext": {
            "tabEntityId": "{tab_entity_id}"
            },
        },
    "conversation": {
           "id": "{generated_conversation_id}" 
        },
    "imdisplayname": "{user_display_name}"
}

tab/submit resposta

//tab/fetch **continue** POST response:
{
    "tab": {
        "type": "continue",
        "value": {
            "cards": [
              {
                "card": adaptiveCard1,
                },
              {
                "card": adaptiveCard2,
                } 
            ]
        },
    },
    "responseType": "tab"
}

Entender o fluxo de trabalho da caixa de diálogo

As caixas de diálogo modais também usam Cartões Adaptáveis para invocar task/fetch e task/submit solicitações e respostas. Para obter mais informações, confira usando caixas de diálogo em bots do Microsoft Teams.

Com a introdução da guia Cartão Adaptável, há uma alteração em como o bot responde a uma solicitação task/submit. Se você estiver usando uma guia Cartão Adaptável, o bot responderá à solicitação task/submit de invocação com a resposta de continuação da guia padrão e fechará a caixa de diálogo. A guia Cartão Adaptável é atualizada renderizando a nova lista de cartões fornecidos na guia continuar corpo da resposta.

Invocar task/fetch

O código a seguir fornece exemplos de task/fetch solicitação e resposta:

task/fetch solicitação

// task/fetch POST request: agents/{botId}/invoke
{
    "name": "task/fetch",
    "value": {
        "data": {
            "type": "task/fetch"
        },
        "context": {
            "theme": "default",
        },
        "tabContext": {
            "tabEntityId": "{tab_entity_id}"
        }
    },
    "imdisplayname": "{user_display_name}",
    "conversation": {
        "id": "{generated_conversation_id}"
    } 
}

task/fetch resposta

// task/fetch POST response: agents/{botId}/invoke
{
    "task": {
        "value": {
            "title": "Ninja Cat",
            "height": "small",
            "width": "small",
            "card": {
                "contentType": "application/vnd.microsoft.card.adaptive",
                "content": adaptiveCard,
            }
        },
    "type": "continue"
    },
    "responseType": "task"
}

Invocar task/submit

O código a seguir fornece exemplos de task/submit solicitação e resposta:

task/submit solicitação

// task/submit POST request: agent/{botId}/invoke:
{
    "name": "task/submit",
    "value": {
        "data": {serialized_data_object},
        "context": {
            "theme": "default"
        },
    "tabContext": {
        "tabEntityId": "{tab_entity_id}"
        },
    },
    "conversation": {
        "id": "{generated_conversation_id}"
    },
    "imdisplayname": "{user_display_name}",
}

task/submit tipo de resposta da guia

// tab/fetch **continue** POST response: 
{
    "task":{
        "value": {
            "tab": {
                "type": "continue",
                "value": {
                    "cards": [
                        {
                            "card": adaptiveCard1
                        },
                        {
                            "card": adaptiveCard2
                        }
                    ]
                }
            }
        },
        "type": "continue"
    },
    "responseType": "task"
}

Autenticação

Nas seções anteriores, você viu que a maioria dos paradigmas de desenvolvimento pode ser estendida das solicitações e respostas da caixa de diálogo em solicitações de guia e respostas. Quando se trata de lidar com a autenticação, o fluxo de trabalho para a guia Cartão Adaptável segue o padrão de autenticação para extensões de mensagem. Para obter mais informações, consulte adicionar autenticação.

tab/fetch solicitações podem ter uma continuar ou uma resposta autenticação. Quando uma solicitação tab/fetch é disparada e recebe uma guia autenticação, a página de entrada é mostrada ao usuário.

Para obter um código de autenticação por meio de tab/fetch invocar

  1. Abra seu aplicativo. A página de entrada é exibida.

    Observação

    O logotipo do aplicativo é fornecido por meio da propriedade icon definida no manifesto do aplicativo. O título que aparece após o logotipo é definido na propriedade title retornada no corpo da resposta de autenticação da guia.

  2. Selecione Entrar. Você será redirecionado para a URL de autenticação fornecida na propriedade value do corpo da resposta auth.

  3. Uma janela pop-up será exibida. Essa janela pop-up hospeda sua página da Web usando a URL de autenticação.

  4. Depois de entrar, feche a janela. Um código de autenticação inicial é enviado ao cliente do Teams.

  5. Em seguida, o cliente do Teams emiti novamente a solicitação tab/fetch para seu serviço, que inclui o código de autenticação fornecido pela página da Web hospedada.

tab/fetch fluxo de dados de autenticação

A imagem a seguir fornece uma visão geral de como o fluxo de dados de autenticação funciona para uma chamada tab/fetch.

A captura de tela mostra o exemplo de fluxo de auth da Guia de Cartão Adaptável.

tab/fetch resposta de autenticação

O código a seguir fornece um exemplo de tab/fetch resposta de autenticação:

// tab/auth POST response (openURL)
{
    "tab": {
        "type": "auth",
        "suggestedActions":{
            "actions":[
                {
                    "type": "openUrl",
                    "value": "https://example.com/auth",
                    "title": "Sign in to this app"
                }
            ]
        }
    }
}

Exemplo

O código a seguir mostra um exemplo de solicitação reemitida:

{
    "name": "tab/fetch",
    "type": "invoke",
    "timestamp": "2021-01-15T00:10:12.253Z",
    "channelId": "msteams",
    "serviceUrl": "https://smba.trafficmanager.net/amer/",
    "from": {
        "id": "{id}",
        "name": "John Smith",
        "aadObjectId": "00000000-0000-0000-0000-000000000000"
    },
    "conversation": {
        "tenantId": "{tenantId}",
        "id": "tab:{guid}"
    },
    "recipients": {
        "id": "28:00000000-0000-0000-0000-000000000000",
        "name": "ContosoApp"
    },
    "entities": [
        {
            "locale": "en-us",
            "country": "US",
            "platform": "Windows",
            "timezone": "America/Los_Angeles",
            "type": "clientInfo"
        }
    ],
    "channelData": {
        "tenant": { "id": "00000000-0000-0000-0000-000000000000" },
        "source": { "name": "message" }
    },
    "value": {
        "tabContext": { "tabEntityId": "homeTab" },
        "state": "0.43195668034524815"
    },
    "locale": "en-US",
    "localTimeZone": "America/Los_Angeles"
}

Exemplo de código

Nome de exemplo Descrição .NET Node.js Manifesto
Mostrar Cartões Adaptáveis na guia Teams Código de exemplo de guia do Microsoft Teams, que demonstra como mostrar Cartões Adaptáveis no Teams. View View View

Guias passo a passo

Siga o guia passo a passo para criar guia com Cartões Adaptáveis.

Próxima etapa

Tabs link unfurling and Stageview

Confira também