Reduce Latency for your APL Documents
Users expect skills to respond to their requests without any delays. When your skill includes a visual component, latency in displaying the content might degrade the user experience.
Use these best practices to improve the performance of your Alexa Presentation Language (APL) document and reduce the latency that the user might notice.
Use Alexa Vector Graphics (AVG) instead of images
Images make the content more engaging, but they can also increase latency. When you display an image in an APL document, the device must load the image from the image source URL that you provide.
You can decrease latency by displaying a vector graphic instead of an image. The Alexa Vector Graphics (AVG) format lets you define a graphic with JSON code. You then display the graphic by placing a VectorGraphic
component in your document.
For details about the AVG format, see Alexa Vector Graphics Format.
For details about the VectorGraphic
component, see VectorGraphic
.
Use dynamic data sources for long, scrolling lists
When you display a long, scrolling list of items, use a dynamic data source. You send your data to the device in smaller batches. Alexa requests additional data from your skill as the user scrolls through the list and your skill responds with an updated data source with the new data to display.
You can use progressive loading ("lazy loading") with the responsive templates that display lists:
When building your own document, you can use progressive loading with the following components:
To use progressive loading for your list
- Define your data source with your list items as a
dynamicIndexList
data source. For details, see dynamicIndexList data source. - In your APL document, bind the data source to the component that displays the list.
- When you use a responsive template, bind the data source to the
listItems
property. - When you build your own list from primitive components, such as
Sequence
, bind the data source to thedata
property.
For details, see Bind a dynamic data source to your APL document
- When you use a responsive template, bind the data source to the
- In your skill code, use directives to manage the list as the user scrolls. For details, see Use directives and requests to manage the list.
For a dynamic data source example, see APL Lazy Loading Lists Demo.
Limit the number of URL-based package imports
APL packages let you define common layouts in resources in a separate file and then import them into your document with the import
property. Packages are a key element for creating modular APL documents that are easier to maintain. However, package imports do impose a cost because the device must retrieve the package from a URL or from the cache before rendering your document. Furthermore, packages can import other packages, which can increase the load.
Guidelines when importing packages:
- Make sure you need all the packages you import. Remove any packages that you don't reference within your APL document.
- Importing a single, larger package is better than importing several small packages due to the time to open connections and download the package.
One good strategy to consider is to import alexa-layouts
for the responsive components and layouts, and then one additional custom package with your own custom layouts as needed.
Use the backstack to return to previous documents
The backstack extension lets users navigate to previously-viewed APL documents. When you use the backstack to go back to an earlier document, the device can render the document faster because the document was already inflated.
Using the backstack also eliminates any requirement to send a request to your skill and wait for your skill to return the RenderDocument
directive with the previous document.
For details about the backstack extension, see APL Backstack Extension.
Use layouts when possible
A layout works as a custom component built from primitive components and layouts. Layouts help you build more modular documents, which are easier to maintain. You can also re-use layouts in your document, which simplifies the code.
Using layouts helps reduce latency. The device caches the layouts when inflating your document. Therefore, the layout loads faster as the device displays your document.
For details about building a custom layout, see APL Layout.
Do on-device updates instead of round-trips to your skill code
You can use the SendEvent
command in your APL document to send a UserEvent
request to your skill. Your code handles this event and returns a response. The response might include content to speak, the RenderDocument
directive to display an updated APL document, or the ExecuteCommands
directive to run commands that update the existing document.
The SendEvent
command is useful for notifying your skill about updates taking place on the device and triggering Alexa voice responses, but relying on this "round-trip" between the device and your skill adds latency. Resending the RenderDocument
directive from the UserEvent
request to render an updated APL document is also a slower and more costly operation.
Instead, use APL commands to update the visual presentation directly without sending a request back to your skill and waiting on a response. Avoid resending the entire document with the RenderDocument
directive when possible.
You can then use the SendEvent
command after making the visual changes to notify your skill of the change if necessary. The user sees the visual update right away, without waiting on the round-trip back to your skill.
For example, the following array of commands updates a bound property called PressCount
, runs an animation to fade a Text
component into view, and then sends the skill a UserEvent
with the latest value of the bound property. From the user's perspective, the screen updates right away with no latency.
[
{
"type": "SetValue",
"property": "PressCount",
"value": "${PressCount + 1}"
},
{
"when": "${PressCount == 1}",
"type": "AnimateItem",
"duration": 2000,
"componentId": "buttonPressCount",
"value": {
"property": "opacity",
"to": 1
}
},
{
"type": "SendEvent",
"arguments": [
{
"buttonPressed": "pressCountButton",
"pressCount": "${PressCount}"
}
]
}
]
The following example shows the full APL document. The Count the presses button increments a counter and displays the total number of button presses on the screen. The Reset the count button resets the counter to zero and hides the text noting the number of button presses. Both buttons call SendEvent
to notify the skill of the current button press count after the other commands finish.
The following example shows a request handler for the UserEvent
generated by the two buttons. Because the SendEvent
takes place after the visual update, the delay during the round trip to the skill is less noticeable.
This code example uses the Alexa Skills Kit SDK for Node.js (v2).
const ButtonPressEventHandler = {
canHandle(handlerInput){
// Use this handler for both buttons
const requestEnvelope = handlerInput.requestEnvelope;
return Alexa.getRequestType(requestEnvelope) === 'Alexa.Presentation.APL.UserEvent'
&& (requestEnvelope.request.source.id === 'pressCountButton'
|| requestEnvelope.request.source.id === 'resetButton');
},
handle(handlerInput){
console.log("In the ButtonPressEventHandler");
// Get button data from the arguments and log it. In a real
// skill, we might save these values to persistent storage or
// create a voice response specific to the input
const buttonData = handlerInput.requestEnvelope.request.arguments[0];
console.log("We got data about the button press from the device.");
console.log("Button press reported: " + buttonData.buttonPressed);
console.log("Latest button press count: " + buttonData.pressCount);
// Return a spoken response just for the reset button.
if (buttonData.buttonPressed === 'resetButton'){
return handlerInput
.responseBuilder
.speak("I've reset your button count to zero.")
.getResponse();
}
}
};
For details about how APL commands work, see APL Commands. For the set of available commands, see Standard Commands
For details about the RenderDocument
directive and UserEvent
request, see Alexa.Presentation.APL Interface Reference.
Related topics
- APL for Screen Devices Reference
- Alexa.Presentation.APL Interface Reference.
- Add APL Support to Your Skill Code
Last updated: Nov 28, 2023