Alexa.Presentation.APL 1.0

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 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
• Context
• Events
  • UserEvent
• Directives
  • RenderDocument
  • ExecuteCommands

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"
    }
  }
}

Context

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

Events

UserEvent

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 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
        }
    }
}

Payload parameters

The following table lists the payload parameters for the UserEvent event. The SendEvent command provides the source of the properties for UserEvent.

Directives

RenderDocument

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

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 ]
    }
}

Payload parameters

The following table lists the payload parameters for the RenderDocument directive:

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 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,
          ...
        ]
    }
}

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: