What's New in APL 1.4

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

APL for Audio (beta)

APL for Audio introduces a new APL document format for building audio responses. You can define APL documents that mix speech and sound effects. APL for Audio uses the same framework as APL with support for data sources, data-binding, and a set of components to build out your audio.

You can use APL for Audio on all Alexa devices, including devices that don't have screens. To use your audio in a skill response, you return the RenderDocument with the APLA for Audio document to play your audio.

For a full reference to the APL for Audio document format, see APL for Audio Reference.

You can also integrate APL for Audio with a visual APL document. Use APL for Audio to play audio with the SpeakItem or SpeakList APL commands. For example, read a weather forecast when the user taps a button on the screen.

To integrate an APL for Audio document with a visual APL document, use the new aplAudioToSpeech transformer. You can preview this integration in the authoring tool with preview mode. For details, see Test the APL for Audio transformer.

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 and templates

For details about the new responsive components, see:

For details about the new responsive templates, see:

Updated responsive components and templates

APL 1.4 adds new properties to existing responsive components and templates.

The AlexaTextListItem component now has the following new properties:

  • emptyRatingGraphic
  • entities
  • fullRatingGraphic
  • halfRatingGraphic
  • hideHorizontalMargin
  • imageThumbnailSource
  • ratingGraphicType
  • ratingNumber
  • ratingSlotMode
  • ratingText
  • secondaryText
  • secondaryTextPosition
  • singleRatingGraphic
  • singleRatingGraphicWidth
  • tertiaryText
  • tertiaryTextPosition
  • touchForward

When you include these new properties in the objects passed to the listItems property for AlexaTextList, the text list displays the additional information.

The AlexaImageListItem component now has the following new properties:

  • emptyRatingGraphic
  • entities
  • fullRatingGraphic
  • halfRatingGraphic
  • hasPlayIcon
  • ratingGraphicType
  • ratingNumber
  • ratingSlotMode
  • ratingText
  • singleRatingGraphic
  • singleRatingGraphicWidth

When you include these new properties in the objects passed to the listItems property for AlexaImageList, the image list displays the additional information.

The AlexaTransportControls component now has the following new properties:

  • entities
  • primaryControlPauseAction
  • primaryControlPlayAction
  • secondaryControls
  • secondaryControlsAVGLeft
  • secondaryControlsAVGRight
  • secondaryControlsLeftAction
  • secondaryControlsRightAction
  • theme

New entities property on all components and templates

All responsive components and templates now include an entities property. This property provides access to the base component entity / entities property.

You can pass an array of data you define to entities. When the document displays on the screen and your skill gets a request, the request includes this entity data in the context for the component.

Support for user gestures

APL now supports new user interactions and gesture. For example, users can drag a component, swipe to delete an item, and perform a long-press on the screen. You can define event handlers to catch these events and execute commands.

All touchable components support the new event handlers onDown, onMove, and onUp. The *touchable components include TouchWrapper and VectorGraphic.

The TouchWrapper component also supports a set of gesture handlers that capture additional user events, such as a long-press or a swipe.

The AlexaSlider and AlexaSliderRadial responsive components use these new handlers to create an interactive progress bar that the user can drag to scrub content or change settings.

Improvements to the Alexa Vector Graphic (AVG) format

The new AVG 1.1 format includes several enhancements:

  • You can define styles, resources, and patterns within the vector graphic.
  • More options for stroke and fill, such as gradients.
  • Vector graphics can draw text items.

For details, see Alexa Vector Graphic Format.

You can now use links to documents built in the authoring tool in the RenderDocument directive. This means you don't need to export the JSON for your APL document and copy it into your code.

A link to a document in the authoring tool has the following syntax:

  • APL – doc://alexa/apl/documents/<document-name>
  • APL for Audio – doc://alexa/apla/documents/<document-name>

For example, you can link to the document named "helloworld-by-link" with "doc://alexa/apl/documents/helloworld-by-link".

To refer to the link in RenderDocument, set the document property to an object with the type and Link properties.

{
  "directives": [
    {
      "type": "Alexa.Presentation.APL.RenderDocument",
      "token": "helloworld-by-link",
      "document": {
        "src": "doc://alexa/apl/documents/helloworld-by-link",
        "type": "Link"
      },
      "datasources": {},
      "packages": []
    }
  ]
}

There are no changes to the structure of RenderDocument. Your existing skills don't require any changes to continue to work.

For more about RenderDocument for APL, see Alexa.Presentation.APL Interface Reference.

For more about RenderDocument for APL for Audio, see Alexa.Presentation.APLA Interface Reference.

Execute commands based on time

You can now define tick event handlers. The system invokes tick handlers as time passes. For example, use a tick handler to animate filling in a progress bar.

Use the new handleTick property on all components and on the document to define your tick handlers:

For details about how tick handlers work, see Tick Event Handlers.

For details about the new handleTick property on components and documents, see the following:

For an example of a tick event handler that works with the AlexaProgressBar responsive component, see Advancing a determinate progress bar.

APL extensions and the backstack

APL now includes extensions. Extensions provide additional APL functionality, but might not be available on all devices that support APL.

For details about how extensions work and how you use an extension in your document, see Extensions.

The backstack extension lets you provide "back" navigation between your documents, similar to back navigation in HTML. For details about the backstack extension, see Backstack Extension.

New APL components

  • Use the new EditText component to display an editable text box. Users can enter text in the edit box with an on-screen keyboard. For details, see EditText.
  • Use the new GridSequence component to display a list of items in a grid with rows and columns.

APL command changes

  • New sequencer property – Commands now include the sequencer property. This gives you more control when you execute a series of commands. You can also use sequencer to force a command to run in normal mode instead of fast mode.
  • Access to more properties in event.source and event.target – You can now access more information about a component when that component is the source or target of an APL event. For example, in previous versions you would retrieve the checked state for a TouchWrapper from event.source.value. Now you can get that data from event.source.checked. The event.source.value property has been deprecated, but remains available for backward compatibility.

For details about commands, see APL Commands. For details about the specific properties reported by each component, see the topic for that component.

General updates

  • Tablet mode – Fire tablets now display APL content in Tablet mode as well as in Show mode. When a user invokes your skill in Tablet mode, the tablet displays your APL content scaled down to the hub viewport and locked to a portrait orientation.
  • New math functions – New math functions are available in the data-binding context. For details, see Math functions.
  • Easing functions data type – You use easing functions with the AnimateItem command. For details about the grammar to build easing functions, see Easing function. You can also define easing functions as resources.

Component properties

The Container component has the following changes:

  • A new "wrap" property
  • New options for the direction property

The Frame component has a new borderStrokeWidth property.

The Sequence component has a new scaling property for the Sequence child properties.

APL document properties

You can now specify these new top-level properties in your document:

Work with APL versions

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

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

Previous APL versions

Amazon Alexa
Amazon Appstore
Amazon Web Services
Amazon Dash Replenishment