What's New in APL 1.7

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

APL for audio is generally available

General availability for APL for audio comes with support for APL for audio in reprompts and high quality audio playback on supported devices.

Use APL for audio in reprompts

Your skill can include a reprompt in your response. Alexa speaks the reprompt when the user doesn't respond within a few seconds. You can now use APL for audio for these reprompts, in addition to outputSpeech.

To send an APL for audio response as a reprompt:

Build your APL for audio document and data source.

In your response, include the reprompt object. Add the Alexa.Presentation.APLA.RenderDocument directive to the directives array.

 {
     "reprompt": {
         "outputSpeech": {
             "type": "PlainText",
             "text": "Alexa speaks this text before playing the APL for audio response."
         },
         "directives": [
             {
                 "type": "Alexa.Presentation.APLA.RenderDocument",
                 "document": {}
             }
         ]
     }
 }

Be sure to also set shouldEndSession in your response to false.
If you include outputSpeech, Alexa speaks the outputSpeech first, followed by the APL for audio response.

High fidelity audio output on supported devices

APL for audio no longer down-samples audio to 24kHz when playing it back on a device. Devices that support higher quality audio (up to 48kHz) can now play your original audio as you intended it.

As part of this update, the audio files you provide with the Audio component can have a sample rate of up to 48kHz.

For details about the audio formats you can use with APL for audio, see Audio file support.

APL responsive components and templates

APL includes updates to the responsive components and templates.

Support for right-to-left languages

APL 1.7 provides support for Arabic-language skills. You can use the updated responsive components and templates to display content in a right-to-left orientation for these skills.

The components and templates now include the layoutDirection property. Use this property to specify either a left-to-right or right-to-left orientation for the component.

Components with the layoutDirection property:

Templates with the layoutDirection property:

For more information about how the responsive components and templates support Arabic, see Support for Right-to-left Languages.

Support for language-specific fonts

Several responsive components and templates now include the lang property. Use this to specify the language for your content. When available, the device uses the corresponding language-specific fonts. For example, set lang to ar-SA to use Arabic-specific fonts.

Components with the lang property:

Templates with the lang property:

New properties on existing components and templates

Property	Description	Available on components
`accessibilityLabel`	A string describing the item. Voice over reads this string when the user selects the item.	`AlexaImageListItem` `AlexaRating`
`contentDirection`	The image and text content direction. Set to `column` or `row`.	`AlexaImageListItem`
`headerAttributionOpacity`	The opacity of the attribution text and attribution image in the header. Set to a number between 0 and 1.	The `headerAttributionOpacity` property was added to `AlexaHeader` in `alexa-layouts` 1.3.0. It is now available in the responsive templates that display `AlexaHeader`, in both 1.3.0 and 1.4.0 versions of `alexa-layouts`: `AlexaDetail` `AlexaGridList` `AlexaHeadline` `AlexaImageList` `AlexaLists` `AlexaPaginatedList` `AlexaTextList`
`imageAltText`	Alternate text for the image. Voice over reads this string.	`AlexaImageListItem`
`lang`	The language for the text displayed in the template. This language determines the default font used for the text. For example, when set to `ar-SA`, the component uses Arabic fonts when available on the device. Set to a BCP-47 string. For more about language-specific fonts for responsive components and templates, see Language-specific fonts in the components and templates.	This property has been added to responsive components and templates that display text. See Support for language-specific fonts for a list.
`layoutDirection`	Specifies the layout direction for the content. Set this property to either `LTR` (left-to-right) or `RTL` (right-to-left). For more about support for right-to-left languages in the responsive components and templates, see Support for Right-to-left Languages.	This property has been added to all of the responsive components and layouts that display content in a reading order. See Support for right-to-left languages for Arabic skills for a list.
`listId`	An identifier to assign to the `Sequence` component used for the list. Set `listId` to a value to enable voice-based scrolling with the built-in intents. Also set this parameter to an ID if you need to target the list for commands, such as the `SpeakList` command.	The `listId` parameter has been added to all of the list-templates in versions 1.2.0, 1.3.0, and 1.4.0: `AlexaGridList` `AlexaImageList` `AlexaLists` `AlexaPaginatedList` `AlexaTextList`
`speechItems`	An array of speech items. The `AlexaImageList` template assigns each item in this array to the `speech` property of the corresponding list item. Use this property when you want to use the `SpeakList` command to speak the list items. For an example of using this property with `AlexaImageList`, see Use the SpeakList command with AlexaImageList."	The `listId` parameter has been added to all of the list-templates in versions 1.2.0, 1.3.0, and 1.4.0: `AlexaGridList` `AlexaImageList` `AlexaLists` `AlexaPaginatedList` `AlexaTextList`

Import the Alexa packages into your APL document

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

Package	Version
`alexa-layouts`	1.4.0
`alexa-styles`	1.3.0
`alexa-viewport-profiles`	1.3.0

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

APL support for right-to-left languages

APL 1.7 provides support for right-to-left content to support Arabic-language skills.

New layoutDirection property

The layoutDirection property is a new base component property. Set this property to LTR or RTL to automatically determine the layout.

For example, when you set layoutDirection to RTL on a row-based Container, the Container displays the child items with the first item starting on the right.

The layoutDirection property determines the layout of the following components:

New properties and options that adjust based on layoutDirection

To support building a single document that can support both left-to-right and right-to-left experiences, APL 1.7 includes new properties and settings that automatically adjust the content based on the value of layoutDirection.

All components now include paddingStart and paddingEnd properties. These override paddingLeft and paddingRight. For details, see paddingStart, paddingEnd.
The Container component now includes start and end properties for positioning. These override the left and right properties based on layoutDirection. For details, see start, end.
The textAlign property on the Text component now accepts start and end values. Use these instead of left and right to align the text based on the layoutDirection. For details, see textAlign.
The direction property on the SwipeAway gesture now takes forward and backward values. Use these instead of left and right to set the swipe direction based on the layoutDirection. For details, see direction.

New lang property

The Text and EditText components now include a lang property to specify the language of the text. APL attempts to find a language-specific version of the fontFamily for displaying the text. For example, set lang to ar-SA to use Arabic versions of the font.

General updates

Component properties

APL 1.7 includes the following changes to component properties and values:

The position property on the Container component now accepts a sticky value. Use this property to "stick" the item to the nearest scrolling item until it's pushed off by another sticky component. For details, see Sticky positioning.
The Text component now supports a <span> tag for content provided in the text property. Use this attribute to apply inline formatting to the text. For details, see the text property of the Text component.
For a Pager component, the navigation and pageDirection properties are now dynamic. You can use the SetValue to change the value of these properties when the document is already rendered on the screen.
The following shadow-related properties are now dynamic and styled:
- shadowColor
- shadowHorizontalOffset
- shadowRadius
- shadowVerticalOffset
You can now define arrays and maps inline in data-binding expressions. For details, see Arrays and Maps.
For details about new properties related to right-to-left support, see APL support for right-to-left languages.

Work with APL versions

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

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