Alexa.Presentation.APL (v1.0)
The Alexa.Presentation.APL
namespace contains APIs that provide a receipt of Alexa Presentation Language (APL) responses, consisting of documents and commands, to an Alexa Built-in device.
Capability Assertion
Alexa.Presentation.APL 1.0 may be implemented by the device on its own behalf, but not on behalf of any connected endpoints.
New AVS integrations must assert support through Alexa.Discovery, but Alexa will continue to support existing integrations using the Capabilities API.
Sample Declaration
{ "interface": "Alexa.Presentation.APL", "type": "AlexaInterface", "version": "1.0", "configurations": { "runtime": { "maxVersion": "1.2" } } }
UserEvent Event
Send an UserEvent
event from the device to Alexa when a SendEvent
command is executed, such when a user presses a button. This action directly sends the event to Alexa.
The Alexa Skill that owns the APL document receives the event.Always send the UserEvent
event along with a complete Context
object. See Context for more details.
Sample UserEvent Event message
The following sample code shows the structure for a UserEvent
event message:
{ "header": { "namespace": "Alexa.Presentation.APL", "name": "UserEvent", "messageId": "56fd9e9b-132c-4ebf-949e-e84e7a517c00" }, "payload": { "presentationToken": "OPAQUE_TOKEN", "arguments": [ "rideTypeSelected", 2, "shared" ], "source": { "type": "Touchable", "handler": "onPress", "id": null, "value": null }, "components": { "component1": "value1", "component2": 3 } } }
UserEvent Event Payload Parameters
The following table lists the payload parameters for the UserEvent
event:
Field | Type | Description |
---|---|---|
presentationToken | STRING | Opaque token for the active presentation. |
arguments | OBJECT | Array of argument data to pass to Alexa. |
source | OBJECT | Populate the source section of the payload with meta-information about the event trigger. |
components | OBJECT | The components property is a list of component IDs. Report the value of each of component in the event, which allows an Alexa Skill developer to construct a form to directly send form contents to the server. |
Example (APL snippet inside of the APL template)
The following snippet shows a sample event where a user requests a ride from a rideshare:
{ "type": "Touchable", "onPress": { "type": "SendEvent", "arguments": [ "rideTypeSelected", "${ordinal}", "${data.dataToSend}" ] } }
RenderDocument Directive
The RenderDocument
directive renders a visually rich document by delivering a template document, datasources, and component "packages" to a device.
Because packages can include images and other files, their potentially large sizes can negatively impact performance and user experience. Make sure that the total size of the directive does exceed 24 kilobytes to prevent a negative user impact. See the JSON Response Format Reference.
RenderDocument Directive message format
The following sample code shows the structure for a RenderDocument
directive:
{ "header": { "namespace": "Alexa.Presentation.APL", "name": "RenderDocument", "messageId": STRING, "dialogRequestId": STRING }, "payload": { "presentationToken": STRING, "document": {{OBJECT}}, "datasources": {{OBJECT}}, "packages": {{LIST}} "windowId": {{STRING}} “supportedViewports”: [ {"mode": "hub", "shape": "round", "minWidth": 480, "maxWidth": 480, "minHeight": 480, "maxHeight": 480}, {"mode": "hub", "shape": "rectangle", "minWidth": 1024, "maxWidth": 1024, "minHeight": 600, "maxHeight": 600}, {"mode": "hub", "shape": "rectangle", "minWidth": 1280, "maxWidth": 1280, "minHeight": 800, "maxHeight": 800}, {"mode": "tv", "shape": "rectangle", "minWidth": 960, "maxWidth": 960, "minHeight": 540, "maxHeight": 540} ] } }
RenderDocument Payload Parameters
The following table lists the payload parameters for the RenderDocument
directive:
Payload Field | Type | Description |
---|---|---|
token | STRING | Unique identifier for the presentation. |
document | OBJECT | APL document template for the device to use to structure a rendered presentation. |
datasources | OBJECT | Data sources to bind to the rendered document. |
packages | LIST | List of packages to render, including layouts, styles, and images. |
windowId | STRING | Identifies which window to render the specified APL document. |
supportedViewports | ARRAY | Array of viewport specifications that are supported by the specified APL document. |
About the supportedViewports parameter
Alexa validates the values in the supportedViewports
according to the following rules:
- The supported viewports must contain at minimum one viewport for each of the following combinations:
- mode = TV & shape = RECTANGLE
- mode = HUB & shape = ROUND
- mode = HUB & shape = RECTANGLE
- For devices with a round shape, Alexa assumes that the device is circular, so specifications with inconsistent
minWidth
+minHeight
ormaxWidth
+maxHeight
are invalid. - The total length of the JSON-encoded viewport specification must not exceed 2KB.
- All viewport entries must exactly match one of the entries defined in the following snippet:
[ {"mode": "HUB", "shape": "ROUND", "minWidth": 480, "maxWidth": 480, "minHeight": 480, "maxHeight": 480}, {"mode": "HUB", "shape": "RECTANGLE", "minWidth": 1024, "maxWidth": 1024, "minHeight": 600, "maxHeight": 600}, {"mode": "HUB", "shape": "RECTANGLE", "minWidth": 1280, "maxWidth": 1280, "minHeight": 800, "maxHeight": 800}, {"mode": "TV", "shape": "RECTANGLE", "minWidth": 960, "maxWidth": 960, "minHeight": 540, "maxHeight": 540} ]
ExecuteCommands Directive
The Alexa.Presentation.APL.ExecuteCommands
directive runs an array of APL commands on APL documents that have been previously rendered and share the same templateToken
.
ExecuteCommands Directive message format
The following sample code shows the structure for a ExecuteCommands
directive:
{ "header": { "namespace": "Alexa.Presentation.APL", "name": "ExecuteCommands", "messageId": string, "dialogRequestId": string }, "payload": { "presentationToken": string, "commands" : [ { "type": enum, "description" : string, "delay" : long, "screenLock" : boolean, "when" : boolean, ... }, ... ] } }
ExecuteCommands Payload Parameters
While the commands themselves can vary, the following table lists the common properties that are shared by all commands that can be included in an ExecuteCommands
array.
Property | Type | Required | Description |
---|---|---|---|
type | Enum | Yes | Defines the command type and the dictates which properties must/can be included. Valid values are "ControlMedia", "SpeakItem", and "SpeakList". |
description | String | No | Placeholder property that can be used for documentation. |
delay | Integer | No | Delay (in milliseconds) before the command starts executing. Must be a non-negative integer. Default is 0. |
screenLock | Boolean | No | If true, disable the Interaction Timer. When a command with screenLock=true finishes executing, the Interaction Timer timer resets to 0. |
delay | Boolean | No | If true, execute the command. If false, ignore the command. Commands that are ignored also ignore the screenLock. |
ExecuteCommands Examples
This section contains sample snippets for the commands that are currently supported by the ExecuteCommands
directive.
ControlMedia Example
{ "header": { "namespace": "Alexa.Presentation.APL", "name": "ExecuteCommands", "messageId": "string", "dialogRequestId": "string" }, "payload": { "presentationToken": "string", "commands" : [ { "type": "ControlMedia", "componentId": "recipe_video_player", "command": "play" }, ] } }
SpeakItem Example
{ "header": { "namespace": "Alexa.Presentation.APL", "name": "ExecuteCommands", "messageId": "string", "dialogRequestId": "string" }, "payload": { "presentationToken": "string", "commands" : [ { "type": "SpeakItem", "componentId": "myJokeSetup", }, ] } }
SpeakList Example
{ "header": { "namespace": "Alexa.Presentation.APL", "name": "ExecuteCommands", "messageId": "string", "dialogRequestId": "string" }, "payload": { "presentationToken": "string", "commands" : [ { "type": "SpeakList", "dataSource": "movieList", "start": 3, "count": 3, "minimumDwellTime": 700, "align": "center" }, ] } }
Command Sequencing for ExecuteCommands
The ExecuteCommands
directive does not directly handle sequencing of commands. Instead, assign the array of commands one of the two "types" to define how to execute the commands:
- Sequential: Execute the commands in the specified sequential order.
- Parallel: Execute the commands simultaneously in parallel.
If the Alexa Skill does not include either sequencing command, the default behavior is to execute the commands in the array in sequence.
Command Sequencing Examples
This section shows sample code snippets for each of the three use cases for ExecuteCommands
.
No sequencing commands
The following snippet executes SpeakItem
followed by ControlMedia
:
{ "header": { "namespace": "Alexa.Presentation.APL", "name": "ExecuteCommands", "messageId": "string", "dialogRequestId": "string" }, "payload": { "presentationToken": "string", "commands" : [ { "type": "SpeakItem", "componentId": "ingredientList" }, { "type": "ControlMedia", "componentId": "recipe_video_player", "command": "play" } ] } }
Sequential command execution
The following snippet executes SpeakItem
followed by ControlMedia
:
{ "header": { "namespace": "Alexa.Presentation.APL", "name": "ExecuteCommands", "messageId": "string", "dialogRequestId": "string" }, "payload": { "presentationToken": "string", "commands" : [ { "type" : "Sequential", "commands" : [ { "type": "SpeakItem", "componentId": "ingredientList" }, { "type": "ControlMedia", "componentId": "recipe_video_player", "command": "play" } ], } }
Parallel command execution
The following snippet executes SetOpacity
and SpeakItem
in parallel.
{ "header": { "namespace": "Alexa.Presentation.APL", "name": "ExecuteCommands", "messageId": "string", "dialogRequestId": "string" }, "payload": { "presentationToken": "string", "commands" : [ { "type" : "Parallel", "commands" : [ { "type": "SetOpacity", "componentId": "jokePunchline", "delay": 100, "value": 1 } { "type": "SpeakItem", "componentId": "jokePunchline" } ] } ] } }