Support Devices with Character Displays

An Alexa-enabled device with a character display, such as the Echo Dot with clock, provides an alphanumeric display. When users invoke your skill on this type of device, your skill can use Alexa Presentation Language (APL) to display brief, textual messages. This capability can be useful for skills that provide short answers, such as weather, trivia, conversion/math results, and so on.

About character displays

There are many types of character displays. For example, the Echo Dot with clock device has an LED 7-segment alphanumeric clock display. This display can show four alphanumeric characters in a single line (4 x 1), with the colon (:) as an inter-segment character to indicate the time.

The Echo Dot with clock has a 4 x 1, 7-segment clock display
The Echo Dot with clock has a 4 x 1 7-segment clock display

Character displays can have limitations in the type of characters they can display. The seven-segment display on the Echo Dot with clock can show all numbers and many letters. Letters that can't be formed from the seven segments, such as "W," are treated as spaces.

Although a 4 x 1 character display can show just four characters at a time, APL supports marquee scrolling on character displays, so you can display longer text.

Other character displays can also use dots instead of segments, and they can include multiple lines rather than just one.

About APL support for character displays

Core APL concepts that apply when building for screens also apply when you build for a character display:

  • When a user invokes your skill, Alexa sends your Lambda function or web service a request. Your skill handles the request and returns a response, which can include a directive to display content on the device. Due to character display limitations, this content can consist of brief text (no graphics, animations, or media).
  • The content you send to the device is in the form of an APL document. An APL document is a JSON structure that defines a template to display. APL documents are constructed from components, which are UI elements that display on the device. Character displays support a small set of components for arranging and displaying text.
  • You can use data-binding to provide the data to display separately from the template defined in the document.
  • You can use APL commands to trigger actions, such as paging through a pager or changing the value of text shown on the display.
  • You can use conditional logic in your document to display different information for different types of displays. For example, on a 7-segment, 4 x 1 clock display like the Echo Dot with clock, you might display just the high and low temperatures from the weather forecast. However, on a device with multiple lines, you could show temperature for both today and tomorrow on separate lines.

For details about APL skill flow and other core APL concepts, see Add Visuals and Audio to Your Skill.

Build an APL document for a character display device

Because character displays have limited space, the supported APL document format is much smaller and simpler than the APL document format available for devices with screens. You can use a limited set of components for displaying and positioning text in your document:

  • Text and TimeText display text-based content. TimeText is available only on character displays.
  • Pager lets you define multiple "pages" that display one after another, so you can present more information.
  • Container groups and arranges multiple components.

To support re-use, you can also do the following:

  • Define layouts that combine components and accept parameters.
  • Define resources, which are named constants you can use instead of hard-coding values.

Other APL document concepts — packages, styles, and the Alexa Design System for APL — don't apply when you build for character displays. Character displays also don't support any sort of touch user input.

Basic document example

This document uses the Pager component to display two separate strings ("HELLO" and then "thIS IS APL"). Since these strings are longer than many displays, the marquee option in the overflow property tells the device to scroll the text one character at a time. The AutoPage command defined in onMount tells the device to advance automatically through the pages after displaying the document.

When you define the text, be sure to consider the supported characters for this device. This example uses characters supported on a seven-segment display like Echo Dot with clock.

Copied to clipboard.

{
  "version": "1.0",
  "type": "APLT",
  "mainTemplate": {
    "item": {
      "type": "Pager",
      "id": "myPager",
      "items": [
        {
          "type": "Text",
          "textAlign": "center",
          "overflow": "marquee",
          "text": "HELLO",
          "msPerCharacter": 500
        },
        {
          "type": "Text",
          "textAlign": "center",
          "overflow": "marquee",
          "text": "thIS IS APL",
          "msPerCharacter": 500
        }
      ]
    }
  },
  "onMount": {
    "type": "AutoPage",
    "componentId": "myPager",
    "delay": 3000,
    "count": 2,
    "duration": 200
  }
}

Document with conditional logic example

APL is built around conditional logic, so you can create an APL document that displays the content differently depending on the device. Since character displays can come in different sizes, you can tailor your output to make the most of the available space.

The following document example illustrates how you might display data for a weather skill. The document defines a single layout called Report, which accepts parameters for different sets of data. This layout uses conditional logic to change the display based on the device:

  • For a small device, the layout displays just the "numeric" temperature ("73").
  • For a 4 x 1 device like Echo Dot with clock, the layout displays a Pager with two pages ("H 73", "L 57").
  • For any larger device, the layout displays three lines of text with the temperatures for today, Tuesday, and Wednesday.

Configure your skill to support APL

To use APL to display content on a character display, you must add support for the Alexa.Presentation.APL interface. This interface is the same interface you use for APL with screen devices such as the Echo Show. After you enable the interface, you can determine whether a request sent to your skill came from a device with a character display. You can also respond with directives to display text.

For details about configuring the APL interfaces, see Configure a Skill to Support APL.

Check for character display support in your code

The directives to send content to character displays are in the Alexa.Presentation.APLT interface. These directives are different from the directives used to display content on screens (Alexa.Presentation.APL). Before your skill code sends any Alexa.Presentation.APLT directives, make sure the user's device supports the Alexa.Presentation.APLT interface.

Check the context.System.device.supportedInterfaces object included in every request. For an example of a request from a device with Alexa.Presentation.APLT support, see Verify that the user's device supports APL.

Send the RenderDocument directive in your response

To display your content on the device, include the Alexa.Presentation.APLT.RenderDocument directive in your response.

For example, this response sends the "Hello World / Welcome" Pager document described earlier.

{
  "version": "1.0",
  "response": {
    "outputSpeech": {
      "type": "SSML",
      "ssml": "<speak>Hello World! You should now also see my greeting on the device.</speak>"
    },
    "sessionAttributes": {},
    "directives": [
      {
        "type": "Alexa.Presentation.APLT.RenderDocument",
        "token": "helloworldToken",
        "document": {
          "version": "1.0",
          "type": "APLT",
          "mainTemplate": {
            "item": {
              "type": "Pager",
              "id": "myPager",
              "items": [
                {
                  "type": "Text",
                  "textAlign": "center",
                  "overflow": "marquee",
                  "text": "Hello World",
                  "msPerCharacter": 500
                },
                {
                  "type": "Text",
                  "textAlign": "center",
                  "overflow": "marquee",
                  "text": "Welcome",
                  "msPerCharacter": 500
                }
              ]
            }
          },
          "onMount": {
            "type": "AutoPage",
            "componentId": "myPager",
            "delay": 2000,
            "count": 2,
            "duration": 200
          }
        }
      }
    ]
  }
}
Was this page helpful?

Last updated: May 10, 2024