Test APL Examples with the Code Sandbox

Note: Learn how to improve your skills with APL with Build visually rich experiences using APL at the Alexa Learning Lab.

Some Alexa Presentation Language (APL) examples in the documentation display in the code sandbox. For APL examples, you can see how a device with a screen renders the APL code. For APL for audio examples, you can listen to the audio generated by the code. You can change the code and then see or hear how Alexa renders your changes.

Experiment with visual APL features

The preview pane automatically updates as you make changes in the code editor. For example, change the value of the primaryText property to a different string, and note the changes in the preview.

Examples that use the onMount handler

The onMount event handlers run when the sandbox loads and displays the APL document. Refresh the page or edit the code to reload the APL document and run these handlers again.

For example, the following document uses onMount to start the AutoPage command for a pager after two seconds. To reload the document and restart this command, refresh the page.

Interact with the preview pane

Most interactive features work in the sandbox. For example, you can test interactive components that run APL commands. Click to simulate touch events. Click and drag to simulate scrolling. For details about features not supported, see Sandbox limitations.

Test widgets and the data store

An Alexa widget displays quick, essential information related to a skill and lets users perform quick actions without leaving the current screen context or asking for updates. A widget can also access the data store, which is area on the device that stores data that your widget APL document can display. You use the Data Store REST API to update the data store.

The code sandbox displays widget examples with the Data Store tab to simulate setting up the data store and sending commands to update it.

The Data Store tab displays the following panes.

Data Store Contents – Displays a JSON object that represents the current data in the data store. The object includes the namespace and key for the data store. In the earlier example, the namespace is LocationWeather and the key is weather. This pane is read-only.
Initial Data Store – Displays the data store commands that create the initial data store data. Change data in this pane to simulate setting up the widget with different data. The widget preview pane updates to reflect the changes.
Commands – Provides a space for entering new commands to test. Some of the examples include a sample command in this pane. Change or enter the command to run and click Execute Commands to update the data store.

The Data Store tab has the following buttons.

Set to Initial – Updates the data store contents to reflect the commands entered in the Initial Data Store pane. Note that this action doesn't erase changes you made to the Initial Data Store pane. For example, if you edited the data in the Initial Data Store, then used the Commands pane to further change the data store, the Set to Initial button restores the initial data store to your edited version.
Edit Data Store – Displays the Initial Data Store and Commands panes for editing.
View Data Store – Displays the Data Store Contents pane.
Execute Commands – Runs the commands specified in the Commands pane.

To revert all changes in the example to the original version, click the Reset button.

Not all widget examples in the sandbox use the data store. You can still experiment with the data store for these examples. Add support for the data store extension to the sample document and then add data-binding expressions to access the data store data. Then, define the initial data store commands to populate the data store on the Data Store tab.

For details about the data store, see APL Data Store Extension. For details about widgets, see About Widgets and Alexa Presentation Language (APL).

Listen to APL for audio examples in the sandbox

The audio sandbox requires a developer account to generate and play the audio. If you have an Amazon retail account, you must complete developer account registration before you can generate audio in the sandbox. For details about creating a new developer account or linking an Amazon.com account to a developer account, see Create Your Amazon Developer Account.

To listen to an example in the sandbox

If you aren't signed in to the developer portal, click Sign in and follow the prompts to sign in with your developer account.
Click Load Audio. This action generates the audio and displays a waveform that represents the sound. 3/ Click Play to hear the audio.

To start playback from a different position or jump to a different position during playback, click in the time line.

If you make changes to the code, click Reload audio to generate a new clip that reflects your changes.

Sandbox limitations

The code editor doesn't save your changes. When you refresh the page or click the Reset button, the code shown in the editor reverts to its original state. The Reset button resets the APL Document / APLA Document and Data Sources tabs. Use the Copy button to copy your code to save or use within a skill.

Limitations (APL)

The sandbox doesn't connect to a skill, so you can't test the SendEvent command.
The sandbox doesn't support testing APL transformers, such as the textToHint or ssmlToSpeech transformer.
The sandbox doesn't support testing the VoiceView screen reader. Use a device to test a document for accessibility.

Limitations (APL for audio)

The sandbox behaves as an English US device. Examples play using the default US English voice unless you use the voice and lang Speech Synthesis Markup Language (SSML) tags with the Speech component.
The environment.alexaLocale property always returns en-US.

Known issues

For APL for audio, if you sign in with an Amazon.com account that isn't linked to a developer account, attempting to load the audio displays the error "We had an issue with the request. Please come back and try later." To solve this issue, complete the developer account registration. For details, see Create Your Amazon Developer Account.

Was this page helpful?

Provide feedback

Last updated: Dec 06, 2023