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 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`	If true, disable the interaction timer.
`sequencer`	String	""	Specify the sequencer that should run this command.
`when`	Boolean	`true`	Conditional expression. If this evaluates to `false`, the command is skipped. Defaults to `true`.

type

Specifies the particular command to run. This may be a pre-defined primitive command types or 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

If specified, the sequencer property names the sequencer that this command should run on. The sequencer selection rules are (in order):

If the sequencer is specified, the command runs in normal mode on that sequencer.
Else, if the command is running in fast mode, run normally in fast mode
Else, if the command is a subcommand of a Sequential or Parallel command, run in normal mode on the sequencer of the Sequential or Parallel command.
Else, 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