Referência herdada de cartão de mensagens acionáveis

Os cartões devem ser fáceis de ler e dar informações claras que os usuários podem decifrar com rapidez e tomar decisões quando for apropriado. Dessa forma, a orientação principal para a criação de um ótimo cartão é "conteúdo em primeiro lugar", ou seja, os cartões devem ir diretamente ao ponto e é importante minimizar o uso de qualquer coisa que distraia como ícones ou cores personalizadas.

Designer de Mensagens Acionáveis

Pronto para experimentar o design do cartão? Aceda à Designer Mensagem Acionável que lhe permite ver o aspeto que o seu card irá ter à medida que edita o payload JSON associado.

Diretrizes de design

Formatação de texto

Todos os campos de texto em um cartão e as seções correspondentes podem ser formatados usando o Markdown. Damos suporte ao Markdown básico.

Usando seções

Se o seu cartão representa uma única "entidade", você não precisará usar seções. Ou seja, as seções dão suporte ao conceito de uma "atividade" que muitas vezes é uma boa maneira de representar dados em um cartão.

Se o seu cartão representar várias "entidades" ou for, por exemplo, um resumo de uma fonte de notícias específica, você certamente precisará usar várias seções, uma para cada "entidade".

Campos do cartão

Campos de seção

Campo	Tipo	Descrição
title	Cadeia de caracteres	A propriedade title de uma seção é exibida em uma fonte de destaque embora menos destacada que o título do cartão. Ela foi criada para apresentar a seção e resumir seu conteúdo, de maneira semelhante a como a propriedade do título do cartão pretende resumir o cartão inteiro. Use um título curto, evite frases longas. Mencione o nome da entidade que está sendo referenciada no título. Não use hiperlinks (via Markdown) no título.
startGroup	Booliano	Quando definido como true, a propriedade startGroup marca o início de um grupo lógico de informações. Normalmente, as seções com startGroup definidas como true serão separadas visualmente de elementos de cartão anterior. Por exemplo, o Outlook usa uma linha de separação horizontal sutil. Use startGrouppara separar seções que representam objetos diferentes; por exemplo, vários tweets em um resumo.
activityImage activityTitle activitySubtitle activityText	Cadeia de caracteres	Essas quatro propriedades formam um grupo lógico. activityTitle, activitySubtitle e activityText serão exibidos junto com activityImage, usando um layout apropriado para o fator de forma do dispositivo no qual o cartão será visualizado. Por exemplo, no Outlook na Web, activityTitle, activitySubtitle e activityText são exibidos à direita do activityImage, usando um layout de duas colunas: Use os campos de atividade para cenários como: Alguém fez algo Use activityImage para exibir a imagem dessa pessoa. Use activityTitle para resumir o que ele fez. Seja sucinto e direto ao assunto. Use activitySubtitle para mostrar, por exemplo, a data e a hora em que a ação foi realizada ou o identificador da pessoa. activitySubtitle será apresentado em uma fonte mais discreta Não inclua informações essenciais Não inclua chamadas para ação Evite formatação de Markdown Use activityText para fornecer detalhes sobre a atividade. Use Markdown simples para enfatizar palavras ou links para fontes externas Não inclua chamadas para ação Um resumo de artigo de notícias Use activityImage para exibir a imagem associada ao artigo Use activitySubtitle para exibir a data e a hora em que o artigo foi lançado originalmente Use activityText para exibir o resumo real
heroImage	Image	Use heroImage para tornar uma imagem a parte central do cartão. Por exemplo, um tweet que contém uma imagem deverá centralizar e destacar essa imagem: heroImage também pode ser usado para adicionar uma faixa ao seu cartão, como a faixa "TINYPulse – Engage" abaixo:
text	Cadeia de caracteres	A propriedade text da seção é muito semelhante à propriedade text do cartão. Ela pode ser usada para o mesmo fim.
facts	Matriz de pares de nome/valor	Fatos são um componente muito importante de uma seção. Muitas vezes contêm as informações que realmente interessam ao utilizador. Fatos são exibidos de tal forma que podem ser lidos de maneira rápida e eficiente. Por exemplo, no Outlook na Web, fatos são apresentados em um layout de duas colunas, com nomes de fato apresentados em uma fonte um pouco mais destacada: Há muitos usos para fatos. Alguns cenários: Um bug foi criado ID do bug: 1234 Aberto por: Manuela Torres Atribuído a: Donato Dias Relatório de uso do aplicativo Nome do aplicativo: Aplicativo Contoso CRM Período: 1 de agosto de 2016 a 30 de setembro de 2016 Quantidade de usuários: 542 Número de sessões: 2056 Tempo médio gasto no aplicativo: 76 segundos Aprovação de despesas Enviado por: Pradeep Gupta Data de envio: 21 de outubro de 2016 Valor total: US$ 1.426,95 Use fatos em vez de incorporar informações importantes dentro da propriedade de texto do cartão ou seção. Use nomes curtos de fato. Evite usar valores de fato muito longos. Evite usar formatação de Markdown para nomes e valores de fato. Deixe os fatos serem apresentados conforme o desejado para terem mais impacto. No entanto, use Markdown para links apenas em valores de fato. Por exemplo, se um fato fizer referência a um documento externo, use o valor desse fato como um link para o documento. Não adicione um fato sem um propósito real. Por exemplo, um fato de que sempre terá o mesmo valor em todos os cartões não é interessante e é um desperdício de espaço.
images	Matriz de objetos de imagem	A propriedade images permite a inclusão de uma galeria de fotos dentro de uma seção. Essa galeria sempre será exibida de uma maneira fácil de consumir independentemente do fator de forma do dispositivo em que estiver sendo exibido. Por exemplo, no Outlook na Web, imagens podem ser exibidas como uma faixa horizontal de miniaturas com controles permitindo percorrer o conjunto se ele não couber na tela. Em dispositivos móveis, as imagens podem ser exibidas como uma única miniatura, com o usuário podendo passar o dedo para percorrer a coleção.
potentialAction	Matriz de Actions	Um conjunto de ações que pode ser chamado nesta seção. Consulte Ações.

Objeto de imagem

Define uma imagem como usada pelas propriedades heroImage e images de uma seção.

Ações

Os cartões são muito poderosos no sentido de que permitem que os usuários realizem ações rápidas sem sair do cliente de email. Quando estiver criando cartões, torne-os acionáveis, pois isso aumentará a produtividade e o envolvimento do usuário.

As ações são especificadas usando a propriedade potentialAction que está disponível no próprio cartão e em cada seção. Há quatro tipos de ações:

• OpenUri
• HttpPOST
• ActionCard
• InvokeAddInCommand

Pode haver no máximo quatro ações (seja qual for o tipo) em uma coleção potentialAction.

• Inclua ações que terão o maior impacto para o usuário final, como as mais repetitivas.
• Não adicione quatro ações só porque você pode. Em muitos casos, menos ações gerarão uma melhor experiência.
• Não crie seus cartões com a intenção de substituir um aplicativo externo. Cartões servem para complementar esses aplicativos, não para substituí-los.

Ação OpenUri

Abre um URI em um navegador ou aplicativo separado.

Embora links possam ser obtidos por meio de Markdown, uma ação OpenUri tem a vantagem de permitir que você especifique diferentes URIs para diferentes sistemas operacionais, o que permite abrir o link em um aplicativo em dispositivos móveis.

• Use uma ação OpenUri em vez de um link no Markdown se houver uma vantagem clara para os usuários abrirem o link em um aplicativo no dispositivo móvel.
• Inclua pelo menos uma ação OpenUri para exibir a entidade no aplicativo externo de origem.
• Torne a ação OpenUri o último elemento na coleção potentialAction.

              
              "destinos": [
    { "os": "default", "uri": "https://yammer.com/.../123" },
    { "os": "iOS", "uri": "yammer://u/123" },
    { "os": "android", "uri": "yammer://u/123" },
    { "os": "windows", "uri": "yammer://u/123" }
]

Ação de HttpPOST

Faz uma chamada para um serviço da Web externo.

Quando uma ação HttpPOST for executada, será feita uma solicitação de POST para a URL no campo target e o serviço de destino precisa autenticar o chamador. Isso pode ser feito de várias maneiras, incluindo por meio de um token de finalidade limitado inserido na URL de destino. Para obter mais informações e ajuda sobre como escolher o mecanismo de segurança que funciona melhor para sua situação específica, consulte Requisitos de segurança para mensagens acionáveis.

Cabeçalho

O objeto Header é um par nome/valor que representa um cabeçalho HTTP.

Reportando o sucesso ou a falha da execução de uma ação

As ações HttpPOST podem incluir o cabeçalho de HTTP CARD-ACTION-STATUS na sua resposta. Esse cabeçalho deve conter o texto que indica o resultado da execução da ação, se ela tiver êxito ou falhar.

O valor do cabeçalho será exibido de forma consistente em uma área reservada do cartão. Ele também é salvo com o cartão para que possa ser exibido no futuro, para que os usuários possam ser lembrados das ações que já foram executadas em um determinado cartão.

Cartões atualizados

Cartões atualizados são um mecanismo muito poderoso que permite que as ações HttpPOST atualizem o cartão completamente na hora em que a ação é concluída com sucesso. Há muitos cenários que se beneficiam de cartões atualizados:

• Cenário de aprovação (por exemplo, relatório de despesas)
  • Assim que a solicitação é aprovada ou rejeitada, o cartão é atualizado para remover as ações de aprovar/recusar e atualizar seu conteúdo para refletir o fato de que foi aprovado ou recusado
• Status da tarefa
  • Quando uma ação é executada em uma tarefa, por exemplo, a definição de sua data de conclusão, o cartão é atualizado para incluir a data de conclusão atualizada em seus fatos
• Pesquisa
  • Assim que a pergunta é respondida, o cartão é atualizado para que:
    • Ele não permita mais que o usuário responda
    • Ele mostre o status atualizado, por exemplo, "Obrigado por responder a esta pesquisa" junto com a resposta real do usuário
    • Você também pode incluir uma nova ação OpenUri que permite ao usuário consultar a pesquisa online

Para atualizar um cartão como resultado de uma ação HttpPOST, um serviço precisará fazer o seguinte:

• Inclua a carga JSON do novo cartão no corpo da resposta para a solicitação POST de HTTP recebida.
• Adicione o cabeçalho CARD-UPDATE-IN-BODY: true de HTTP à resposta, para informar o cliente receptor que ele deve analisar o corpo da resposta e extrair um novo cartão (isso é para evitar o processamento desnecessário quando nenhum cartão atualizado é incluído.)

Ação ActionCard

Apresenta a interface do usuário adicional que contém uma ou mais Entradas, junto com as ações associadas que podem ser tipos OpenUri ou HttpPOST.

Use uma ação ActionCard se uma ação exigir entrada adicional do usuário. Alguns cenários:

• Respondendo a uma pesquisa
• Adicionando um comentário em um bug
• Fornecendo uma justificativa para recusar um relatório de despesas

Por padrão, uma ação ActionCard será representada como um botão ou link na interface do usuário do cartão. Quando for clicado, esse botão exibirá uma parte adicional da interface do usuário que contém as entradas e as ações definidas no cartão de ação.

Se houver uma única ação ActionCard em uma coleção potentialAction, o Outlook representará essa ação "previamente expandida", por exemplo, as entradas e as ações serão imediatamente visíveis.

ActionCard de exemplo

{
  "@type": "ActionCard",
  "name": "Comment",
  "inputs": [
    {
      "@type": "TextInput",
      "id": "comment",
      "isMultiline": true,
      "title": "Input's title property"
    }
  ],
  "actions": [
    {
      "@type": "HttpPOST",
      "name": "Action's name prop.",
      "target": "https://yammer.com/comment?postId=123",
      "body": "comment={{comment.value}}"
    }
  ]
}

Entradas

Três tipos de entradas são suportados: TextInput, DateInput e MultichoiceInput.

Campos comuns

Os campos a seguir são comuns a todos os tipos de entrada.

TextInput

Use esse tipo de entrada quando os usuários precisarem fornecer texto livre, por exemplo, a resposta a uma pergunta da pesquisa.

TextInput de exemplo

{
  "@type": "TextInput",
  "id": "comment",
  "isMultiline": true,
  "title": "Input's title property"
}

DateInput

Use esse tipo de entrada quando precisar que os usuários forneçam data e/ou hora, por exemplo, a data de conclusão de uma tarefa.

DateInput de exemplo

{
  "@type": "DateInput",
  "id": "dueDate",
  "title": "Input's title property"
}

MultichoiceInput

Use esse tipo de entrada quando precisar que os usuários selecionem em uma lista de opções predefinidas, como o status de um bug, sim/não/talvez etc.

Campo	Tipo	Descrição
choices	Matriz de pares de nome/valor	Define os valores que podem ser selecionados para a entrada de múltipla escolha.
isMultiSelect	Booliano	Se for definido como true, indica que o usuário pode selecionar mais de uma opção. As opções especificadas serão exibidas como uma lista de caixas de seleção. O valor padrão é false.
style	Cadeia de caracteres (normal(padrão ou expanded))	Quando isMultiSelect for false, a configuração da propriedade style para expanded instruirá o aplicativo host para experimentar e exibir todas as opções na tela, normalmente usando um conjunto de botões de opção.

MultichoiceInput compacto de exemplo

{
  "@type": "MultichoiceInput",
  "id": "list",
  "title": "Pick an option",
  "choices": [
    { "display": "Choice 1", "value": "1" },
    { "display": "Choice 2", "value": "2" },
    { "display": "Choice 3", "value": "3" }
  ]
}

MultichoiceInput de seleção múltipla de exemplo

{
  "@type": "MultichoiceInput",
  "id": "list",
  "title": "Pick an option",
  "isMultiSelect": true,
  "choices": [
    { "display": "Choice 1", "value": "1" },
    { "display": "Choice 2", "value": "2" },
    { "display": "Choice 3", "value": "3" }
  ]
}

MultichoiceInput expandido de exemplo

{
  "@type": "MultichoiceInput",
  "id": "list",
  "title": "Pick an option",
  "style": "expanded",
  "choices": [
    { "display": "Choice 1", "value": "1" },
    { "display": "Choice 2", "value": "2" },
    { "display": "Choice 3", "value": "3" }
  ]
}

Substituição do valor de entrada

O valor de uma entrada pode ser referenciado no corpo de uma HttpPOST ação. Quando um valor de entrada é referenciado, ele é substituído pelo valor real da entrada logo antes de a ação ser executada.

Para fazer referência ao valor de uma entrada, use o seguinte formato:

{{<id of input>.value}}

Exemplo de substituição do valor de entrada

{
  "@type": "ActionCard",
  "name": "Comment",
  "inputs": [
    {
      "@type": "TextInput",
      "id": "comment",
      "isMultiline": true,
      "title": "Input's title property"
    }
  ],
  "actions": [
    {
      "@type": "HttpPOST",
      "name": "Action's name prop.",
      "target": "https://yammer.com/comment?postId=123",
      "body": "comment={{comment.value}}"
    }
  ]
}

Ação InvokeAddInCommand

Abre um painel de tarefas do suplemento do Outlook. Se o suplemento não estiver instalado, o usuário será solicitado a instalar o suplemento com um único clique.

Quando uma ação InvokeAddInCommand é executada, o Outlook primeiro verifica se o suplemento solicitado está instalado e ativado para o usuário. Se ele não estiver, o usuário será notificado de que a ação requer o suplemento e é capaz de instalar e ativar o suplemento com um único clique. O Outlook abre o , tornando qualquer contexto de inicialização especificado pela ação disponível para o suplemento.

Confira mais informações em Invocar um suplemento do Outlook de uma mensagem acionável.

InvokeAddInCommand de exemplo

{
  "@type": "InvokeAddInCommand",
  "name": "Invoke My Add-in",
  "addInId": "527104a1-f1a5-475a-9199-7a968161c870",
  "desktopCommandId": "show ",
  "initializationContext": {
    "property1": "Hello world",
    "property2": 5,
    "property3": true
  }
}

Exemplos de cartão

Trello

O cartão é criado em uma lista:

Veja como esse cartão é criado:

Aqui está o mesmo cartão com a ação Adicionar um comentárioexpandida:

Veja como a ação Adicionar um comentário é construída:

JSON do Trello

{
  "summary": "Card \"Test card\"",
  "themeColor": "0078D7",
  "title": "Card created: \"Name of card\"",
  "sections": [
    {
      "activityTitle": "David Claux",
      "activitySubtitle": "9/13/2016, 3:34pm",
      "activityImage": "https://connectorsdemo.azurewebsites.net/images/MSC12_Oscar_002.jpg",
      "facts": [
        {
          "name": "Board:",
          "value": "Name of board"
        },
        {
          "name": "List:",
          "value": "Name of list"
        },
        {
          "name": "Assigned to:",
          "value": "(none)"
        },
        {
          "name": "Due date:",
          "value": "(none)"
        }
      ],
      "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat."
    }
  ],
  "potentialAction": [
    {
      "@type": "ActionCard",
      "name": "Set due date",
      "inputs": [
        {
          "@type": "DateInput",
          "id": "dueDate",
          "title": "Select a date"
        }
      ],
      "actions": [
        {
          "@type": "HttpPOST",
          "name": "OK",
          "target": "https://..."
        }
      ]
    },
    {
      "@type": "ActionCard",
      "name": "Move",
      "inputs": [
        {
          "@type": "MultichoiceInput",
          "id": "move",
          "title": "Pick a list",
          "choices": [
            { "display": "List 1", "value": "l1" },
            { "display": "List 2", "value": "l2" }
          ]
        }
      ],
      "actions": [
        {
          "@type": "HttpPOST",
          "name": "OK",
          "target": "https://..."
        }
      ]
    },
    {
      "@type": "ActionCard",
      "name": "Add a comment",
      "inputs": [
        {
          "@type": "TextInput",
          "id": "comment",
          "isMultiline": true,
          "title": "Enter your comment"
        }
      ],
      "actions": [
        {
          "@type": "HttpPOST",
          "name": "OK",
          "target": "https://..."
        }
      ]
    },
    {
      "@type": "OpenUri",
      "name": "View in Trello",
      "targets": [
        { "os": "default", "uri": "https://..." }
      ]
    }
  ]
}

Twitter

Aqui está um exemplo de um cartão de resumo do Twitter:

Veja como esse cartão é criado:

JSON do Twitter

{
  "themeColor": "0078D7",
  "sections": [
    {
      "activityTitle": "**Elon Musk**",
      "activitySubtitle": "@elonmusk - 9/12/2016 at 5:33pm",
      "activityImage": "https://pbs.twimg.com/profile_images/782474226020200448/zDo-gAo0.jpg",
      "activityText": "Climate change explained in comic book form by xkcd xkcd.com/1732"
    },
    {
      "activityTitle": "**Mark Knopfler**",
      "activitySubtitle": "@MarkKnopfler - 9/12/2016 at 1:12pm",
      "activityImage": "https://pbs.twimg.com/profile_images/378800000221985528/b2ebfafca6fd7b565fdf3bf4ccdb4dc9.jpeg",
      "activityText": "Mark Knopfler features on B.B King's all-star album of Blues greats, released on this day in 2005..."
    }
  ]
}

Email acionável

Aqui está um exemplo de corpo de email HTML com um cartão de mensagem inserido.

<html>
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  <script type="application/ld+json">{
    "@context": "https://schema.org/extensions",
    "@type": "MessageCard",
    "originator": "",
    "hideOriginalBody": "true",
    "themeColor": "0072C6",
    "title": "Visit the Outlook Dev Portal",
    "text": "Click **Learn More** to learn more about Actionable Messages!",
    "potentialAction": [
      {
        "@type": "ActionCard",
        "name": "Send Feedback",
        "inputs": [
          {
            "@type": "TextInput",
            "id": "feedback",
            "isMultiline": true,
            "title": "Let us know what you think about Actionable Messages"
          }
        ],
        "actions": [
          {
            "@type": "HttpPOST",
            "name": "Send Feedback",
            "isPrimary": true,
            "target": "http://..."
          }
        ]
      },
      {
        "@type": "OpenUri",
        "name": "Learn More",
        "targets": [
          { "os": "default", "uri": "https://video2.skills-academy.com/outlook/actionable-messages" }
        ]
      }
    ]
  }
  </script>
</head>
<body>
Visit the <a href="https://video2.skills-academy.com/outlook/actionable-messages">Outlook Dev Portal</a> to learn more about Actionable Messages.
</body>
</html>