What's New in APL 1.7

(This is not the most recent version of the APL change log. Use the Other Versions option to see the documentation for the most recent version of the APL change log)

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:

  1. Build your APL for audio document and data source.
  2. 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

For details about how to check the APL version, see What's New in APL.