Using the Alexa Presentation Language (APL) with Jovo

Learn how to build visual Alexa Skills with the Alexa Presentation Language (APL) and the Jovo Framework.

You can also find the Jovo beginner template for APL here: jovo-templates/alexa/apl

• Introduction to APL
• Adding APL to your Alexa Skill with Jovo
  • Alexa Presentation Language Interface
  • addDirective
• Working with Documents and Data Sources
  • The APL Authoring Tool from Amazon
  • Next Steps

Introduction to APL

As recently announced by Amazon, the public beta of the new Alexa Presentation Language (APL) is now available.

APL allows you to build visual (or, multimodal) experiences for Alexa. Devices like the Echo Show, the Echo Spot, or even TVs can now display visual information that goes beyond the previously known Display Templates.

The Alexa Presentation Language is quite complex, so we're using this tutorial just to get started with some simple displays to make it easier for you to dive into this topic. Let us know in the comments if you have specific questions about APL where you would want to see a tutorial.

Here are more resources for you to get started:

• Amazon Docs: Alexa Presentation Language (APL) Overview
• Amazon Docs: APL Support for Your Skill
• Great introduction by Dustin Coates: Alexa Presentation Language Walkthrough

Adding APL to your Alexa Skill with Jovo

We prepared a small Jovo app template for you that uses some APL documents. You can download the template like this:

In the next few steps, we're going through all the essential elements that you need to create simple APL displays in your Alexa Skills.

Alexa Presentation Language Interface

First, you need to enable the APL Interface for your Skill.

You can either do this in the "Interfaces" tab in the Alexa Developer console:

Or you can deploy with the Jovo CLI. The Jovo APL template has the right configurations for the interface in its project.js:

Just use the following Jovo CLI commands to deploy the template to your Amazon Alexa developer account:

addDirective

To use APL templates, you need to add an additional directive called Alexa.Presentation.APL.RenderDocument to your response.

For this, you can use the addDirective method and add the following elements:

We will talk a little bit more about the document and datasources elements in the next step. The document block can get quite lenghty. This is why it is recommended to put it into a separate JSON file and then require it.

For example, the Jovo APL template uses the main layout by Amazon as a main.json file in a dedicated apl folder:

For example, this main.json file looks like this:

If we're testing it in the Alexa Simulator, we can see a very simple "Hello World":

In the next section, we're taking a detailed look at both documents and data sources.

Working with Documents and Data Sources

One of the interesting aspects about APL is how it separates the data from the presentation. This way, complex visuals can be created, stored in a content management system, and then be dynamically changed by the code.

As the whole layout creation process is such a complex process, we're first taking a look at a helpful new tool by Amazon.

The APL Authoring Tool from Amazon

The authoring tool by Amazon allows you to build your own templates for APL, or build on top of existing ones (currently, the display templates known as Body Templates and List Templates):

For example, if we select one of those, like Image Left Detail Sample (similar to Body Template 3), it looks like this:

By clicking on the upper right "Export Code" button, we can download a JSON called apml_template_export.json that includes both the important document and dataSources elements.

In the Jovo APL template, we split up these elements and put them into different folders, so you can see how the display templates differ from each other.

Just say Alexa, ask my APL test to show Body Template three, and it should display the right template:

Next Steps

This short tutorial just scratches the surface of what's possible with the Alexa Presentation language by showing how previously known display templates can be migrated to APL templates.

In the next tutorials, we are going to look at additional elements of APL:

• New layouts
• APL commands
• Layouts for different viewports
• UserEvent requests