What's New in APL 2024.1


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

APL tooling updates

Debug APL documents with logging in the authoring tool

When you preview a document in the authoring tool, the preview now includes a log window. Use the log window to display logging messages sent with the Log command. This can be useful for debugging your document.

For details about defining log messages, see Log Command. For details about using the log window, see Debug a document with the log window.

Use APL code snippets in Visual Studio Code

The Alexa Skills (ASK) Toolkit for Visual Studio Code (VS Code) now supports automatic completion of APL language constructs, including components and commands. The tool suggests APL properties as you type your APL document in the VS Code Editor. For more about the code snippets, see the pull request on GitHub.

Respond to changes in bound variables

Components, layouts, and Alexa Vector Graphics (AVG) support bound variables, which you define with the bind property. A bound variable is a local variable that your document can access from the data-binding context of the component and its children.

For components and layouts, these bound variables now support an onChange handler. You can define commands to run when the value of the variable changes. For details, see APL Bound Variables.

Bound variables on vector graphics don't support the onChange handler.

Capture and respond to events when components change visibility

APL generates events when the visibility of a component changes. You can use a handleVisibilityChange event handler to capture these events and run commands. For example, you can run commands in response to an item scrolling into view.

Visibility change events trigger for two types of changes: when the opacity of the item changes, or when the visible percentage of the item's bounding box changes.

For details, see Visibility Change Event Handlers.

Test your documents for localization issues up front

A new "pseudo-localization" mode for the document lets you test how UI elements in your document might appear when localized into different languages. Pseudo-localization is a mock translation which mimics the space required by a string after real world translation. For example, the pseudo-locale version of the string "Hello World" is "[Ħḗḗŀŀǿǿ Ẇǿǿřŀḓ]." The resulting string, although still readable, occupies more space and height than the original.

You can use pseudo-localization mode to identify any issues with UI layout, including truncation and overflow, that might occur when you actually translate the text into other languages.

To enable pseudo-localization mode, use the settings.pseudoLocalization property in your document. For details, see Settings.

Other updates

  • A new Map.keys() function returns an array the keys for a map. For details, see Map functions.

APL versions and Amazon device support

The following table indicates the newest version of APL available on Amazon devices.

Device Latest APL version Notes

Echo Show 15

2023.3

Release date to be announced

Echo Show 10

2023.3

Release date to be announced

Echo Show 8 (1st generation)

2024.1

Echo Show 8 (2nd and 3rd generation)

2023.3

Release date to be announced

Echo Show 5 (1st and 2nd generation)

2024.1

Echo Show 5 (3rd generation)

2023.3

Release date to be announced

Echo Show

2023.3

Release date to be announced

Echo Spot

2023.3

Release date to be announced

Echo Hub

2023.3

Release date to be announced

Fire TV

2023.2

Release date to be announced

Fire tablet

2022.2

Release date to be announced

Work with APL versions

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

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 2024.1. 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": "2024.1"
            }
          }
        }
      },
      "apiEndpoint": "https://api.amazonalexa.com",
      "apiAccessToken": "eyJ..."
    },
    "Viewport": {}
  },
  "request": {}
}

Was this page helpful?

Last updated: Mar 11, 2024