Alexa Presentation Language (APL) Overview

With Alexa Presentation Language (APL), you can build skills with voice and visual experiences that apply conditional layouts and data binding. If you have developed skills for Alexa-enabled devices with a screen, you are familiar with display templates. You can use APL to create the equivalent of display templates. However, with APL, you also have the power and flexibility to build multimodal skills with many visual elements–including graphics, images, and slide shows–and to customize the output for different devices.

With APL, you can create skills with full-featured, responsive, and interactive screen displays, in a manner similar to how you can create Web pages with HTML, CSS, and JavaScript.

Understand how APL works with your skill

The following process walks you through the sequence of activities that occur when you include APL in your skill development:

  • You create an APL document. The skill sends this APL document to the device, along with a collection of data. The APL document might import packages of additional APL content. The APL content includes definitions of common resource properties, styles that control how components are displayed, parameterized component layouts, and a single "main" starting layout.

  • The mainTemplate starting layout inflates into a hierarchy of primitive components containing text, graphical images, scrolling regions, and several types of layout components that position child components. Data-binding expressions set the properties of the primitive components. These expressions combine the data sources referenced in the APL document with the structure of the component hierarchy.

  • The initial display of the visual hierarchy on the screen, and subsequent user interactions with the visual hierarchy, generate state changes and events. Styles assigned to components visually change the appearance of a component when the component state changes. Event handlers assigned to components capture events and can change the visual component hierarchy, scroll or navigate within the hierarchy, speak text-to-speech (TTS) or SSML, change the properties or state of components, run animations that move, rotate, scale, and fade components, control media playback, and send messages to the skill in the cloud. Event handlers use data binding to control behavior.

  • When an event handler sends a message to the skill in the cloud or when the user starts a speech utterance, the information passed to Alexa includes the context of the component hierarchy. The context contains the position, visibility, and types of displayed components. As the skill developer, you can mark a component to be of speech interest, or indicate that it has actionable behaviors such as scrolling or toggling a check box. Alexa uses the context to automatically resolve utterances such as "Alexa, select the third one." When Alexa receives the message or speech intent, the skill service may send back a response with one or more commands to execute in the displayed visual hierarchy.

Apply APL capabilities

You can create, reuse, and nest layouts and components. The separation of the layout and the data-binding follows standard software development practices, and makes Alexa skill development more robust. You can design a layout so that it inflates and lays out child components appropriately for the theme, shape, and size of the screen of the target device. You have control over how your skill appears and acts. APL uses data binding to populate the inflated component hierarchy with the desired images, graphics, and text. With APL development tools, you can quickly visualize how the APL document will appear on a wide range of devices and under different theme and accessibility operating conditions.

APL terminology

The following list of terms refers to common APL concepts.

Document: A JSON file with the following sections: a list of APL packages to import, definitions for resources, layouts, and styles, and an initial layout to display on the screen. An APL document is what a skill sends to the device.

Package: A collection of files with a unique name and version. Packages typically contain one or more APL documents, bitmap images, and vector graphics. Packages are cached on the device for rapid re-use. Each sample included in the authoring tool has a package with a single document.

Layout: A visual hierarchy of components that render on the screen. Standard components include text, bitmap images, vector graphics, scrolling regions, and components that position child components relative to each other. Layouts support conditional expansion; portions of the layout hierarchy can be dependent on the screen size/shape or other developer-defined properties. Layouts may include other layouts. Large layouts are built out of individual components and layouts (which inflate into layouts). The use of layouts encourage developers to build libraries of common patterns.

Resources: A constant used when drawing text, images, and layouts on the screen. For example, the constant textSizeCaption is the size of the font used to draw image captions. Using a named constant rather than a numerical value allows reuse of an APL document across different devices by providing per-device resource definitions.

Styles: A collection of state-dependent resources. For example, the flatButton style defines the size, background color, text color, border color, border width, and border radius of one type of button for the "normal", "pressed", "focused", and "disabled" states. All APL components have a clearly documented list of styled properties.

Components: A component is a primitive element that displays on the viewport. A component has various properties that affect its behavior and appearance.

For a discussion of how to use these elements to improve the user experience for your multimodal Alexa skill, see Alexa Design Guide.

Update your skill to support APL

If you did not use the Node.js v2.0 SDK to develop your skill, see Add APL support to your skill.

If you did use the Node.js v2.0 SDK to develop your skill, see Update your skill to support APL.

APL authoring best practices

The following best practices are similar to those found in front-end design and programming and are meant to encourage extensibility and reusability. The Alexa Design Guide provides guidance for effective skill design.

Resources

  • Use named resources rather than absolute values. For example, instead of setting a text color to "black", define a suitably named resource like "standardTextColor = black".
  • Use resources to define conditions

Layouts and styles

  • Make layouts to allow for uniformity.
  • Break your visual design into logical sections and define a layout for each section of your visual design, passing appropriate parameters.
  • Compile styles to create themes.
  • Avoid the use of "%"-based dimensions. These dimensions are a percentage of the parent container, which is generally not what you want. In most cases you'll want to either use a % of the overall screen size (such as "${viewport.width * 0.05}") or use the Flexbox grow and shrink properties.
  • Use efficient branching logic in layouts. For example, if you define a new custom MyHeader layout, as shown in the following example, that needs to adapt to landscape, portrait, and round screens, use simple dispatch logic to direct the display to other layouts, as shown in this example.
"MyHeader": {
  "parameters: ["title", "subtitle"],
  "item": [
    {
      "when": "${viewport.shape == 'round'}",
      "type": "MyRoundHeader"
    },
    {
      "when": "${viewport.width > viewport.height}",
      "type": "MyLandscapeHeader"
    },
    {
      "when": true,
      "type": "MyPortraitHeader"
    }
  ]
},
"MyRoundHeader: {
  :
  :

Templates

  • Dynamically populate your templates with data-binding expressions
  • Construct templates across multiple devices
  • Organize your template file system per screen

APL document and information exchange

APL communicates data to the Alexa service to support user interaction and visual context. In turn, the Alexa service sends down commands to be processed by APL.

The following types of information exchange that involve an APL Document will typically occur.

  • An Alexa skill sends an APL Document with associated meta-data to the device to be rendered.

  • An Alexa skill sends an ExecuteCommands directive to the current APL document which contains a list of commands that should be executed.

  • The customer speaks to the device or takes action on the device (such as by touching an option on a screen), thereby causing the context to be sent along with the utterance or event.

In addition, you may choose to have your skill support an event handler on the device, such as an Echo button, that fires a series of commands that should be processed on the device. One or more of these commands may send a message back to Alexa.

References

See also: