Referencia de la tarjeta de mensaje que requiere acción heredada

Las tarjetas están diseñadas para ofrecer una información que se pueda leer de manera fácil y rápida y que los usuarios pueden descifrar y tratar de inmediato cuando corresponda. El principio básico para diseñar tarjetas perfectas es "el contenido antes que el aspecto" (content over chrome), que significa que las tarjetas deben ser directas y deben minimizar el uso de cualquier elemento que pueda distraer, como los iconos o los colores personalizados.

Mensaje accionable Designer

¿Está a punto para experimentar con el diseño de las tarjetas? Vaya al Designer de mensajes accionables, que le permite ver el aspecto de la tarjeta al editar la carga JSON asociada.

Directrices de diseño

Formato de texto

Se puede dar formato a todos los campos de texto de una tarjeta y a su sección con Markdown. Se proporciona un soporte de Markdown básico.

Uso de las secciones

Si la tarjeta representa una única "entidad", es posible que no le haga falta usar ninguna sección. Dicho esto, las secciones admiten el concepto de una "actividad", que suele ser una buena forma de representar datos en una tarjeta.

Si la tarjeta representa varias "entidades" o es, por ejemplo, un resumen de una fuente periodística determinada, sin duda querrá usar varias secciones, una por cada "entidad".

Campos de la tarjeta

Campos de una sección

Campo	Tipo	Descripción
title	String	La propiedad title de una sección se muestra con una fuente que destaca, aunque no tan destacada como el título de la tarjeta. Está diseñada para presentar la sección y resumir su contenido, de forma similar a la propiedad title de la tarjeta, que sirve para resumir toda la tarjeta. Escriba un título corto; no escriba una frase larga. Mencione el nombre de la entidad a la que se hace referencia en el título. No use hipervínculos (a través de Markdown) en el título.
startGroup	Boolean	Si se establece en true, la propiedad startGroup marca el inicio de un grupo lógico de información. Las secciones que tienen startGroup establecido en true suelen estar separadas visualmente de los elementos anteriores de la tarjeta. Por ejemplo, Outlook usa una línea de separación horizontal sutil. UsestartGroup para separar las secciones que representan objetos diferentes; por ejemplo, varios tweets en un resumen.
activityImage activityTitle activitySubtitle activityText	Cadena	Estas cuatro propiedades forman un grupo lógico. activityTitle, activitySubtitle y activityText se mostrarán junto a activityImage, con un diseño apropiado para el factor de forma del dispositivo en el que se visualiza la tarjeta. En Outlook en la web, por ejemplo, activityTitle, activitySubtitle y activityText se muestran a la derecha de activityImage, con un diseño de dos columnas: Use los campos de actividad para escenarios como: Alguien ha hecho algo Use activityImage para mostrar la imagen de esa persona. Use activityTitle para resumir lo que ha hecho. Sea breve y conciso. Use activitySubtitle para mostrar, por ejemplo, la fecha y hora en la que se ha efectuado la acción, o bien el identificador de la persona. activitySubtitle se procesará con una fuente más tenue No incluya información esencial No incluya llamadas a la acción Evite el formato de Markdown Use activityText para proporcionar la información detallada de la actividad. Use un formato Markdown simple para resaltar palabras o crear vínculos a fuentes externas No incluya llamadas a la acción Un resumen de un artículo periodístico Use activityImage para mostrar la imagen asociada al artículo Use activitySubtitle para mostrar la fecha y la hora en la que se publicó el artículo Use activityText para mostrar el resumen real
heroImage	Image (Imagen)	Use heroImage para convertir una imagen en el eje de la tarjeta. Por ejemplo, en un tweet que contenga una imagen se querrá poner esa imagen centrada y en primer plano: heroImage también se puede usar para agregar un banner a la tarjeta, como el banner "TINYPulse – Engage", que se muestra a continuación:
text	String	La propiedad text de la sección es muy parecida a la propiedad text de la tarjeta. Se puede usar para el mismo propósito.
facts	Matriz de pares nombre-valor	Los hechos representan un componente muy importante de una sección. A menudo contienen la información que realmente importa al usuario. Los hechos se muestran de tal manera que se pueden leer de forma rápida y eficiente. Por ejemplo, en Outlook en la web, los hechos se presentan con un diseño de dos columnas, con los nombres de los hechos representados con una fuente un poco más destacada: Los hechos se emplean para distintas finalidades. Algunos escenarios: Creación de un error Id. de error: 1234 Abierto por: Adele Saavedra Asignado a: Alberto Tercedor Informe de uso de aplicación Nombre de la aplicación: Aplicación CRM de Contoso Período: del 1 de agosto de 2016 al 30 de septiembre de 2016 Número de usuarios: 542 Número de sesiones: 2056 Promedio de tiempo transcurrido en la aplicación: 76 segundos Aprobación de gastos Enviado por: Pradeep Gupta Fecha de envío: 21 de octubre de 2016 Importe total: 1.426,95 $ Use los hechos en lugar de insertar información importante dentro de la propiedad de texto de la tarjeta o de la sección. Use nombres cortos para los hechos. Evite que los valores de los hechos sean demasiado largos. Evite usar el formato de Markdown para los nombres y los valores de los hechos. Los hechos se deben representar según lo previsto, puesto que es así como tendrán un mayor impacto. Use Markdown solo para los vínculos de los valores de hechos. Por ejemplo, si un hecho hace referencia a un documento externo, convierta el valor de este hecho en un vínculo al documento. No agregue hechos sin un propósito real. Por ejemplo, un hecho que siempre tendría el mismo valor en todas las tarjetas no es interesante y supone un malgasto de espacio.
images	Matriz de objetos de imagen	La propiedad images permite incluir una galería de fotografías dentro de una sección. La galería de fotografías siempre se mostrará de una forma que resulte fácil de usar, con independencia del factor de forma del dispositivo en el que se está visualizando. Por ejemplo, en Outlook en la web, las imágenes podrían mostrarse como una franja horizontal de miniaturas, donde los controles permiten desplazarse por la colección si no cabe todo en la pantalla. En los dispositivos móviles, las imágenes se podrían mostrar como miniaturas; además, el usuario puede pasar el dedo por la colección para desplazarse.
potentialAction	Matriz de Actions	Una colección de acciones que se pueden invocar en esta sección. Consulte Acciones.

Objeto de imagen

Define una imagen usada por las propiedades heroImage e images de una sección.

Acciones

Las tarjetas son muy eficaces en el sentido de que permiten que los usuarios tomen acciones rápidas sin salir de su cliente de correo electrónico. A la hora de diseñar tarjetas, considere la posibilidad de hacerlas accionables, con lo que aumentará la productividad y la interacción del usuario.

Las acciones se especifican con la propiedad potentialAction, que está disponible en la propia tarjeta y en cada sección. Existen cuatro tipos de acción:

• OpenUri
• HttpPOST
• ActionCard
• InvokeAddInCommand

Puede haber un máximo de 4 acciones, independientemente del tipo que sean, en una colección potentialAction.

• Incluya acciones que tengan el mayor impacto para el usuario final, como las más repetitivas.
• No agregue 4 acciones porque sí. En muchos casos, llevar a cabo menos acciones implica una mejor experiencia.
• No elabore sus tarjetas solo para reemplazar una aplicación externa. Las tarjetas están diseñadas para complementar dichas aplicaciones, no para reemplazarlas.

Acción OpenUri

Abre un identificador URI en un explorador o aplicación independiente.

Aunque los vínculos se pueden crear con Markdown, las acciones OpenUri tienen la ventaja de que le permiten especificar distintos identificadores URI para distintos sistemas operativos, con lo que puede abrir el vínculo en una aplicación de un dispositivo móvil.

• Considere la posibilidad de usar una acción OpenUri en lugar de usar un vínculo en Markdown si a los usuarios les resultará mucho más fácil abrir el vínculo en una aplicación de su dispositivo móvil.
• Incluya al menos una acción OpenUri para ver la entidad en la aplicación externa de la que procede.
• Efectúe la acción OpenUri en último lugar en la colección potentialAction.

              
              "targets": [
    { "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" }
]

Acción HttpPOST

Realiza una llamada a un servicio web externo.

Al ejecutar una acción HttpPOST, se efectúa una solicitud POST en la dirección URL en el campo target y el servicio de destino necesita autenticar al llamador. Esto se puede hacer de varias formas, también con un token de objetivo limitado insertado en la dirección URL de destino. Para obtener más información y ayuda sobre cómo elegir el mecanismo de seguridad que mejor se ajuste a su escenario concreto, consulte Security requirements for actionable messages (Requisitos de seguridad de los mensajes accionables).

Encabezado

El objeto Header es un par de nombre y valor que representa un encabezado HTTP.

Notificar la ejecución correcta o incorrecta de una acción

Las acciones HttpPOST pueden incluir el encabezado HTTP CARD-ACTION-STATUS en su respuesta. Este encabezado está diseñado para contener texto que indique el resultado de la ejecución de la acción (si se ha efectuado correctamente o no).

El valor del encabezado se mostrará de forma coherente en un área reservada de la tarjeta. También se guarda con la tarjeta para que se pueda mostrar más adelante; de esta manera, se avisa a los usuarios de las acciones que ya se han ejecutado en una tarjeta determinada.

Tarjetas de actualización

Las tarjetas de actualización son un mecanismo muy eficaz con el que las acciones HttpPOST pueden actualizar completamente la tarjeta sobre la marcha a medida que se lleva a cabo la acción. Existen muchos escenarios que se benefician de las tarjetas de actualización:

• Escenario de aprobación (por ejemplo, informe de gastos)
  • Una vez que se aprueba o rechaza la solicitud, la tarjeta se actualiza para quitar las acciones de aprobación o rechazo y actualizar su contenido para que refleje que se ha aprobado o rechazado
• Estado de la tarea
  • Cuando se lleva a cabo una acción en una tarea, como la configuración de la fecha de vencimiento, la tarjeta se actualiza para incluir la fecha de vencimiento actualizada en los hechos
• Encuesta
  • Una vez que se ha contestado a la pregunta, la tarjeta se actualiza para que:
    • El usuario ya no pueda responder
    • Muestre el estado actualizado (por ejemplo, "Gracias por responder a esta encuesta"), junto con la respuesta real del usuario
    • Incluya potencialmente una nueva acción OpenUri que permita al usuario consultar la encuesta en línea

Para actualizar una tarjeta como consecuencia de una acción HttpPOST, debe haber un servicio que haga lo siguiente:

• Incluir la carga JSON de la nueva tarjeta en el cuerpo de la respuesta a la solicitud HTTP POST que recibió.
• Agregar el encabezado HTTP CARD-UPDATE-IN-BODY: true a la respuesta para que el cliente receptor sepa que debe analizar el cuerpo de la respuesta y extraer una tarjeta nueva (esto se hace para evitar un procesamiento innecesario si no se incluye ninguna tarjeta de actualización).

Acción ActionCard

Presenta una interfaz de usuario adicional que contiene una o varias entradas, junto con las acciones asociadas, que pueden ser de tipo OpenUri o HttpPOST.

Use una acción ActionCard si una determinada acción requiere que el usuario efectúe una entrada adicional. Algunos escenarios:

• Responder a una encuesta
• Agregar un comentario a un error
• Proporcionar una justificación al rechazo de un informe de gastos

De forma predeterminada, las acciones ActionCard se representarán en forma de botón o de vínculo en la interfaz de usuario de la tarjeta. Al hacer clic en él, dicho botón mostrará un fragmento adicional de la interfaz de usuario que contiene las entradas y las acciones definidas en la tarjeta de la acción.

Si solo hay una acción ActionCard en una colección potentialAction, Outlook representará dicha acción de manera "preexpandida" (por ejemplo, sus entradas y acciones serán visibles inmediatamente).

Ejemplo ActionCard

{
  "@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

Se admiten tres tipos de entradas: TextInput, DateInput y MultichoiceInput.

Campos comunes

Los campos siguientes son comunes en todos los tipos de entrada.

TextInput

Use este tipo de entrada si necesita que los usuarios proporcionen un texto libre (por ejemplo, la respuesta a una pregunta de una encuesta).

Ejemplo TextInput

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

DateInput

Use este tipo de entrada si necesita que los usuarios proporcionen una fecha o una hora (por ejemplo, en el caso de la fecha de vencimiento de una tarea).

Ejemplo DateInput

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

MultichoiceInput

Use este tipo de entrada si necesita que los usuarios seleccionen una opción de una lista de opciones predefinidas (por ejemplo, el estado de un error, Sí/No/Quizás, etc.).

Campo	Tipo	Descripción
choices	Matriz de pares nombre-valor	Define los valores que se pueden seleccionar para la entrada de varias opciones.
isMultiSelect	Boolean	Si se establece en true, indica que el usuario puede seleccionar más de una opción. Las opciones especificadas se mostrarán como una lista de casillas de verificación. El valor predeterminado es false.
style	Cadena: normal (predeterminada) o expanded	Si isMultiSelect es false, al establecer la propiedad style en expanded se indicará a la aplicación host que intente mostrar todas las opciones en la pantalla, normalmente con un conjunto de botones de opción.

Ejemplo MultichoiceInput compacta

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

Ejemplo MultichoiceInput de selección múltiple

{
  "@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" }
  ]
}

Ejemplo MultichoiceInput expandida

{
  "@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" }
  ]
}

Sustitución del valor de entrada

Se puede hacer referencia al valor de una entrada en el cuerpo de una HttpPOST acción. Cuando se hace referencia a un valor de entrada, se sustituye por el valor real de la entrada justo antes de que se ejecute la acción.

Para hacer referencia al valor de una entrada, use el siguiente formato:

{{<id of input>.value}}

Ejemplo de sustitución del 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}}"
    }
  ]
}

Acción InvokeAddInCommand

Abre el panel de tareas de un complemento de Outlook. Si el complemento no está instalado, se pedirá al usuario que instale el complemento con un solo clic.

Cuando se ejecuta una acción InvokeAddInCommand, Outlook comprueba primero si el complemento solicitado está instalado y activado para el usuario. Si no es así, se notifica al usuario que la acción requiere el complemento, y podrá instalarlo y habilitarlo con un solo clic. Outlook abre el objeto solicitado, haciendo que cualquier contexto de inicialización especificado por la acción esté disponible para el complemento.

Para obtener más información, consulte Invocación de un complemento de Outlook desde un mensaje accionable.

Ejemplo InvokeAddInCommand

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

Ejemplos de tarjetas

Trello

Se crea una tarjeta en una lista:

Le mostramos cómo se crea esa tarjeta:

Aquí puede ver la misma tarjeta con la acción Agregar un comentario expandida:

Aquí se muestra cómo se crea la acción Agregar un comentario:

Trello JSON

{
  "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

Aquí puede ver un ejemplo de una tarjeta de resumen de Twitter:

Le mostramos cómo se crea esa tarjeta:

Twitter JSON

{
  "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..."
    }
  ]
}

Correo electrónico accionable

Este es un ejemplo de un cuerpo de correo electrónico HTML con una tarjeta de mensaje integrada.

<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>