Base Command Properties

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

An Alexa Presentation Language (APL) command is a message that can change the visual or audio presentation of the content on the screen.

Common properties

A single command is encoded as a JSON object. All commands contain the following properties.

Property	Type	Default	Description
`type`	String	Required	Type of the command
`description`	String	—	Optional documentation for this command
`delay`	Integer	0	Delay time in milliseconds before this command runs. Must be non-negative. Defaults to 0.
`screenLock`	Boolean	`false`	When true, disable the interaction timer.
`sequencer`	String	—	Specify the sequencer that should run this command.
`when`	Boolean	`true`	Conditional expression. When the expression evaluates to `false`, skip the command. Defaults to `true`.

type

Specifies the particular command to run. This can be a pre-defined primitive command type or the name of a user-defined command.

delay

The delay value is the amount of time in milliseconds inserted before running this command. The delay value must be a non-negative integer, which if not specified, defaults to 0. The delay value is ignored if the when property resolves to false, or if the command runs from within an event handler.

screenLock

If true, the interaction timer is disabled while this command runs. When a command with screenLock=true finishes running, the interaction timer is reset to 0.

The screenLock applies to the entire extent of the command including any defined delay. For example, the following command holds the screen lock for 30 seconds:

{
  "type": "Idle",
  "delay": 30000,
  "screenLock": true,
}

sequencer

When specified, identifies the name of the sequencer to use for this command. The following rules determine the sequencer for a command. APL uses the first rule that applies.

If the sequencer property for the command has a value, the command runs in normal mode on the specified sequencer. This is true even when the command started from an event handler that normally runs in fast mode.
If the command started from a fast mode handler, run normally in fast mode. Commands don't have a sequencer when running in fast mode.

For details about which handlers run in fast mode or normal mode, see Fast mode.
If the command is a subcommand of another command, run in normal mode on the sequencer specified by the parent command.

The following commands can have subcommands:
- OpenURL
- Parallel
- Select
- Sequential
Finally, when none of the previous rules apply, run the command in normal mode on the "MAIN" sequencer.

For details about the command sequencer, see Command sequencing.

when

If when is set to true, run the command. If false, ignore the command. Commands that are ignored also ignore the screenLock property.

Reinflation strategy

The Reinflate command reinflates the document, which by default ends any running commands. You can change this default by defining a sequencer for the command, and preserving that sequencer with the preservedSequencers property on the Reinflate command.

For any command, when the command runs on a preserved sequencer and the Reinflate command runs, the remaining delay for the command is saved.

For example, assume an Idle command has delay set to 2000 ms and 1000 ms have elapsed when a reinflate occurs. After reinflation, the Idle command continue to run for the remaining 1000 ms specified in delay.

All commands can have a delay. Some commands take time to run, such as AutoPage and SpeakItem. These commands resume after reinflation when run on a preserved sequencer. Refer to the reinflation strategy section for a command to understand how the command behaves when it is preserved during reinflation.

Was this page helpful?

Provide feedback

Last updated: frontmatter-missing