Understand Alexa Presentation Language (APL)

With Alexa Presentation Language (APL), you can create visual experiences to accompany your skill. Users can see and interact with your visuals on supported devices such as the Echo Show, Fire TV, some Fire tablets, and other devices. You can include animations, graphics, images, slideshows, and video in your visual experience.

APL and skill flow

All custom skills use a request and response interface. Alexa sends your Lambda function or web service a request. Your skill handles this request and returns a response. APL works within this familiar framework:

  • Your skill gets a normal LaunchRequest or IntentRequest to start an interaction with the user.
  • In your skill response, you can return directives to tell the device to display your APL content and execute commands. These directives are defined in the Alexa.Presentation.APL interface. The payload of the directive includes an APL document, which is a structure that defines how you want to display your content on the viewport, and a data source, which provides the specific data to display. Both of these concepts are described in more detail later.

  • Your skill can listen for requests triggered by user actions, such as when the user selects a button on the screen. These requests are also defined in the the Alexa.Presentation.APL interface. You create handlers in your skill code to accept and process these requests, similar to the handlers you create for your intents.

    Note that an APL document can also trigger commands that change the display without the need to send any event to your skill. For example, touching a button on the screen can trigger video playback or an animation directly. In this case, there is no need to send a request your skill and then wait for a response.

  • As with any skill, users can make voice requests, which are sent to your skill as normal IntentRequest request. For a good user experience, your skill should let users interact with your skill with both voice and touch and not force users to just one input mode.

For example, a user might have this interaction with an APL skill:

The user's device is an Echo Show.
User: Alexa, open Trivia Master

The Echo Show displays a welcome animation as Alexa begins speaking.
Alexa: Welcome to Trivia Master! Are you ready to play?

User: Yes.

The Echo Show displays a scrolling list of trivia categories.
Alexa: OK, please choose the Trivia Master category you want to play! You can say a category or select an item on the screen.

User: … (User touches the "Animals" category item on the screen. Alternatively, the user could have responded with an utterance like "Play the animals category" )

Device displays the question over a related background image.
Alexa: OK, we'll do questions about animals. Here's your first question: text of the trivia question… (Alexa reads the question text and highlights each line.)

After reading the question, the screen updates to show a list of possible answers to choose from.

User can respond to the questions with either voice or by touching options on the screen.

Here is how the APL directives and requests would be used in this interaction:

User interaction Skill requests/responses

The user's device is an Echo Show.
User: Alexa, open Trivia Master

Your skill gets a normal LaunchRequest, then returns a response with two parts:

  • Normal output speech
  • The Alexa.Presentation.APL.RenderDocument directive. The payload of this directive includes an APL document that defines a welcome animation.

The Echo Show displays a welcome animation as Alexa begins speaking.
Alexa: Welcome to Trivia Master! Are you ready to play?

The Echo Show renders the document provided in your response. This displays a welcome animation.

When Alexa finishes speaking, the device opens the microphone to listen for the user's response.

User: Yes.

Your skill gets a normal IntentRequest for the AMAZON.YesIntent intent, then returns a response that again includes both output speech and the RenderDocument directive. This time, the APL document defines a scrolling list of categories.

The Echo Show displays a scrolling list of trivia categories.
Alexa: OK, please choose the Trivia Master category you want to play!

The Echo Show renders the document provided in your response. This displays a list of game categories.

When Alexa finishes speaking, the device opens the microphone to listen for the user's response.

User: … (User touches the "Animals" category item on the screen. Alternatively, the user could have responded with an utterance like "Play the animals category" )
  • Your skill gets an Alexa.Presentation.APL.UserEvent request indicating the item the user touched.
  • Your handler for the UserEvent request returns a response with output speech, the RenderDocument directive, and the ExecuteCommands directive.
  • The APL document defines two pages: a detail page that displays the question, and an answer page that displays a list of multiple-choice answers.
  • The ExecuteCommands directive specifies commands to read the question text displayed on the screen and highlight each line in sync (SpeakItem), then switch to the second page to display the possible answers (SetPage).

Device displays the question over a related background image.
Alexa: OK, we'll do questions about animals. Here's your first question: text of the trivia question… (Alexa reads the question text and highlights each line.)

The Echo Show renders the document to display the question text, then executes the SpeakItem command to read the text with the karaoke highlighting.

After reading the question, the screen updates to show a list of possible answers to choose from.

User can respond to the questions with either voice or by touching options on the screen.

When the SpeakItem command is finished, the device executes the SetPage command to change the display to the next page, which displays a list of answers.

APL support on different types of devices

You can use APL to display content on both devices with screens, such as the Echo Show, and devices with alphanumeric clock displays, such as the Echo Dot with clock:

  • You can use all APL features to display content on devices with screens. APL provides full support for user interaction and rich content such as images, video, and animation.
  • You can use a smaller set of APL features to display content on devices with character displays such as the Echo Dot with clock. APL provides support for showing alphanumeric data on the display for these types of devices. These devices also support unique features like the ability to marquee text and show timers and countdowns. See Understand Alexa Presentation Language and Character Displays.

The overall concepts for APL are the same regardless of the device you target. Supporting both of these device categories is recommended, as it lets your skill reach more users.

What do you build to use APL in a skill?

To use APL in your skill, you work with APL documents, data sources, commands, and the APL directives and requests.

The following sections provide a high-level overview of these key APL concepts and where they fit into your skill-building process.

Documents

An APL document is a JSON structure that defines a template to display on the viewport. The document controls the overall structure and layout of the visual response. An APL document combines multiple parts:

  • An APL component is a primitive UI element that displays on the viewport, such as a simple text box. Components are the basic building blocks for constructing a document.
  • A layout combines components into a reusable template and gives it a name. You can then place the layout in your document by referencing its name. This results in a more modular design that is easier to maintain.
  • A style assigns a name to a set of visual characteristics, such as color and font size. You can then assign the style to a component. Use styles to keep your visual design consistent.
  • A resource is a named constant you can use rather than hardcoding values. For example, you could create a resource called myRed that defines a particular shade of red, and then use that resource name when you need to specify a color.
  • A package bundles together all of the above elements so that you can use them across multiple APL documents. You import the package into your document.

An APL document can be very simple or very complex. For example, a simple document might just use the Text component to display plain text. This JSON displays the text "Hello World!" in the center of the viewport:

Copied to clipboard.

{
  "type": "APL",
  "version": "1.2",
  "description": "A simple hello world APL document.",
  "settings": {},
  "theme": "dark",
  "import": [],
  "resources": [],
  "styles": {},
  "onMount": [],
  "graphics": {},
  "commands": {},
  "layouts": {},
  "mainTemplate": {
    "parameters": [
      "payload"
    ],
    "items": [
      {
        "type": "Text",
        "height": "100vh",
        "textAlign": "center",
        "textAlignVertical": "center",
        "text": "Hello World!"
      }
    ]
  }
}

APL is designed to encourage modular documents and reuse. The Alexa Design System for APL provides a set of responsive components and responsive templates. These combine APL components, styles, and resources into modular, responsive layouts you can use to more quickly build your document and ensure it works well on different viewports. You can also build your own re-usable layouts and bundle them into packages to use across multiple documents.

For details about these concepts:

Data sources, data binding and data-binding syntax

APL supports data-binding, which lets your document retrieve data from a separate data source that you provide. Data binding lets you separate your presentation logic (the APL document) from your source data.

In the earlier "hello world" document example, the text to display is hard-coded in the document. While this is fine for a simple example, the better approach is to put the data in a separate data source and then point to that data source from the document. In this case, the document would look like this:

Copied to clipboard.

{
  "type": "APL",
  "version": "1.2",
  "description": "A simple hello world APL document with a data source.",
  "settings": {},
  "theme": "dark",
  "import": [],
  "resources": [],
  "styles": {},
  "onMount": [],
  "graphics": {},
  "commands": {},
  "layouts": {},
  "mainTemplate": {
    "parameters": [
      "payload"
    ],
    "items": [
      {
        "type": "Text",
        "height": "100vh",
        "textAlign": "center",
        "textAlignVertical": "center",
        "text": "${payload.helloworldData.properties.helloText}"
      }
    ]
  }
}

The value of the Text component's text property now contains an expression set off with a dollar sign ($) and curly brackets ({ }). This is a data-binding expression. In this example, the expression ${payload.helloworldData.properties.helloText} tells the document to retrieve the text to display from the data source called helloworldData. The text to display is in the properties.helloText property of helloworldData:

Copied to clipboard.

{
  "helloworldData": {
    "type": "object",
    "objectId": "helloworld",
    "properties": {
      "helloText": "Hello World!"
    }
  }
}

For details about data sources and data binding:

Commands

You use APL commands to do both of the following:

  • Change the visual experience during runtime. For instance, the SetValue command can change the value of a component's property, which then changes the appearance or behavior of the component.
  • Communicate with your skill's Lambda function or web service during the interaction. To do this, you use the SendEvent command in your document. This command tells Alexa to send your skill a UserEvent request, which your code can handle just as it handles other types of requests such as IntentRequest. The skill requests and responses related to APL are discussed more in Skill directives and requests.

This example shows the SetValue command configured to change the text property of the component with the ID buttonDescriptionText:

Copied to clipboard.

{
  "type": "SetValue",
  "componentId": "buttonDescriptionText",
  "property": "text",
  "value": "You pressed the 'Click me' button!"
}

There are multiple ways to execute APL commands:

  • Some components have event handler properties that can trigger a command. For example, the TouchWrapper component has an onPress property to specify a command to execute when the user selects the component on the screen. Similarly, the AlexaButton responsive component has a primaryAction property that specifies the command to use when the user selects the button.
  • The APL document itself has an onMount property to execute a command when the document loads. This is useful for creating welcome animations that play when the user launches your skill.
  • You can use a skill directive to send an APL command from your skill code. This is discussed more in Skill directives and requests, later.

For example, you could use the primaryAction property on an AlexaButton to trigger the SetValue command shown earlier:

Copied to clipboard.

{
  "type": "AlexaButton",
  "id": "clickMeButton",
  "primaryAction": {
    "type": "SetValue",
    "componentId": "buttonDescriptionText",
    "property": "text",
    "value": "You pressed the 'Click me' button!"
  }
}

For details about commands:

Skill directives and requests

Your Lambda function or web service communicates APL-related information with the directives and requests defined in the Alexa.Presentation.APL interface:

  • You send the Alexa.Presentation.APL.RenderDocument directive to tell the device to display APL content. Include both the document and the associated data source (if applicable) as part of the directive.
  • You send the Alexa.Presentation.APL.ExecuteCommands directive to send commands to the device. These commands typically reference specific parts of the document. For example, the SpeakItem command tells the device to speak the text defined with a particular component (such as a Text component).
  • You can use the SendEvent command in your document to send an Alexa.Presentation.APL.UserEvent request to tell your skill about user actions that take place on the device, such as when the user touches a button. Your code should include handlers to accept and process these types of events.

Use the directives and requests to build a user interface that works with both voice and touch. For example, the earlier trivia interaction example described how the user could choose their trivia category by touching the screen or by speaking the category. To accomplish this, each category shown on the screen is configured with the SendEvent command, which sends a UserEvent request. The skill's interaction model would also have a ChooseCategoryIntent intent with utterances such as "play the {category} category". The skill code then has a handler that listens for either the Alexa.Presentation.APL.UserEvent request or the IntentRequest for ChooseCategoryIntent and responds by selecting that category and starting the game.

For more about the directives and requests, see:

Conditional logic and responsive documents

APL is built around conditional logic. You can create an APL document that displays the content in different ways depending on the viewport characteristics or other factors. For example, you could create a list that displays a continuous vertical scrolling list on larger screens, but presents each list item a single page on very small screens.

Every APL component and command has an optional when property that expects a boolean value (true / false). This determines whether the device displays the component or executes the command. The property defaults to true when not provided.

To use the when property, write a data-binding expression that evaluates to true or false. For example, this statement evaluates to true when the device is a small, landscape hub:

"when": "${@viewportProfile == @hubLandscapeSmall}"

As noted previously, data-binding expressions always take the form: ${expression}. In the above example, the constants viewportProfile and hubLandscapeSmall are resources provided as part of the alexa-viewport-profiles package. The "at" sign (@) is the standard syntax to reference a resource.

You can also use data-binding expressions to assign property values on components and commands conditionally. For example, the following expression returns the string "center" for small, round hubs, and "left" for all others:

${@viewportProfile == @hubRoundSmall ? 'center' : 'left'}

You could use this to conditionally set the property values on a component, instead of using when to hide or show the entire component.

Conditional logic is a key ingredient when you write responsive APL documents. A responsive APL document can adjust to the characteristics of the viewport. Since users can invoke skills on devices with a wide variety of screen sizes, shapes, and aspect ratios, responsive APL is critical to creating a good user experience. For more details and recommendations, see Build Responsive APL Documents

For more about conditional logic in APL:

High-level steps to implement APL in your skill

These steps assume you are familiar with building custom skills. To learn more about custom skills in general, start with Understand Custom Skills and Steps to Build a Custom Skill.

  1. Plan your visual design. See the APL sections in the Alexa Design Guide for inspiration and guidance.
  2. Build the APL document and any accompanying data source.
    • Many skills will have multiple documents to display different content at different points during the skill flow. In the earlier trivia interaction example, the trivia skill had X APL documents: one to present the welcome screen, one to present a list of trivia categories, and one to display the question text.
    • Use the APL authoring tool in the developer console to preview your document as you build.
    • Follow recommended best practices to ensure that your content looks good on all different devices that users might have.
  3. Configure your skill to support the Alexa.Presentation.APL interface.
  4. In your skill code, add the code to send RenderDocument and ExecuteCommands directives to display your document when needed.
  5. In your skill code, create handlers for the UserEvent request.

  6. Test your skill in the simulator and with actual devices. Update the set of viewport profiles your skill supports and test to ensure that your content looks good on all different types of devices.

    You can use the simulator to see how your content looks on different viewports that are similar to devices with screens, such as the Echo Show. The simulator does not include a viewport for character displays like the Echo Dot with clock, so you need to use a device to test your content on a character display.

  7. Submit your skill for certification.
Amazon Alexa
Amazon Appstore
Amazon Web Services
Amazon Dash Replenishment