How to use Microsoft’s Active Card in your chat apps

Chat-based user interfaces are everywhere. Built into both consumer and business tools, they’re an effective way of delivering quick snippets of information, especially with a growing ecosystem of personal assistants like Cortana and Siri and chat platforms like Teams, Messenger, and Slack. New tools in the next release of Windows 10 will also let applications add information into the Windows Timeline, helping you quickly pick up the context of previous interactions.

With a chat platform, you ask a question, a natural language tool parses the question, and a response is delivered. That response might be direct if you’re using a personal assistant, or it might be from a bot in chat platform. While there’s a tendency to use these platforms to deliver only text, it’s often not the best way of displaying information. That’s where information cards come in, stepping outside the traditional chat format, to display formatted text and images, and even add interactions.

Microsoft’s Adaptive Card frees developers to focus on chat content

Originally designed to work with its Bot Framework, and extended to provide interaction in tools like Teams, Microsoft is working to make its Adaptive Card an open platform for delivering information to any chat-based application platform. The underlying design principles make a lot of sense: Ensure that the application that hosts the card content has control over how the card content is displayed. As a card author, you’ll own what’s in the card, but you don’t get pixel-level control. The result is a format that’s focused on content, and that should handle the different ways users work with chat-based systems.

That last point is critical: Everyone uses a chat application differently. Some view them full screen on phones, some use standard PC windows, others display them as narrow columns. As a developer, you have no control over the layout of a chat, and no way of getting that information from the client. That makes delivering a good UI hard, so having a framework to support content delivery reduces risks and allows a richer response format than pure text.

Microsoft has taken a lesson from the familiar Markdown document formatting tool. Markdown’s markup is simple, using shortcuts to add headers, links, and even code blocks as you write a document. But it’s also expressive enough to handle most common formatting requirements: bolding text, adding italics, and handling lists. By taking a similar approach to card design, Microsoft hopes to encourage wider adoption and support, in much the same was as developer demands for Markdown support have seen it added to most common documentation platforms.

Adaptive cards are JSON objects. When a query is delivered to your application from a chat client, you can return the response in the card’s JSON structure. Because cards are built from predefined elements, you can use an online card editor to build and test cards—with support for editing chat-service-side client formatting and for trying out audio versions of your card. The online editor will format cards for Microsoft’s platforms: Cortana, Teams, and the upcoming Windows Timeline and Skype Adaptive Card. You can see which card renderers support actions, letting you design cards that work with both interactive and informational systems.

As well as providing tools to help you design adaptive cards that you can deliver to any compatible chat application, Microsoft also has a set of renderers that can be used by host applications. As well as the familiar web and Windows clients, there’s also support for Android and iOS, so you can add adaptive cards to most user-facing platforms; MacOS is obviously the big gap in Microsoft’s implementation. You don’t need much code with the renderers; they work in the context of an existing display surface and only have a handful of operations: opening a URL containing the JSON object, submitting the card to the display surface, and displaying card contents.

Using the Adaptive Card SDK

Adding the Adaptive Card JavaScript library to your application is easy enough. Node applications can pull it in from NPM, while a standard script tag adds it to your HTML. Rendering a card is a matter of taking the JSON from the card source and adding a handler for any actions it might contain. Once the card is parsed by the Active Card script, you can apply the render method and then use a DOM action to add it to the appropriate part of your HTML.

Microsoft provides basic styling for card contents in its library, but there are plenty of options for applying your own look and feel. One route involves editing the host config file that defines the common fonts used for all the cards rendered on your platform, no matter what application delivers them. You can also use this to control basic layout, aligning actions and spacing, as well as setting colors and any columns used.

IDG

The obvious customization route for any web-based active card is via CSS. Microsoft’s documentation details the various classes used to handle card elements, and you can override the default settings with your own CSS definitions. Perhaps you want card content to blend in to a chat, or perhaps you want it to stand out. By using CSS, you can also provide different formats for different card sources, applying appropriate class settings as required.

For more complex modifications to active card formatting, Microsoft gives you access to a low-level registry with separate sections for both Actions and Elements. Here you can override Microsoft’s JavaScript with your own, allowing more complex changes to both layout and to card interactions. That way, if you’re using your own renderers for any of the elements used by an active card you can ensure that yours are used by default, avoiding confusion among, for example, data pickers in a calendaring action.

As chat systems become more and more common, a standard for how applications interact with them is becoming increasingly important. Although Microsoft’s Adaptive Cards may not end up as that standard, it is a start. The release of the 1.0 version of its specification and of its client-side SDKs should help with uptake outside the core Microsoft ecosystem, and it should encourage chat vendors to come up with a common standard that works across the entire range of endpoints—and even on newer voice-based systems like Amazon’s Alexa.