How to Get Started with the Alexa Presentation Language to Build Multimodal Alexa Skills
Voice is the most natural form of interaction. But in a voice-first world, visuals can enhance interactions with Alexa-enabled devices. By combining visual elements with voice experiences, developers can expand the possibilities of what their skills can do. Alexa-enabled devices have varying display sizes and shapes, purposes, and hardware limitations. For example, while using a skill on an Echo Spot or Fire TV may have similar spoken interactions for a customer, interactivity and information rendered on the screen may vary drastically depending on the device features.
The Alexa Presentation Language (APL) is Amazon’s new voice-first design language you can use to create rich, interactive displays for Alexa skills and tailor the experience for tens of millions of Alexa-enabled devices. Using APL, you can easily build customized, robust displays that coincide with your personal brand and the context of your voice experience.
Building voice user interfaces with APL borrows concepts you find in traditional web development, specifically with regards to styling, component nesting, and document hierarchy, but it also maintains security, scalability, and renderability across all Alexa-enabled devices.
In this blog post, we will dive into the technical details behind the new design language and explain how to build voice-first, visual experiences with APL.
What Is the Alexa Presentation Language?
APL is, very simply, JSON that is compiled into a visual experience. It is comprised of conditional layouts based upon both user and system-defined variables, and incorporates information from your skill code using data binding.
Your graphical user interface is defined by an APL document. When the speech response is sent to a user, a developer can optionally include an APL document to send to the device with a collection of data relevant to that document. The document may also include import packages of existing APL content, including common resource properties, component styles, or pre-defined layouts to be used throughout your document.
Below is a RenderDocument directive you would add in your response builder in your skill code to display the APL document. In this case, the APL document is empty, and would thus show a blank display.
{
"type": "Alexa.Presentation.APL.RenderDocument",
"datasources": {},
"document": {
"type": "APL",
"version": "1.0",
"import": [],
"resources": [],
"styles": {},
"layouts": {},
"mainTemplate": {}
}
}How to Enable APL in Your Skill
To allow an APL document to be a part of your skill’s response, you need to enable the Alexa Presentation interface in the Alexa Developer Console. Navigate to your skill and scroll to interfaces. Once there, toggle “Alexa Presentation Language,” save and build your skill. This will enable the ability to render APL in your skill and automatically add all of the required intents to your interaction model.
If you are working outside of the developer console, you can do this in your skill.json. When you create a skill that will incorporate visuals built with APL, you need to assure that you first include ALEXA_PRESENTATION_APL under apis.custom.interfaces in your skill manifest.
"apis": {
"custom": {
"endpoint": {
"sourceDir": "lambda/custom"
},
"interfaces": [
{
"type": "ALEXA_PRESENTATION_APL"
}
]
}
},It is important to note that we recently updated all skills to include the built-in intent AMAZON.NavigateHomeIntent. With this update, skills will now handle requests like “go home,” “return to the home screen,” “return home,” and so on. While these commands will mostly benefit multimodal skills, they are also supported on Echo devices without displays. The AMAZON.NavigateHomeIntent exits the skill and returns customers to the Home screen. For skills that have utterances that overlap with AMAZON.NavigateHomeIntent, the overlapping utterances will continue to invoke your custom intent. Either way, no action is needed by you.
How to Build an APL Document
Each entity within the main APL template is called a Component. The current list of primitive components can be found in the APL Reference. The mainTemplate is comprised of components containing text, graphical images, scrolling regions, and several types of layout components that position child components.
To customize your APL document, there is a new APL authoring tool available in the developer console. We provide seven samples built entirely in APL that are based upon the Body and List display directive templates. You can choose to build off of any of these APL documents, start your own from scratch, or upload existing APL code.
How to Incorporate an APL Document into a Response Using the ASK SDK
In your skill code, navigate to the intent to which you’d like to incorporate your visuals. These visuals are sent via an Alexa.Presentation.APL.RenderDocumentdirective. In the Alexa Skills Kit (ASK) Software Development Kit (SDK) for Node.js, you can add this in your response builder.
return handlerInput.responseBuilder
.speak(speechResponse)
.reprompt(repromptResponse)
.addDirective({
type : 'Alexa.Presentation.APL.RenderDocument',
document : document,
datasources : data
})
.getResponse();Start Learning with 3 New APL Skill Samples and More
To help you get started, we’ve created three new sample skills using APL: Level Up Riddles, Movie Quote Quiz, and Pager Karaoke. We plan on building upon these skills in the future to incorporate more APL features. We have also updated Pet Match to include a branch with a version of the skill that includes APL.
Visit our website to see how others are using APL to create engaging multimodal skills and get inspired to start building your own voice-first, visual experiences. To get started with APL, check out our technical documentation and the Alexa Design Guide.
Register for an APL Webinar
Watch our on-demand webinar on how to get started with APL. We cover how to use the new APL authoring tool, how to incorporate a template into your skill, and best practices for building multimodal skills. To dive deeper into APL, register for our next webinar on Advanced Template Building with the Alexa Presentation Language to learn about template styling and layout best practices.
We can’t wait to see what you build!