Optimize APL Document Updates Performance

From the topic Optimize APL Document Rendering you know that rendering new APL documents on screen devices is a technical effort that costs time depending on the complexity of your APL template. For this reason, you should, whenever possible, reuse an already rendered APL document and update the existing UI. This is the more efficient alternative to responding to subsequent user requests.

For example, the user interacts with your APL document, which you’ve previously rendered on screen at the launch of your skill, by tapping a button. Or, the user just sees the button on the screen, and then selects the button by speaking to Alexa and reading out loud the button label text. For details about the options available to you for responding to this user request, see Understand APL Lifecycles.

Update APL documents in response to voice requests

The following diagram shows the technical steps that are usually taken when the screen device updates an already rendered APL document. In this case, the update begins when the user request comes in as a voice command. For example, the user views your rendered APL document and discovers a “Play now” button. Instead of tapping the button, the user says, "Alexa, play now."

The following timeline shows the technical steps that are taken after a user makes a voice request and your Alexa skill processes the request before updating an already rendered APL document on screen.

Technical steps to update an APL document in response to a voice request
Technical steps to update an APL document in response to a voice request

The eight technical steps that are taken to update an already rendered APL document in response to a voice request are as follows:

Before you learn the details about all of these steps, it is helpful for you to understand this process as it is perceived by the user. Refer to the illustrated timeline and the time stamps in parentheses in the following sequence:

  • At (t0), the user finishes an interaction, such as speaking or tapping a UI button as part of your APL document.
  • Between (t0) and (t5), the user sees the device working on the request. On Echo Show devices, this is indicated by a blue loading bar at the bottom of the screen.
  • At (t5), the user receives a voice response from Alexa in case the skill returns output speech.
  • At (t6), the devices begins to update the UI based on instructions that the skill has sent to the device.
  • At (t7), the UI updates have finished with the possible exception of media assets, such as images and video that continue to load up gradually until (t8).
  • At (t8), the user sees the entirely updated UI in response to the initial request that was made at (t0).

Step 1: Alexa processes the user request

The screen device receives user input as a voice command; for example, when the user reads out loud button text. It processes the request in the cloud, and then forwards it to your Alexa skill. For details about how to reduce latency in this step, see Step 1 in Optimize APL Document Rendering.

Step 2: Your skill receives the request

Your Alexa skill code that usually runs inside an AWS Lambda function receives the request, and then resolves it to one of its request handlers. For details, see Step 2 in Optimize APL Document Rendering.

Step 3: Your skill prepares data to be displayed

Sometimes, UI updates need more data from your source to visually respond to the user request. If you use dynamic list data and a user requests to see more product items, your skill needs to read out the next group of product list items from the database. For details about how to optimize for performance when you load data from an external data source, see Step 3 in Optimize APL Document Rendering.

Step 4: Your skill sends back update instructions to the device

After the data is loaded and prepared, your skill code needs to respond to the device by completing one of the following actions:

  • Construct and return an ExecuteCommand directive — Do this to run APL commands to change an already rendered APL document on screen. For example, use SetValue commands to change dynamic APL component properties to change their visual appearance, such as a font color or display state. Or, use a PlayMedia command to start playing a video inside an APL Video component that is part of your already rendered APL document on screen.
  • Construct and return an UpdateIndexList directive — Do this to add, change, or remove items from your dynamic list data source. Changing dynamic list data from your template data source cause multi-child components, such as an APL GridSequence, to populate updated list data automatically if their data property is linked to it.
  • Return an empty or regular skill response — Your skill isn’t required to update the UI in response to an incoming user voice request. Instead, it might respond with output speech to acknowledge the request or provide an update verbally.

You can improve performance in this process step by performing the following actions:

  • Avoid replicating complex APL command structures — These structures are already part of your rendered APL document on screen. This can happen if a user voice request represents a UI action, such as a button press. For example, a user says, "Alexa, press the submit button." To provide a consistent user experience, the skill needs to replicate UI behavior by returning a similar set of APL commands that are also executed in an onPress event handler of an APL TouchWrapper component that is the “Submit” button. To avoid this replication, your APL template should leverage APL user-defined commands to encapsulate command logic that is used for handling certain user events within the template. This makes the commands reusable for the skill, as well. Instead of returning a replicated set of APL commands, your skill code can now return an ExecuteCommand directive that just runs a single user-defined command that is also being used to handle a user event within the template.
  • Keep within response size limits — Keep the number of APL commands or list item updates at a reasonable level so you don't exceed byte size limits that exist for skill responses.

Step 5: APL template is processed by Alexa and sent to the device

The skill response is returned to the Alexa cloud to be validated, processed, and sent to the screen device of a skill user. For details, see Optimize APL Document Rendering.

Step 6: Alexa speaks, plays audio

The device returns output speech or plays an audio response as it is returned by the skill.

  • Be aware of directive sequencing behavior — Returned output speech and some of APL’s directives are sequentially processed by the APL runtime on the device. An ExecuteCommand directive or UpdateIndexList directive only execute after Alexa finishes speaking. This might lead to an undesired user experience. In this case, you can only mitigate problems by shortening or removing output speech from the skills response, or use the APL SpeakItem command to play back audio, such as speech.

If there is no output speech or audio response returned by the skill, this step is omitted. Step 7 processes immediately.

Step 7: Execute directives as returned from the skill

APL runtime fulfills the skills request for updating the UI on the rendered document. This is done by running APL commands from the ExecuteCommand directive, or updating the dynamic list data source as instructed in an UpdateIndexList directive.

Step 8: Load embedded media files

If a UI update implies displaying new images, or starting playback of a new video or audio, the process continues by gradually pulling media files from their content sources, such as your CDN provider. For details about how to optimize for lower latency media loading in APL templates, see Step 10 in Optimize APL Document Rendering.

Update APL documents in response to UI events

Unlike voice requests, UI events are captured within the APL template on the device instead of coming in over the Alexa cloud interface. At this point, the cloud round trip to your skill isn’t implicit, but entirely optional. This can result in significant performance improvement.

The following diagram shows the technical steps that are usually taken when you update an already rendered APL document in response to a user interaction as it is captured by your APL template. For example, the user looks at your rendered APL document and discovers a “Play now” button. The user taps the button.

The following timeline shows the technical steps that are taken after a UI event is captured on the device and your APL template processes the request before it is updated on screen.

Technical steps to update an APL document in response to a UI event
Technical steps to update an APL document in response to a UI event

Refer to the previous diagram and the time stamps in parentheses in the following sequence:

  • At (t0), the user interaction is finished; for example, the user releases the UI button after pressing it. Since this event is captured in one of your APL template’s event handlers, the processing begins immediately. Usually, you use APL commands to trigger actions, such as changing a visual property like a background color, etc.
  • At (t1), your APL commands have executed and the visual UI changed accordingly. If any of the UI changes imply showing a new image or playing back video or audio, the process continues to load gradually.
  • At (t2), all media files, such as images, have completed loading and are rendered on the device.

At this point, the UI update is finished. Given that there is no round trip to the cloud involved, there is no network latency or cloud processing time added. Whenever possible, use this approach. This is the best performing option because updates appear to the user almost instantly. However, there are cases in which you still need to initiate a cloud round trip to your skill. For instance, you need to fetch new data from your database to show on screen, or you want your skill backend to keep track of UI interactions as they happen locally on the device. Any of the following actions can initiate a cloud round trip:

  • In the most common scenario, you have an APL SendEvent command as part of your APL commands that are executed in Step 1 of this process. SendEvent commands create and send out a UserEvent to your skill.
  • If you use a dynamic list data source and you link it to a scrollable list view, the APL runtime creates and sends out a LoadIndexListData request to your skill if the user has scrolled near the end of the list view. • Likewise, if you bound a dynamic list data source to a paginated item view, such as an APL Pager, the runtime creates and sends a LoadTokenListData request to your skill if the user nears the last page of items on screen.

For details about what happens in a cloud roundtrip, what might cause higher latency, and how to optimize this process for higher performance, see Update APL Documents in Response to Voice Requests.

Was this page helpful?

Last updated: Nov 28, 2023