What's New in APL 1.8

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

Viewport profiles package

New viewport profiles

The alexa-viewport-profiles package includes the following two new profiles to support the Echo Show 15:

Hub Landscape Extra Large (@hubLandscapeXLarge)
Hub Portrait Medium (@hubPortraitMedium)

Use these profiles when building your conditional logic to make sure that your content looks good on all Alexa devices. Select these new profiles in the authoring tool and simulator to preview your content on this device.

The following table summarizes the two new profiles.

Viewport profile	Shape / Orientation	Mode	minWidth / maxWidth	minHeight / maxHeight
`hubLandscapeXLarge`	rectangle / landscape	hub	1920 – 2560	960 – 1279
`hubPortraitMedium`	rectangle / portrait	hub	960 – 1279	1920 – 2560

For more about the viewport profiles available in alexa-viewport-profiles, see Viewport Profiles.

For details about how to preview your content with different viewports in the authoring tool, see Preview an APL Document.

For details about how to test your skill with different viewports in the simulator, see Test APL Skills in the Developer Console Simulator.

The responsive components and templates in the alexa-layouts package support the two new viewport profiles. For details about how to use the responsive components and templates, see Responsive Components and Templates.

After you have updated your skill to support the new viewport profiles, update the list of profiles that your skill supports. You can make this update on the Interfaces page in the developer console or using the ASK CLI. For details, see Select the Viewport Profiles Your Skill Supports.

Other updates to the viewport profiles package

The @viewportSizeClass resource in the package now includes an additional possible value: @viewportClassMediumXLarge. For more about resources about how to determine the viewport size, see Size Classes.

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.

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.

Improved image and video handling

The Image, VectorGraphic, and Video components now include handlers that run when the items load or fail to load. For example, if an image fails to load because the URL is invalid, the component invokes the new onFail handler. Configure these handlers with commands to handle this situation. For example, if an image fails to load, you might run SetValue to change source to a different placeholder image.

See the following new handlers:

Image component: onLoad and onFail.
VectorGraphic component: onLoad and onFail.
Video component: onTrackReady and onTrackFail.

Override environment defaults

The environment object in the data-binding context contains runtime information about the operating APL environment. You can now override certain properties to change document-level defaults.

To override these defaults, you set properties in the document-level environment object. You can override the following two properties:

lang – The default language (BCP-47 format) used for text display.
layoutDirection – The default component and text layout direction for the document`

This change simplifies supporting right-to-left languages such as Arabic, as well as supporting language-specific fonts. Previously, you had to use the component-level layoutDirection and lang properties, which meant that you might need to set these values on multiple components in your document. Now, you can set these values one time, at the document level, and they apply throughout your layout. You can also use these document defaults when building resources for use in your document.

Use data-binding to set the environment.layoutDirection and environment.lang properties to values in your data source. When your skill constructs the data source to send with the RenderDocument directive, set these properties in the data source based on the locale provided in the request. This method lets you use the same APL document for both left-to-right and right-to-left content.

For details about how you set the document-level environment property, see the document environment property.

For an example that shows using the document-level environment property with responsive components and templates, see Support for Right-to-left Languages in the Responsive Components and Templates.

General updates

Data-binding context

The environment property in the data-binding context now gives you access to the document-level layoutDirection and lang properties. Access the current document-level settings for these properties with ${environment.layoutDirection} and ${environment.lang}. These properties can be useful when building language-appropriate resources. For details, see the environment object in the data-binding context.
New displayState property in the initial data-binding context to report whether the document is hidden, in the foreground, or in the background. For details, see displayState.

Document properties

New environment property at the document level. Use this property to override environment settings. You can override layoutDirection and lang properties. For details, see the document environment property.
New onDisplayStateChange handler to define commands that run when the document displayState changes. For details, see the onDisplayStateChange property.

Component properties

Image
- onFail
- onLoad
VectorGraphic
- onFail.
- onLoad
Video
- onTrackFail
- onTrackReady

Work with APL versions

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

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