What's New in APL 1.3

Alexa Presentation Language 1.3 introduces new features and capabilities for APL.

New responsive components and templates

Use the new responsive components and templates to build APL responsive documents. To use the new components and templates, import the alexa-layouts package into your document. Be sure to specify 1.1.0 for the version.

{
  "import": [
    {
      "name": "alexa-layouts",
      "version": "1.1.0"
    }
  ]
}

For an overview of the components and templates, see Responsive Components and Templates.

For details about the new responsive components, see:

For details about the new responsive templates, see:

Lazy loading and dynamic data sources

Use lazy loading to progressively load items in large lists as the user scrolls through the content. This lets you send your datasource to Alexa in "piecemeal" fashion rather than attempting to send all the data at once.

You can also now update a datasource after you've already sent it to Alexa. You can add, edit, and delete items on the fly to change the data presented to the user.

For both of these features, you use the new dynamicIndexList data source type for your data. Then, use new APL directives and requests to send more data and datasource updates from your skill code as needed. See the following documents for details:

Simplified access to data sources in data-binding expressions

To bind a datasource to your document, you can now specify the key for your datasource in the mainTemplate.parameters array. This simplifies your data-binding expressions.

For example, in versions before 1.3, you would set mainTemplate.parameters like the following:

{
  "type": "APL",
  "version": "1.2",
  "mainTemplate": {
    "parameters": [
      "payload"
    ],
    "items": []
  }
}

Then you would write data binding expressions like the following:

${payload.myDocumentData.title}

With 1.3, you set mainTemplate.parameters like the following:

{
  "type": "APL",
  "version": "1.3",
  "mainTemplate": {
    "parameters": [
      "myDocumentData"
    ],
    "items": []
  }
}

Then write data binding expressions like the following:

${myDocumentData.title}

Documents that use "payload" as the mainTemplate.parameters do continue to work. However, the simplified form is recommended for new APL documents. Note that using other strings as the parameter does not work. You must use either "payload" or the data source key.

To use a dynamicIndexList data source in your document, you must use the data source key in the mainTemplate.parameter. Don't use the pre-1.3 "payload" parameter.

For more details about datasources, see APL Data Sources and Transformers.

General updates

APL Document properties

You can now specify these new properties in your document:

  • background property – You can now specify a background color or gradient for your document. When set, the device uses this color or gradient when loading your document. Note that this property has access to properties in the initial data-binding context, but it can't access data from data sources or document resources.
  • export – You can now identify the document elements you intend others to use when importing your document as a package. Verification and authoring tools can use export information to help the APL author build a well-structured document.

Commands

You can use the following new commands:

  • Select selects a single command from an array of commands and data.
  • Finish closes the current APL document and exits the skill.

Variables and functions for clocks and timers

The data-binding context now includes new top-level variables to get the time:

The data-binding context also includes a Time object, which is a collection of built-in Time functions for manipulating and formatting the time.

Work with APL versions

In your APL document, set the version to "1.3".

A user can invoke your skill on older devices that do not support the latest version of APL. When working with features introduced in a specific version of APL, provide an alternative experience for devices running earlier versions of APL. The environment.aplVersion property in the data-binding context returns the version of APL on the device. This property returns null for APL 1.0 and the actual version for 1.1 or later. Use this property in when statements to create conditional blocks based on version.

For example, this renders a VectorGraphic on a device with APL 1.1 or later, and an image for APL 1.0:

[
  {
    "type": "Image",
    "when": "${environment.aplVersion == null}",
    "width": 100,
    "height": 100,
    "source": "https://example.com/alternate/image/for/older/versions.jpg"
  },
  {
    "type": "VectorGraphic",
    "when": "${environment.aplVersion != null}",
    "source": "lightbulb",
    "width": 100,
    "height": 100,
    "scale": "best-fit"
  }
]

The APL version is also available in requests sent to your skill, in:

context.System.device.supportedInterfaces.['Alexa.Presentation.APL'].runtime.maxVersion

This example shows a request from a device with 1.3. Note that the session, request, and viewport properties are omitted for brevity.

{
  "version": "1.0",
  "session": {},
  "context": {
    "System": {
      "application": {
        "applicationId": "amzn1.ask.skill.1"
      },
      "user": {
        "userId": "amzn1.ask.account.1"
      },
      "device": {
        "deviceId": "amzn1.ask.device.1",
        "supportedInterfaces": {
          "Alexa.Presentation.APL": {
            "runtime": {
              "maxVersion": "1.3"
            }
          }
        }
      },
      "apiEndpoint": "https://api.amazonalexa.com",
      "apiAccessToken": "eyJ..."
    },
    "Viewport": {}
  },
  "request": {}
}

Previous APL versions

Amazon Alexa
Amazon Appstore
Amazon Web Services
Amazon Dash Replenishment