What's New in APL 2023.3

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

Conditional imports

You now have more options when you import external packages into your APL document. You can use new import types and data-binding expressions to conditionally select the package or packages to load. You can also declare dependencies and require a particular package to load after a different package.

For example, you could load one package for hub devices and a different package for TV devices. This flexibility can improve performance and make it easier to manage complex packages.

For details, see APL Import.

Support for inserting and removing items

The new InsertItem and RemoveItem commands let you update the child items for a component at runtime. Use the onChildrenChanged event handler to watch for these changes and commands.

For details, see InsertItem Command, RemoveItem Command, and onChildrenChanged

Control over scrolling and paging animation speed

When you use an APL scrolling command to scroll a ScrollView or Sequence, you can control the speed of the scrolling animation with the new targetDuration property. Set to the duration in milliseconds, or set to zero to turn off the scrolling animation completely. The Scroll, ScrollToIndex and ScrollToComponent commands support this new option.

When you use an APL paging command to advance a Pager, you can control the speed of the paging animation with the new transitionDuration property. Set to the duration in milliseconds, or set to zero to turn off the paging animation completely. The SetPage and AutoPage commands support the new property.

Accessibility improvements

The component actions property now accepts new standard actions for scrolling. For details, see APL Base Component Properties

Gradient backgrounds for Frame components

Set the new background property on a Frame to either a gradient or color. This new property takes precedence if you provide values for both background and the legacy backgroundColor.

Support for data arrays in the Parallel and Sequential commands

The Parallel and Sequential commands now support a data property that accepts an array of values. When provided, the command iterates over this array and builds a new Sequential command for each item in the array. For details, see Parallel Command and Sequential Command.

Support for variable-sized viewports

The viewport object in the data-binding context has additional properties to report on the size of a viewport and whether that size can adjust:

• autoHeight
• autoWidth
• minHeight
• minWidth
• maxHeight
• maxWidth

For details about viewport sizing, see About viewport size. For details about how the size of the viewport and the size of the top-level component interact, see Understand viewport layout.

Other updates

• The String functions available in data-binding expressions now include the charAt() function to return the character in a string at a specified index. For details, see String functions
• The VectorGraphic component has a parameters property for explicitly passing parameters to the Alexa Vector Graphic (AVG) to display. You can continue to pass parameters as properties on the component as well. For details, see AVG object parameters.
• When you request an extension in an APL document, you can set a new required flag. When true, the document won't load and render unless the extension is present. For details, see Request an extension in the APL document.
• You can use data-binding expressions in the settings property for an extension. However, the data-binding expressions are limited to the properties available in the initial data-binding context. You can get information about the device, such as environment, but not data from a data source.

Updated 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 reference for 2023.3, see APL Cheat Sheets.

APL versions and Amazon device support

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

Work with APL versions

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

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

Related topics

• Add Visuals and Audio to Your Skill
• APL Known Issues

Last updated: Dec 04, 2023