What's New in APL 2023.2

Alexa Presentation Language (APL) 2023.2 introduces new features and capabilities for APL.

Deferred evaluation for data binding

When APL evaluates a property or bound variable, expressions written with the ${...} syntax are evaluated and resolved. Sometimes, you might want to defer this evaluation to later and control when to resolve an expression. With APL version 2023.2 and later, you can use the #{...} placeholder and the eval() built-in function to defer expression evaluation. You can also use eval() to evaluate expressions that aren't evaluated automatically, such as expressions within a data source.

For details and examples, see APL Data-Binding Syntax .

APL component property changes

The following component properties have changed:

  • The entities base component property is now dynamic. You can use the SetValue Command to update the entities property on a component. You can also set the entities property to a value that changes automatically, such as ${elapsedTime}. Your skill can access the value of the entities property in the visual context included with the skill request. For details, see APL Visual Context in the Skill Request.
  • The source property for the VectorGraphic is now dynamic. Use the SetValue command to change the graphic during run time. For details, see source property.
  • The ControlMedia command now has an additional seekTo sub-command you can pass to the command property. Use this command to move the video player forward or backward to an absolute position. For details, see ControlMedia Command.

New APL cheat sheets

The APL cheat sheets provide a quick reference guide that provides information about the syntax and semantics of an APL document and its components, commands, and properties in a concise and digestible format. To download this new reference, see APL Cheat Sheets.

Other changes

The SetState command is now considered deprecated. Although the command continues to work, it isn't the correct way to change the state of a component.

To change the disabled or checked state, use the SetValue command. To change the focused state, use the SetFocus, and ClearFocus commands.

For details, see Component state.

Work with APL versions

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

A user can invoke your skill on older devices that don't 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 2023.2. This example omits the session, request, and viewport properties 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": "2023.2"
            }
          }
        }
      },
      "apiEndpoint": "https://api.amazonalexa.com",
      "apiAccessToken": "eyJ..."
    },
    "Viewport": {}
  },
  "request": {}
}
Was this page helpful?

Last updated: Jun 30, 2023