Display Cards Overview

Display Cards for Alexa allow products to render “Now Playing” information for music, as well as static display cards for general knowledge questions, weather, to-do and shopping lists, calendar updates, and Alexa skills. If your product has a display, you can enable the Display Cards capability in the Alexa Developer Console to begin receiving directives with visual metadata. For example, after you've enabled Display Cards for your product, when a user asks, "Alexa, what is the weather?", in addition to receiving a Speak directive with Alexa TTS, you will receive a RenderTemplate directive with visual metadata that maps to design templates provided by Amazon.

How to Enable Display Cards

To enable display cards, you must declare the TemplateRuntime version 1.0 interface in your call to the Capabilities API. For additional details, see Capabilities API.

Flow and Delivery

This diagram illustrates the high-level message flow for delivering visual metadata to an AVS-enabled product.

Data flow diagram.
Click to enlarge
  1. A user asks, "Who is Usain Bolt?". Their speech is captured by your product and streamed to AVS.
  2. AVS returns two directives:
    • A Speak directive that instructs your client to play Alexa TTS.
    • A RenderTemplate directive that instructs your client to display visual metadata – in this case, information about Usain Bolt.
  3. Playback of Alexa TTS starts.
  4. The RenderTemplate directive is rendered immediately (and if possible, in tandem with the Speak directive) in a separate thread.
  5. Your client informs AVS that your product has started to playback Alexa TTS by sending a SpeechStarted event.
  6. When playback of Alexa TTS finishes, a SpeechFinished event is sent to AVS.

This is what the user will see on a tablet-sized screen:

BodyTemplate2
Click to enlarge

TemplateRuntime Directives

The TemplateRuntime interface exposes two directives for the delivery of visual metadata:

  • The RenderPlayerInfo directive instructs your client to display visual metadata associated with user requests for audio playback (music). In addition to sending Play directive, AVS will send a RenderPlayerInfo directive with visual metadata specific to an audio content provider that your client will bind to a template and render for the end user.
  • The RenderTemplate directive instructs your client to display visual metadata associated with a user’s request for a for static display cards. For example, when a user asks “Alexa, what's the weather in San Francisco?”. In addition to sending a Speak directive, AVS will send a RenderTemplate directive with visual metadata that your client will bind to a template and render for the end user.

Display Card Templates

The TemplateRuntime interface supports five templates, one for "Now Playing" and four static display cards. The visual metadata provided in each directive will map to a specific component in each display card template.

"Now Playing" visual metadata is always delivered as a RenderPlayerInfo directive and maps to the "Now Playing" template for music.

Static display cards are delivered via the RenderTemplate directive, and always include the type parameter. This instructs your client to map the provided visual metadata to a specific template type:

Type Description Use Cases
BodyTemplate1 A text only template that supports title, subtitle, text, and skill icons. Wikipedia entries without images, and simple cards provided by Alexa Skills.
BodyTemplate2 A template with support for body text and a single image. Wikipedia entries with images.
ListTemplate1 A template for lists and calendar entries. Shopping lists, to do lists, and calendar entries.
WeatherTemplate A template designed to display weather data. Weather

Dissecting a RenderTemplate Directive

Let's return to our example. You'll remember that after asking Alexa, "Who is Usain Bolt?", a RenderTemplate directive was returned instructing your client to display visual metadata for the user. The directive's payload supplies important information like mainTitle, subTitle, skillIcon, textField, and image, which map directly to specific components in the display card template. In this section we're going to dissect that RenderTemplate directive.

The payload will look like this:

{
  "directive": {
    "header": {
      "namespace": "TemplateRuntime",
      "name": "RenderTemplate",
      "messageId": {{STRING}},
      "dialogRequestId": {{STRING}}
    },
    "payload": {
      "token": "{{STRING}}",
      "type": "bodyTemplate2",
      "title": {
        "mainTitle": "Who is Usain Bolt?",
        "subTitle": "Wikipedia"
      },
      "skillIcon": null,
      "textField": "Usain St Leo Bolt, OJ, CD born 21 August 1986..."
      "image": {
        "contentDescription": "{{STRING}}",
        "sources": [
          {
            "url": "https://example.com/usain_bolt.jpg",  
            "size": "LARGE"
          }
        ]
      }
    }
  }
}

The first thing we encounter is the token, which is used to match the Speak directive that includes Alexa TTS, with the RenderTemplate directive that includes visual metadata. Then there is type. This value let's you know which display card template to choose – in this case it's bodyTemplate2. The remaining parameters include the visual metadata that you must bind to the template. Here's a sample of the visual metadata bound to the template specification for tablet-sized screens:

BodyTemplate2 with visual metadata mappings.
Click to enlarge

Rendering Instructions

In addition to the guidance provided in the Interaction Model, these rules must be enforced by your product when rendering visual metadata:

  1. Read the response on the request thread and parse the directives:
    • Immediately execute directives without a dialogRequestId on a new thread.
    • Immediately execute RenderTemplate directives on a new thread.
    • Place directives with a dialogRequestId in your queue.
  2. Directives in the queue should be picked up on a separate thread and handled sequentially.
  3. Play directives and associated RenderPlayerInfo directives must be in sync. Unlike RenderTemplate, the directive should not always be rendered immediately, but should match the sequence of Play directives. For example, after sending PlaybackNearlyFinished, if you receive a new Play directive and RenderPlayerInfo directive they must be added to the queue and handled when the currently playing track has finished. This means that your display card implementation must be aware of playback state, such as playing, stopped or paused.

UX Considerations

When implementing display cards, you need to determine how best to render visual metadata for your user. The AVS UX Design Guidelines for Display Cards provide screen specific guidance for TVs, tablets, and low resolution screens, with requirements for binding metadata, and recommendations for display card transitions, interruption behaviors, and the presentation of Alexa states.

Click here to view the AVS UX Design Overview for Display Cards.

Next Steps

Amazon Alexa
Amazon Appstore
Amazon Web Services
Amazon Dash Replenishment