Alexa.Presentation.APL 1.1
The Alexa.Presentation.APL
interface contains APIs that provide a receipt of Alexa Presentation Language (APL) responses, consisting of documents and commands, to an Alexa Built-in device.
To learn how to integrate the APL Core Library, see the APL Core Library repository and documentation.
To learn more about visual responses for the Alexa Voice Service (AVS) and related APIs, see Alexa Presentation Language (APL) Overview.
Capability assertion
A device may implement Alexa.Presentation.APL 1.1 on its own behalf, but not on behalf of any connected endpoints.
For new AVS integrations, assert support through Alexa.Discovery. However, AVS provides support for existing integrations through the Capabilities API.
Sample declaration
{ "interface": "Alexa.Presentation.APL", "type": "AlexaInterface", "version": "1.1", "configurations": { "runtime": { "maxVersion": {{STRING}} } } }
runtime
Parameter | Description | Type |
---|---|---|
maxVersion | STRING | Specifies the max version of the APL runtime supported by the device. The Alexa.Presentation.APL 1.1 directives require implementation of the 1.3 version of the APL Core runtime, at a minimum. For more details, see APL Core runtime. |
Because APL is backward-compatible, a content author could send any APL document declaring a version of APL up to the maxVersion
. For example, a content author shouldn't send an APL document requiring 1.3 features to a device that only supports up to 1.2 version of the runtime, but the author could send a document declaring 1.0, 1.1, or 1.2. For more details, see APL document version
property.
The following table shows the minimum and maximum allowed runtime versions for maxVersion
:
Min or Max? | Allowed versions |
---|---|
Minimum supported runtime version | 1.3 |
Maximum supported runtime version | 1.x |
Context
RenderedDocumentState
Alexa expects a client to report RenderedDocumentState
to communicate the current onscreen APL elements with each event that requires context. The presentationSession
object helps Alexa to track the session Id from the device.
For more details, see Context and the APL Core Library repository and documentation.
Sample message
The following example shows the structure for a RenderedDocumentState
context entry:
{ "context": [ { "header": { "namespace": "Alexa.Presentation.APL", "name": "RenderedDocumentState", "payloadVersion" : "1" }, "payload": { "token": "token", "version" : "Alexa.Presentation.APL-1.1.x.x", "componentsVisibleOnScreen": [{ "id": "list4050", "position": "100x200+30+50:1", "visibility": 1, "tags": { "focused": true, "list": { "itemCount": "2" } } }] "presentationSession": { "skillId": "MY_SKILL_ID", "id": "MY_ID" }, } } ] }
Context properties
Property | Type | Required? | Description |
---|---|---|---|
header.namespace | STRING | Yes | Namespace of the new state. Fixed value: Alexa.Presentation.APL |
header.name | OBJECT | Yes | Name of the new state. Fixed value: RenderedDocumentState |
header.payloadVersion | STRING | Yes | Payload version. |
payload.componentsVisibleOnScreen | ARRAY OF OBJECTS | No | Container for the list of the visible components on screen. For more details, see APL Core Library repository and documentation. |
payload.token | STRING | No | Id for the visual context captured in current event and sent originally by the skill. This value is the same as the presentationToken value reported by the original RenderDocument directive |
payload.version | STRING | No | Version of the UI component on the device. Amazon recommends using some combination of agentName and agentVersion as defined in the APL Data-Binding Evaluation Environment object. |
payload.presentationSession | OBJECT | Yes | A compound object to uniquely identify the presentation session. |
payload.presentationSession.skillID | STRING | Yes | ID of skill that owns the presentation session. |
payload.presentationSession.ID | STRING | Yes | Unique string identifying the instance of a skill. |
Events
LoadIndexListData
Send a LoadIndexListData
event from the device to AVS to load more items into a dynamicIndexList
.
Sample event message
The following example shows the structure for a LoadIndexListData
event message:
{ "event": { "header": { "namespace": "Alexa.Presentation.APL", "name": "LoadIndexListData" }, "payload": { "presentationToken": "OPAQUE_TOKEN", "correlationToken": "CORRELATION_TOKEN"", "listId": "MY_LIST", "startIndex": 0, "count": 5 } } }
Payload parameters
The following table lists the payload parameters for the LoadIndexListData
event.
Field | Type | Required | Description |
---|---|---|---|
presentationToken | STRING | Yes | Presentation token specified in the RenderDocument directive sent to the device. |
correlationToken | STRING | Yes | Identifier generated by a device to correlate requests with their corresponding directives. Max-length 1024 chars, case sensitive. |
listId | STRING | Yes | The identifier of the list whose items to fetch. Max-length 1024 chars, case sensitive. |
startIndex | INTEGER | Yes | The lowest index of the items to fetch, inclusive. Valid range: -231 → 231-1 (incl.) |
count | INTEGER | Yes | The number of items to fetch. Valid range: 1 - 1024. Examples: startIndex = 10, count = 2: Alexa should return items at indexes 10 and 11. startIndex = -2, count = 5: Alexa should return items at indexes -2, -1, 0, 1 and 2 |
UserEvent
Send an UserEvent
event from the device directly to AVS when running a SendEvent
command, such when a user presses a button.
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 event message
The following code example 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 } } }
Payload parameters
The following table lists the payload parameters for the UserEvent
event. The SendEvent command provides the source of the properties for UserEvent
.
Field | Type | Description |
---|---|---|
presentationToken | STRING | Opaque token for the active presentation. |
arguments | OBJECT | Array of argument data to pass to Alexa. For more details, see the APL Core Library repo and documentation. |
source | OBJECT | Populate the source section of the payload with meta-information about the event trigger. For more details, see the APL Core Library repo and documentation. |
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 developer to construct a form to directly send form contents to the server. For more details, see the APL Core Library repo and documentation. |
RuntimeError
Send a RuntimeError
event to notify a skill about any errors that occurred during APL processing. This request is for notification only. Skills can't return a response to a RuntimeError
request.
Sample event message
The following sample code shows the structure for a RuntimeError
event message:
{ "header": { "namespace": "Alexa.Presentation.APL", "name": "RuntimeError", }, "payload": { "presentationToken": {{STRING}}, "errors": [ { "type": "LIST_ERROR", // Required. "reason": {{STRING}}, // Required. Type of error "listId": {{STRING}}, // Required. Field is specific to the LIST_ERROR type. "listVersion": {{INTEGER}}, // Optional. Field is specific to the LIST_ERROR type. "operationIndex": {{INTEGER}}, // Optional. Field is specific to the LIST_ERROR type. The index of the operation which caused the error (when known) "message": {{STRING}}, // Required. See examples for each error condition in the table above. } ] } }
Payload parameters
The following table lists the payload parameters for the RuntimeError
event.
Field | Type | Required | Description |
---|---|---|---|
presentationToken | STRING | Yes | Presentation token that identifies the APL experience. |
errors | ARRAY | Yes | An array of reported errors. |
error.type | ENUM | Yes | Error type indicator. Current valid value is 'LIST_ERROR'. |
error.reason | STRING | Yes |
Describes the type of error which occurred. The following values are valid:
|
error.listId | STRING | Yes | Specific to the LIST_ERROR error type. Contains the identifier of the list which encountered the error. |
error.listVersion | INTEGER | No | Specific to the LIST_ERROR error type. Contains the listVersion specified by the update that encountered the error, if known. |
error.operationIndex | INTEGER | No | Specific to the LIST_ERROR error type. Contains the index of the operation that caused the error, if known. |
error.message | STRING | Yes | Text description of the error. |
Directives
RenderDocument
The RenderDocument
directive renders a visually rich document by delivering a template document and data sources to a device. The presentationSession
object tracks the session id to help with back navigation.
Message format
The following example 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}}, "windowId": {{STRING}}, "timeoutType": {{STRING}}, "supportedViewports": {{ARRAY OF SUPPORTED VIEWPORTS}} "presentationSession": { "skillId": {{STRING}}, "id": {{STRING}} }, } }
Payload parameters
The following table lists the payload parameters for the RenderDocument
directive:
Payload Field | Type | Description |
---|---|---|
presentationToken | 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. |
windowId | STRING | Identifies which window to render the specified APL document. |
timeoutType | STRING | Specifies the expected duration of the timeout of the document in the device and whether to persist the document in the background. Valid values are SHORT, TRANSIENT, and LONG. SHORT – 30 Seconds. The activity doesn't persist in the background. TRANSIENT – 10 Seconds. The activity doesn't persist in the background. LONG – No default timeout. The activity defines the task closure. The activity persists in the background if needed. |
supportedViewports | ARRAY | Array of viewport specifications that the specified APL document supports. For more details about viewport support, see Select the Viewport Profiles Your Skill Supports. |
presentationSession | OBJECT | A compound object to uniquely identify the presentation session. |
presentationSession.skillId | STRING | ID of skill that owns the presentation session. |
presentationSession.id | STRING | Unique string identifying the instance of a skill. |
ExecuteCommands
The Alexa.Presentation.APL.ExecuteCommands
directive runs an array of APL commands on APL documents that have been already rendered and share the same presentationToken
.
Message format
The following code example shows the structure for a ExecuteCommands
directive:
{ "header": { "namespace": "Alexa.Presentation.APL", "name": "ExecuteCommands", "messageId": {{STRING}}, "dialogRequestId": {{STRING}} }, "payload": { "presentationToken": {{STRING}}, "commands" : {{ARRAY OF COMMANDS}}, ... ] } }
Payload parameters
Although the commands themselves might vary, the following table lists the common properties that all commands share and that an ExecuteCommands
array might include:
Property | Type | Required | Description |
---|---|---|---|
type | DIRECTIVE | Yes | Set to Alexa.Presentation.APL.ExecuteCommands . |
presentationToken | STRING | Yes | String that tells the device about the RenderDocument command associated with the APL document for the commands. |
commands | ARRRAY OF COMMANDS | Yes | Commands to run on the rendered APL document identified by the presentation token. Run each command in the array sequentially, rather than in parallel. |
SendIndexListData
Alexa sends a SendIndexListData
directive to devices with the item data requested by a LoadIndexListData
event.
Message format
The following code example shows the structure for a SendIndexListData
directive:
{ "directive": { "header": { "namespace": "Alexa.Presentation.APL", "name": "SendIndexListData" }, "payload": { "presentationToken": {{STRING}}, "correlationToken": {{STRING}}, "listId": {{STRING}}, "listVersion": {{INTEGER}}, "startIndex": {{INTEGER}}, "minimumInclusiveIndex": {{INTEGER}}, "maximumExclusiveIndex": {{INTEGER}}, "items": {{ARRAY}} } } }
Payload parameters
The following table lists the common properties that a SendIndexListData
directive might include:
Field | Type | Required | Description |
---|---|---|---|
presentationToken | STRING | Yes | Presentation token supplied in the LoadIndexListData event. |
correlationToken | STRING | No | Correlation token supplied in the LoadIndexListData event. correlationToken is mandatory if the skill is responding to a LoadIndexListData request. Alexa rejects skill responses if the expected correlationToken is not specified in a single SendIndexListData directive. Omit the correlationToken if the skill is proactively sending list items. Max-length: 1024 chars, case sensitive. |
listId | STRING | Yes | Identifier of the list containing the items in this response. Only required if you don't specify a correlationToken ; however, always including listId reduces overhead and helps with debugging. Max-length: 1024 chars, case sensitive. |
listVersion | INTEGER | No | New version of the list following the update. Maintains list consistency between the skill and device. Lists should start at version 0, so the first UpdateIndexListData directive issued for a particular list should have a listIndex value of "1". The device buffers any UpdateIndexListData specifying an out-of-sequence listVersion until processing any missing or intermediate directives. |
startIndex | INTEGER | Yes | Index of the first element in the items array. Required when a fast-scroll request exceeds available list locations. Valid range: -231 → 231-1 (incl.) |
minimumInclusiveIndex | INTEGER | No | Index of the first item of the skill-managed array. When populated, this value replaces any specified value from a previous interaction. Continued absence of this property indicates that the minimum index is not yet known and further backwards scrolling is possible. If this value equals the index of the first item returned, no further backwards scrolling is possible. Valid range: -231 → 231-1, inclusive. |
maximumExclusiveIndex | INTEGER | No | Last valid index of the skill-managed array, plus one. When populated, this value replaces any specified values in previous interactions. Continued absence of this property indicates that the maximum index is not yet known and further forwards scrolling is possible. If this value is greater than the index of the last item returned, no further forwards scrolling is possible. Valid range: -231 → 231-1, inclusive. |
items | ARRAY | No | Array of objects to add to the device cache. Each item's encoding in the array has a max-length of 2048 chars. |
UpdateIndexListData
The UpdateIndexListData
directive communicates dynamic list changes to the device. The directive may include multiple changes, such as insert, set, and delete operations.
Message format
The following sample code shows the structure for a UpdateIndexListData
directive:
{ "directive": { "header": { "namespace": "Alexa.Presentation.APL", "name": "UpdateIndexListData" }, "payload": { "presentationToken": {{STRING}}, "listId": {{STRING}}, "listVersion": {{INTEGER}}, "operations": [ { "type": InsertItem "index": {{INTEGER}}, "item": {{OBJECT}} }, { "type": InsertMultipleItems "index": {{INTEGER}}, "items": {{OBJECT ARRAY}} }, { "type": SetItem "index": {{INTEGER}}, "item": {{OBJECT}} }, { "type": DeleteItem "index": {{INTEGER}} }, { "type": DeleteMultipleItems "index": {{INTEGER}}, "count": {{INTEGER}} } ... ] } } } }
Payload parameters
The following table lists the common properties that a UpdateIndexListData
directive might include:
Field | Type | Required | Description |
---|---|---|---|
presentationToken | STRING | Yes | String that tells the device about the RenderDocument command associated with the APL document for the list. |
correlationToken | STRING | Yes | Identifier generated by a device to correlate requests with their corresponding directives. Max-length 1024 chars, case sensitive. |
listId | STRING | Yes | Identifier for the list from the RenderDocument datasources with the items to update. Max-length: 1024 chars, case sensitive. |
listVersion | INTEGER | Yes | The newest version of the list. Because all lists start at version 0, the first UpdateIndexListData directive issued for a particular list has a listVersion of 1. The device buffers a minimum of three UpdateIndexListData directives specifying an out-of-sequence listVersion until the device receives and processes any intermediate directives. Valid range: 1 → 231-1.
|
operations | ARRAY | Yes | Individual operations apply to the list, in order. Complete each operation, including updating the index locations of list items, before processing the next operation in the array. Any operation processing errors should cause the device to discard later operations in the array and to discard further attempts to update the items in the target datasource. See the individual tables for each operation type. |
InsertItem:
Field | Type | Required | Description |
---|---|---|---|
index | INTEGER | Yes | Index location in the existing list indicating where to insert the item. Increment the index for all existing list items after the new item by one. You can insert items at the end of the list, but you can't insert items at non-adjacent indexes. Valid range: -231 → 231-1. |
item | OBJECT | Yes | Item data to include at the specified list index. |
InsertMultipleItems:
Field | Type | Required | Description |
---|---|---|---|
index | INTEGER | Yes | Index in the existing list indicating the location to insert the first item. Insert the remaining items at sequentially increasing indexes. Increase the index for all existing list items at indexes after the insertion index by the length of the items array. You can insert items at the end of the list, but you can't insert items at non-adjacent indexes. Valid range: -231 → 231-1. |
items | OBJECT ARRAY | Yes | The array of item data to include at the specified list index. |
SetItem:
Field | Type | Required | Description |
---|---|---|---|
index | INTEGER | Yes | The index of the item to set or replace in the existing list. The definition and indexes of all other items in the list do not change. Attempting to set an item at an unpopulated index results in an error. Valid range: -231 → 231-1. |
item | OBJECT | Yes | The new item data for the specified list index. Don't exceed 2048 characters for the JSON encoding of each item. |
DeleteItem:
Field | Type | Required | Description |
---|---|---|---|
index | INTEGER | Yes | The index of the item to delete in the existing list. Decrease the index of all existing list items after the delete index. Attempting to delete an item at an unpopulated index results in an error. Valid range: -231 → 231-1. |
DeleteMultipleItems:
Field | Type | Required | Description |
---|---|---|---|
index | INTEGER | Yes | Index of the first item to delete in the existing list. Perform subsequent deletions at sequentially increasing indexes. Decrease the index for all existing list items after the deleted items by the number of deletions. Attempting to delete an item at an unpopulated index results in an error. Valid range: -231 → 231-1. |
count | INTEGER | Yes | Number of items at sequentially increasing indexes to delete. Valid range: 1 → 231-1. |
Last updated: Feb 25, 2021