Preview an APL Document
Use the authoring tool to preview how your document renders to your users.
For a visual response, you can see how the document looks on devices of different sizes and preview tap events, commands, video, and other aspects of the document. For an audio response, you can listen to the audio clip generated by the document.
Preview a visual response
For a visual response, you can view your document in different viewports as you build. Use preview mode to further test tap events, commands, and other aspects of your document.
View your document in different viewports
Click the icons for the different viewports in the viewport toolbar. The viewports are organized by the type of device, then viewport:
- Hub
- Hub Round Small
- Hub Landscape Small
- Hub Landscape Medium
- Hub Landscape Large
- Hub Landscape Extra Large
- Hub Portrait Medium
- TV
- TV Landscape Extra Large
- Mobile
- Mobile Small
- Mobile Medium
- Mobile Large
- Custom

To preview the document with a specific profile
- Click the device type, such as Hub, and then click the the icon for the viewport you want to see, such as the Hub Landscape Medium icon.
For viewport profiles that support a size range, actual viewport sizes for popular devices display in a drop-down list under the viewport profile icons. Use these to verify that your APL document works in all the popular devices that fall within the viewport profile. Make sure that your document works on the smallest width/height within a range but also responds to the largest width/height by filling out the extra space. To learn how to create responsive APL documents, see Build Responsive APL Documents.
To preview the document with a specific device
- Select the device from the Device Presets menu in the upper right.
Viewport profile resources (viewport profiles package)
The viewports in the authoring tool correspond to the viewport profile resources available in the viewport profiles package:
- Hub Round Small –
hubRoundSmall
- Hub Landscape Small –
hubLandscapeSmall
- Hub Landscape Medium –
hubLandscapeMedium
- Hub Landscape Large –
hubLandscapeLarge
- Hub Landscape Extra Large –
hubLandscapeXLarge
- Hub Portrait Medium –
hubPortraitMedium
- TV Landscape Extra Large –
tvLandscapeXLarge
- Mobile Small –
mobileSmall
- Mobile Medium –
mobileMedium
- Mobile Large –
mobileLarge
For example, suppose your document uses a when
statement on a component as shown in the following example.
{
"type": "Text",
"when": "${@viewportProfile == @hubLandscapeSmall}",
"text": "Display this text on small, landscape hubs."
}
When you preview the document in the authoring tool and select Hub Landscape Small, the document displays this Text
component. When you select any other profile, this Text
component doesn't display.
For more details about the properties of these viewport profiles, see Alexa Viewport Profiles Package.
Create and view a custom viewport
Create a custom viewport to see how your design looks on devices that are different from the provided profiles.
Custom viewports remain available while the document is open in the authoring tool. When you close the browser or navigate away from the open document, the custom viewports are deleted.
To create a custom viewport
- In the top viewport toolbar, click Custom, and then click the plus (+) button.
- Enter a name for the viewport, then enter the Width, Height, and Density.
- Click the checkmark to save the custom viewport.
To preview your document in a custom viewport
- In the top viewport toolbar, click Custom.
- In the custom toolbar, click the name of the custom viewport to view.
Preview tap events, commands, and video
Use preview mode to preview touch events, commands, video, and other aspects of document. Preview mode disables the tools for authoring the document. Clicking in the preview pane triggers tap events as it would on a device.
Use preview mode to test the following:
- Commands – Test any commands triggered within the document. For example, test a
SpeakItem
command triggered byonMount
or a tap event. - APL and APL for audio integration – Your document can use the APL for audio transformer (
aplAudioToSpeech
) to convert an APL for audio document into audio for use with theSpeakItem
orSpeakList
command. You can test this integration in the authoring tool in preview mode. For details, see Test the APL and APL for audio integration. - Run
onMount
commands – The document-levelonMount
command automatically runs when you start preview mode, as it does when the document loads on a device. Any component-levelonMount
commands also run when the component is displayed. - Video playback – The
Video
component plays as it does on a device. - Transformers – Transformers work as they do on a device.
- Tap events – Click on the touchable areas of your document to select an item.
- Navigation – For a
Pager
component, click and drag in the document to "swipe" through pages. ForSequence
andScrollView
components, use a mouse scroll wheel to scroll the content.
Preview mode doesn't support testing the SendEvent
command. To test SendEvent
, use a device or the simulator and test your document within the skill.
As you test in preview mode, use the Viewport profiles toolbar to preview in different viewports. Switching to a different viewport stops any running commands or video. When the document displays with the new viewport, the preview resets to the initial state of the document.

To open preview mode
In the authoring tool, click Preview Interactions in the upper-right corner.
The authoring tool disables the editing controls, displays a preview of your document, and runs any applicable onMount
commands.
Replay the preview
Click the Replay button to restart preview mode. Replay stops any running commands or video and then resets the preview to the initial state of the document. For example, this button re-runs any document-level onMount
commands and resets any Pager
components to display the configured initial page.
To exit preview mode
Click the Preview Interactions again.
Preview an audio response
To preview an audio response
- In the authoring tool, click Preview button to generate the audio the first time.
- Click Play to hear the audio response.
- As you make changes to the JSON, click Refresh to re-generate the audio response with your changes.
After you generate the audio response, the authoring tool displays a time line that represents the audio. You can navigate this time line to play back portions of your response.

UI Element | Description |
---|---|
|
Refresh button – Click to regenerate the audio response. You must regenerate the response to reflect your changes to the JSON. |
|
Play button – Click to play back the response. |
|
Repeat button – Click to repeatedly play the entire response or a portion of the response. Click again to turn off the repeat. |
|
Audio response time line – Displays a wave form representing the audio response. You can click within the time line to listen to different parts of the response.
|
Test the APL and APL for audio integration
The aplAudioToSpeech
transformer converts an APL for audio document into audio you can bind to the speech
property of an APL component. You can then use the SpeakList
or SpeakItem
command to play that audio.
When you use the aplAudioToSpeech
transformer in your skill, you must provide an APLA document for the audio in the sources
property of the RenderDocument
directive. The SOURCES section of the authoring tool simulates this property. Fill in this section with the same object you would provide in sources
. This lets you test commands that depend on the output of the transformer aplAudioToSpeech
transformer.
To test the APL for audio transformer in the authoring tool
- Open the APL document for your visual response in the authoring tool.
-
Click SOURCES. Provide the same JSON object you would include in the
sources
property ofRenderDocument
. This is a JSON object containing a map of APL for audio documentsFor example, the following JSON in SOURCES creates a mapping between the string "helloApla" and an APL for audio document (details removed for brevity).
{ "helloApla": { "version": "0.91", "type": "APLA", "mainTemplate": { "parameters": [ "payload" ], "item": {} } } }
-
In the DATA section, paste or create your data source. Include the
aplAudioToSpeech
transformer. Set thetemplate
field of the transformer to the key you defined for your APLA document in the SOURCES section.{ "helloData": { "properties": { "user": { "name": "" } }, "transformers": [ { "template": "helloApla", "outputName": "aplaHelloSpeech", "transformer": "aplAudioToSpeech" } ] } }
-
In your APL document, bind the
speech
property of a component to the output of theaplAudioToSpeech
transformer. Set theSpeakItem
orSpeakList
command to target that component.In this example, the
outputName
isaplaHelloSpeech
. Therefore, the generated audio ispayload.helloData.properties.aplaHelloSpeech.url
.{ "type": "AlexaButton", "alignSelf": "center", "buttonText": "Play the APL Audio!", "speech": "${payload.helloData.properties.aplaHelloSpeech.url}", "primaryAction": { "type": "SpeakItem" }, "spacing": "@spacingLarge" }
- Click Preview Interactions and invoke the
SpeakItem
orSpeakList
command. The authoring tool generates the APLA audio and plays it as a device.
For details about setting up and using the aplAudioToSpeech
transformer, see Transformers.
For details about building APL for audio documents, see APL for audio Reference.
You can adjust the APL for audio document in the SOURCES section as needed, then update your skill's RenderDocument
response to return the revised document.
When you send your document to Alexa with the RenderDocument
directive, your skill code must build out and include the APL for audio sources as part of RenderDocument
in the sources
property. Alexa doesn't use the sources saved in the authoring tool when rendering the actual response from a skill.
For details about RenderDocument
see Alexa.Presentation.APL Interface Reference.
Related topics
Last updated: Sep 12, 2022