What's New in APL 2024.3

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

Import packages dynamically

You can use the new ImportPackage command to import an APL package and then run commands after the package loads. This feature lets you delay loading lower-priority packages, but still minimize the time to display elements that rely on those packages.

For details about the command, see ImportPackage Command. For details about packages and the options you can specify for a package, see APL Package .

New FlexSequence component for displaying items

The new FlexSequence component displays a sequence of child components, similar to a Sequence. However, with a the FlexSequence, the child components can be non-uniform and the list wraps the child items by default. The component combines a scroll view with a series of repeated components and inflates a data set.

For details, see APL FlexSequence.

New functions for manipulating strings

The String property in the data-binding context provides three new string functions:

• String.indexOf(x,y[,z])
• String.lastIndexOf(x,y[,z])
• String.includes(x,y[,z])

For details, see String functions.

More information in the visual context

The visual context provides your skill with information about the content displayed on the screen when the user invokes an intent or triggers a user event. This context has been updated with additional properties.

• The componentsVisibleOnScreen object in the context object now reports the role for the component in the role property.
• The viewport tag now reports three new properties:
  • utcTime – The UTC time in milliseconds.
  • elapsedTime – The run time in milliseconds of this document.
  • trackedChanges – An array of changes to any components you requested to track with the new trackChanges component property.
• The media tag reports two new properties for the Video component:
  • muted – True if the media is muted.
  • audioTrack – The audio track the media plays on.

For details about the visual context, see APL Visual Context in the Skill Request.

Component changes

The base component has the following new properties:

• onCursorMove – An array of commands to run when a cursor moves in the active region for a component.
• trackChanges – An array of properties to track and report changes in the visual context. The new trackedChanges property in the visual context provides the changes.

For details about the base component properties, see APL Base Component Properties.

The Text component has the following updates:

• Use the <li> tag within the text property to display the text in a bulleted list.
• The following component properties are now dynamic, so you can change these properties with the SetValue command:
  • letterSpacing
  • lineHeight
  • maxLines
  • textAlign
  • textAlignVertical

For details about the Text component, see APL Text.

The Image component source property now supports the data URL type. For details, see source.

APL versions and Amazon device support

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

¹The original Echo Spot (released in 2017) supports APL and uses the Hub Round Small viewport. The Echo Spot (2024 release) is a smart alarm clock with a handcrafted UI. For optimal functionality and reliability, this device doesn't support APL for custom skills. Requests sent to your skill therefore don't show Alexa.Presentation.APL in the supportedInterfaces property. However, the device does support voice-only experiences. When a user interacts with your skill, the device displays the icon and name for your skill. Skills that use the AudioPlayer interface also show the playback controls and the custom audio metadata you provide in the AudioPlayer.play directive except for the backgroundImage. For details about the AudioPlayer directives, see AudioPlayer Interface Reference.

Work with APL versions

In your APL document, set the version to "2024.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 2024.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": "2024.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 18, 2024