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.

To learn how to integrate the APL Core Library, see the APL Core Library repo 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.0 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.0",
  "configurations": {
    "runtime": {
      "maxVersion": "1.2"
    }
  }
}

RenderedDocumentState context entry

Alexa expects a client to report RenderedDocumentState to communicate the current onscreen APL elements with each event that requires context.

For more details, see Context and the APL Core Library repo and documentation.

Sample message

The following sample code 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.0.x.x",
        "componentsVisibleOnScreen": [{
          "id": "list4050",
          "position": "100x200+30+50:1",
          "visibility": 1,
          "tags": {
            "focused": true,
            "list": {
              "itemCount": "2"
            }
          }
        }]
      }
    }
  ]
}

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 repo and documentation.
payload.token string No Id for the visual context captured in current event and sent originally by the skill.
payload.version string No Version of the UI component on the device. Follows the format created by renderedListState.

UserEvent event

Send an UserEvent event from the device directly to AVS when a SendEvent command is executed, 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 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. 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.

RenderDocument directive

The RenderDocument directive renders a visually rich document by delivering a template document and datasources to a device.

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}},
        "windowId": {{STRING}}
        “supportedViewports”: [ Array of supported viewports ]
    }
}

RenderDocument 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.
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

ExecuteCommands directive

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.

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" : array of commands,
          ...
        ]
    }
}

ExecuteCommands 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:

</tr>
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 execute on the rendered APL document identified by the presentation token. Execute each command in the array sequentially, rather than in parallel.