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 or maxWidth + 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"
              }
            ]
          }
        ]
    }
}
Amazon Alexa
Amazon Appstore
Amazon Web Services
Amazon Dash Replenishment