What's New in APL 2024.2

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

Base component properties

All components now have the following new base component properties:

• onLayout – This handler runs commands when the layout calculation for the component changes. For example, use onLayout to resize a Sequence to fit a specific number of child components of different sizes. For details, see the onLayout property.
• pointerEvents – This property controls whether the component is the target of pointer events, such as touch, cursor events, gestures, and hover. You can use the pointerEvents property to turn off pointer events for a component that displays on top of another component, to allow pointer events to pass through to the next component. For details, see pointerEvents.

Component-specific properties

Text component

The Text component now has the onTextLayout property. This handler runs commands when the text layout calculation for the Text component occurs. This can be useful for setting properties such as the font size based on the size of the component.

For example, you can use SetValue to reduce the font size of a text item so that the text doesn't truncate. For details, see onTextLayout.

Video component

The Video component now has the screenLock property. This property controls the document lifecycle during video playback.

For details, see screenLock.

Event context properties

The event context for the Sequence, GridSequence, and ScrollView components has been updated to include two new Boolean properties:

• allowForward – Reports true when there is room to scroll the component forward.
• allowBackwards – Reports true when there is room to scroll the component backwards.

These properties are available when the component is the source or target of an event, and are reported in event.source or event.target.

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

Related topics

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

Last updated: Sep 06, 2024