Customer adoption of multimodal devices is growing, as millions of customers are choosing Alexa-enabled devices with screens. In fact, customer engagement with multimodal skills is higher than voice-only skills. On average, APL-based multimodal skills see more than 3x the amount of monthly active users compared to voice-only skills on multimodal devices.
As customers continue to seek out the best multimodal experiences, we will be deprecating Display templates features on Aug. 31, 2021, to allow greater support of multimodal devices through the Alexa Presentation Language (APL). Unlike Display templates that only work on a subset of Alexa multimodal devices and restrict developers to only using pre-defined layouts, APL-based Responsive Templates are supported on all Echo Show devices, Fire tablets, recent TVs by LG/Samsung, Facebook Portal devices, the Alexa for Xbox app, and PCs. Responsive templates will help you create beautiful layouts that are responsive across screen sizes, and support is being added for new and additional third-party devices all the time through the Alexa Smart Screen SDK.
To prepare for this deprecation and ensure your skills continue to work on devices as they are added, we have simplified the process of converting your existing code to support APL. Below is an example of how you can update your Display Templates skill backend to render APL documents instead. The following Body Template 6 code...
if (supportsDisplay(handlerInput)) {
const responseBuilder = handlerInput.responseBuilder;
const bgImage = new Alexa.ImageHelper()
.addImageInstance('https://example.com/background.png')
.getImage();
const primaryText = new Alexa.RichTextContentHelper()
.withPrimaryText('Example of a text content')
.getTextContent();
responseBuilder.addRenderTemplateDirective({
type: 'BodyTemplate6',
backButton: 'visible',
backgroundImage: bgImage,
textContent: primaryText,
});
}
... can be replaced with the following in APL code for the AlexaHeadline template:
if (supportsAPL(handlerInput)) {
const responseBuilder = handlerInput.responseBuilder;
const document = {
"type": "APL",
"version": "1.6",
"import": [
{
"name": "alexa-layouts",
"version": "1.3.0"
}
],
"mainTemplate": {
"parameters": [
"headlineTemplateData"
],
"item": [
{
"type": "AlexaHeadline",
"primaryText": "${headlineTemplateData.textContent}",
"headerBackButton": true,
"backgroundImageSource": "${headlineTemplateData.backgroundImage}"
}
]
}
};
const datasources = {
"headlineTemplateData": {
"backgroundImage": "https://example.com/background.png",
"textContent": "Example of a text content"
}
};
responseBuilder.addDirective({
type: 'Alexa.Presentation.APL.RenderDocument',
version: '1.1',
document,
datasources
})
}
Take a look at this mapping to see how the rest of the Display Templates translate to Alexa Responsive Templates.
Looking for another convenient way to change Display Template code to APL? Check out this cool converter, created by the APL Ninja, Alexander Martin @xeladotbe, from our developer community.
To support this transition, we’re also adding new text styling options to APL that were available in Display Templates. You will be able to change inline text size and colors through new paragraph text layout options, using the <span> markup tag in the Text Component. <span> expands on the <font> functionality in Display Templates. In particular, <span> will enable you to change inline text sizes through setting density-independent pixels (dp) for a desired piece of text, and setting customizable colors for spans of text.
<span fontSize="48dp">APL</span> is <span color="red">Awesome</span>!
The three other Display Templates markup tags (<img> to add inline images, <action> for clickable content, and <div> for centering content) are not supported in APL. You can achieve similar — an in most cases, better — outcomes through APL-specific code implementations for text and image formatting.
Arunjeet Singh, a leader from our Alexa Multimodal team has said this of the new features: “APL templates are very easy to use and allow for a great degree of customization of visual skills. In addition, APL templates support many more features than Display Templates, such as motion detection APIs. User engagement on APL based skills is at an all time high and APL based skills have seen an increase in active users since converting from Display Templates.”
You might be wondering what happens if you don't upgrade your skills to APL. If you don't complete the migration to APL, your skill won't be removed from the Skill Store. However, skills using Display Templates won't look as they did before. For example, <action> and <div> tags won't work. Touch-based element selection also won't retain functionality, so skills using those features might have a broken experience.
To help you quickly recertify your updated skills, we will be expediting your skill certification process. Please include the following text in your testing instructions when you submit the skill for certification “Skill has been upgraded to APL as part of Display Templates deprecation.” Please contact alexa-certification-apl-migration@amazon.com if you encounter any issues with certification.
Join other great skills like Akinator, Knight Manager, and Question of the Day, as well as first party experiences like Shopping, Weather, Music, Jokes, Timers, Alarms, and Reminder already using APL. To learn more about these new features, check out the latest APL documentation here.
What is APL?
Alexa Presentation Language (APL) is a visual design framework which enables developers to create engaging voice and visual experiences for customers across Alexa multimodal devices (e.g. the Echo Show family) as well as 3rd party devices. APL is an upgrade over legacy Display Templates. APL has been the multimodal visual design language of choice since September 2019. Over the past few years, many external skills have migrated to it, and all internal Amazon experiences now run on it.
Who can use APL?
Any developer of multimodal experiences in Alexa, including internal Amazon developers, as well as external skills developers. If you would like to include visual experiences in your skill, APL is the way to go.
How are my skills impacted?
If your skill uses Display Templates, please plan to migrate to APL as soon as possible. The <font> tag functionality will be added to APL, while the other 3 tags (<img>, <action>, and <div>) will not. See below for instructions on how the three tags map to APL.
When do I need to migrate my skills to APL?
We are asking developers to plan to complete migration by Aug. 31, 2021. We have created a detailed migration guide of how Display Templates map to Alexa Responsive Templates.
Do I need to submit my skill for re-certification?
Yes, skills will need to be re-certified. However, we will expedite the re-certification process for impacted skills. Please add the following text, along with any additional testing instructions, when you submit your skill for re-certification : "Skill has been upgraded to APL as part of Display Templates deprecation."
How will the <font> tag functionality be supported in APL?
A new <span> markup tag will replace <font> for changes to the text component font size and font color. Individual spans within a line of text can set their own font size and/or font color. A new fontSize attribute can now be used to set a different font size within a <span> of text. A new color attribute can now be used to set a different color within a <span> of text.
How does the <action> tag map to APL?
For short text, use the Text component inside a TouchWrapper to make it clickable. Read the blog post on TouchWrapper best practices and how to design for longer clickable text.
{
"type": "Container",
"items": [
{
"type": "Text",
"text": "This is a"
},
{
"type": "TouchWrapper",
"spacing": "8dp",
"item": [
{
"type": "Text",
"text": "clickable",
"color": "dodgerblue"
}
],
"onPress": [
{
"type": "SendEvent",
"arguments": [
"my-token-value"
]
}
]
},
{
"type": "Text",
"spacing": "8dp",
"text": "element"
}
],
"direction": "row"
},
How does the <img> tag map to APL?
For short lines of text, use a Container component with the direction set to row. Place Text and Image components in the Container to display the text and images side-by-side. Be sure to test the result on different viewports to ensure that the text and images display as you expect. Consider redesigning your experience for longer text.
{
"type": "Container",
"items": [
{
"type": "Text",
"text": "This is an inline"
},
{
"type": "Image",
"source": "https://upload.wikimedia.org/wikipedia/commons/c/cc/Amazon_Alexa_App_Logo.png",
"scale": "best-fit",
"align": "left",
"spacing": "8dp",
"height": "48dp",
"width": "48dp"
},
{
"type": "Text",
"spacing": "8dp",
"text": "image of the Alexa icon."
}
],
"direction": "row"
},
How does the <div align> tag map to APL?
Format the desired text through the textAlign prpoperty.
{
"type": "Container",
"items": [
{
"type": "Text",
"text": "This is"
},
{
"type": "Text",
"spacing": "8dp",
"text": "centered",
"textAlign": "center",
"textAlignVertical": "auto"
},
{
"type": "Text",
"spacing": "8dp",
"text": "text"
}
],
"direction": "column"
}
