What's New in APL 1.5

Alexa Presentation Language 1.5 introduces new features and capabilities for APL.

APL for audio (beta)

The APL for audio beta has been updated to version 0.9. These release includes the following new features:

  • Resources – You can now define resources in your APL for audio documents. A resource is a named constant that you use to specify a value instead of hardcoding values. You can create conditional resources based on characteristics of the user's device. Using resources helps simplify your APL code and ensure consistency. For details about creating and using resources, see Resources.
  • Compositions – You can now define compositions in your APL for audio documents. A composition combines components into a new "custom" component that you can use and reuse within the main template of your document. You can use conditional logic within the composition to choose which components to render in the final audio clip. Using compositions helps simplify your APL code and ensure consistency. For details about creating and using compositions, see Compositions.
  • Authoring tool updates – The authoring tool now provides additional tools for previewing your audio response:
    • You can click in the time line to listen to different portions of your response.
    • You can select a portion of the time line to play.
    • You can turn on a repeat mode to repeatedly play back the entire response or a portion response.

    For details about the authoring tool for APL for audio, see Use the authoring tool for APL for Audio.

APL responsive components and templates

Use the new and updated responsive components and templates to build APL responsive documents. To use the new components and templates, import the alexa-layouts package into your document. Be sure to specify 1.2.0 for the version.

{
  "import": [
    {
      "name": "alexa-layouts",
      "version": "1.2.0"
    }
  ]
}

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

New responsive components

For details about the new responsive components, see:

Updated responsive components and templates

APL 1.5 updates existing responsive components and templates.

  • AlexaButton – The AlexaButton component has the following changes:
    • The buttonStyle property now takes additional styles: ingress and egress.
    • The component has a new touchForward property to change the button text style.
  • AlexaTransportControls – The AlexaTransportControls component has new properties to define accessibility text. Voice over reads the string when the user selects the control on the screen. You can set the following new properties:
    • accessibilityLabel
    • secondaryControlsLeftAccessibilityLabel
    • secondaryControlsRightAccessibilityLabel

  • AlexaTextList – The AlexaTextList template now supports the new AlexaSwipeToAction component. This new component has the same properties as AlexaTextListItem. This lets you create a text list in which users can swipe the items to take an action.

    The change adds the following new properties to AlexaTextList so that you can set defaults for the swipe items:

    • swipeDirection
    • swipeActionIcon
    • swipeActionIconType
    • swipeActionIconForeground
    • swipeActionIconBackground
    • onSwipeMove
    • onSwipeDone
    • optionsButton1Text
    • optionsButton1Command
    • optionsButton2Text
    • optionsButton2Command

New image filters

APL now supports a larger set of image filters to create different effects:

  • Blend – Merges two images together with a defined operation mode.
  • Color – Creates a solid color image and appends it to the array of images. Combine this filter with Blend to apply the color to your image.
  • Gradient – Creates a gradient image and appends it to the array of images. Combine this filter with Blend to apply the gradient to your image.
  • Grayscale – Converts the image to grayscale.
  • Saturate – Changes the color saturation of the image.

As part of this change, the Image component now takes an array of image URLs in the source or sources property.

For details about how filters work, see Filters.

Alexa Vector Graphics (AVG) improvements

The Alexa Vector Graphics (AVG) format now supports filters to apply effects to the graphic. The first available filter applies a drop-shadow to the graphic. For details, see AVG filters.

The AVG format also now supports multiple-child inflation. You can pass the AVG object an array of data in the data property. The graphic inflates one item out of the items array for each element in the data array. For details, see Alexa Vector Graphics Format.

General updates

  • When a Sequence is the source or target of an event, the event generated includes details about both fully visible child components and partially-visible child components. See Sequence event object.
  • When a GridSequence is the source or target of an event, the event generated includes details about both fully visible child components and partially-visible child components. See GridSequence event object.

New function calls

The String.length() function returns the length of a string in Unicode code points. For details, see String functions.

The new Array object in the data-binding context provides functions for manipulating arrays. For details, see Array functions.

The Math object in the data-binding context provides three new functions:

  • Math.isFinite(x)
  • Math.isInf(x)
  • Math.isNaN(x)

For details, see Math functions

New environment properties

New environment properties are available in the data-binding context:

Component properties

All components now include new properties to improve how APL works with assistive technologies:

The accessibilityLabel base component property is now dynamic, so you can change its value with the SetValue command.

Child components within a Container now support using the left, right, top, and bottom properties with relative positioning, in addition to absolute positioning. Previously, these positioning properties were ignored when position is set to relative. Now, these properties offset the child component from the component's normal position in the parent container.

For details about using these properties, see position, bottom, left, right, top.

Work with APL versions

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

A user can invoke your skill on older devices that do not 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 1.5. 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": "1.5"
            }
          }
        }
      },
      "apiEndpoint": "https://api.amazonalexa.com",
      "apiAccessToken": "eyJ..."
    },
    "Viewport": {}
  },
  "request": {}
}

Previous APL versions

Amazon Alexa
Amazon Appstore
Amazon Web Services
Amazon Dash Replenishment