What's New in APL 2022.2

December 2022 tooling updates (December 12, 2022)

The December 2022 launch includes new tooling features for Alexa Presentation Language (APL).

APL linting and autocomplete in the authoring tool

The code editor in the APL authoring tool provides improved linting for coding errors, such as missing required properties, incorrect use of APL attributes, and other syntax issues. Error messages provide links to documentation and details about how to correct the problem.

The APL authoring tool also now supports auto-completion of APL language constructs. As you type, the tool shows possible APL properties, primitive components, commands, and event handlers.

For details about the authoring tool, see Create and Edit an APL Document.

Alexa icon package

The Alexa icon package provides a set of provides a set of icons defined in Alexa Vector Graphics (AVG) format. Use these icons with the AlexaButton and the new AlexaIcon responsive components.

For example, set the new buttonIconName property on AlexaButton to the name of an icon. The button displays the icon next to the button text. You can also define buttons that display an icon and no text.

To use the icon package, import alexa-icon into your document.

For details about the package, see Alexa Icon Package. For a reference to the icons available in the package, see Alexa Icon Library Reference. For details about how to show an icon on AlexaButton, see Button icons. For details about the new AlexaIcon component that displays an icon, see Alexa Icon.

Accessibility

The responsive components and templates provide better support for accessibility. Components and templates now set defaults for the accessibility labels. For example, the accessibilityLabel for AlexaButton now defaults to the text you provide in the buttonText property. As you build your document, review these defaults and provide alternative text as needed.

Interactive responsive components set the accessibility role automatically. Screen readers use the role to describe the component and explain to the user how to interact with it. For example, the AlexaButton component sets role to button.

For details about building accessible APL documents, see the APL Accessibility Guide.

Responsive components and templates

Version 1.6.0 of the alexa-layouts package provides several updates to the responsive components and templates.

• AlexaButton – Supports displaying an icon on the button. Use the following new parameters:
  • buttonIconName
  • buttonIconSource
  • buttonIconStyle

  You can display an icon from the icon library, or a custom icon built in AVG format. For details, see Button.

• AlexaDetail – Supports an additional button, intended as an external link. Use the following new parameters:
  • externalLinkButtonTheme
  • externalLinkButtonText
  • externalLinkButtonPrimaryAction
  • externalLinkButtonAccessibilityLabel

  For details, see Detail.

• AlexaDivider – Supports both horizontal and vertical dividers. Use the new dividerDirection parameter to set the direction. For details, see Divider.
• AlexaHeader – Supports centering the header content. Set the new headerHorizontalAlignmentCentered parameter to true to center the content. For details, see Header.
• AlexaImage – Supports displaying a gradient overlay over the image. Set the following parameters to configure a gradient overlay:
  • overlayGradient
  • gradientLowerInputRange

  For details, see Image.

• AlexaImageList and AlexaImageListItem – Supports hiding the divider between items. Set the hideDivider parameter. For details, see Image List and Image List Item.

Import the Alexa packages into your APL document

To use the latest components, templates, styles, and resources, update your APL document to import the latest versions of the packages.

For an overview of the components and templates, see Responsive Components and Templates.

APL version

The current APL version number hasn't changed and remains at version 2022.2.

APL 2022.2 (October 18, 2022)

Alexa Presentation Language (APL) 2022.2 introduces new features and capabilities for APL. APL 2022.2 was released on October 18, 2022.

Resume commands during configuration changes

You run the Reinflate command to re-display a document after a configuration change, such as the user flipping a device between portrait and landscape. This command previously stopped any running commands, which interrupted actions like reading out audio or paging through a pager.

The Reinflate command has a new property, preservedSequencers. You can specify an array of command sequencers to continue to run after the document reinflates.

For details, see the Reinflate command.

Work with APL versions

In your APL document, set the version to "2022.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 2022.2. Note that the session, request, and viewport properties are omitted 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": "2022.2"
            }
          }
        }
      },
      "apiEndpoint": "https://api.amazonalexa.com",
      "apiAccessToken": "eyJ..."
    },
    "Viewport": {}
  },
  "request": {}
}

Related topics

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

Last updated on 2022-12-13