Alexa Presentation Language (APL) Frequently Asked Questions (FAQs)

The Alexa Presentation Language (APL) is a set of APIs that enable you to publish static characteristics for a device viewport to the Alexa cloud.

Q: Tablets support multitouch gestures. What value should I specify for touch?

A: Specify a value of SINGLE for the touch field. This field indicates that the device supports single input mode, not that that SINGLE touch is the only mode. At a later point, multitouch gestures may be added to Alexa.

Q: As a Skill developer designing landscape and portrait experiences for tablets, how do I determine my window orientation?

A: Unlike Android and other host systems, the Alexa.Window API does not offer explicit constants for orientation because orientation is not a universal concept across all devices, such as stationary TV sets. If your design requires orientation logic, compare the width and height of the window in your presentation to account for other conditions, such as dynamic window resizing, which can set height greater than width or vice versa.

Q: How can I represent multiple displays under the Alexa.Display interface?

A: Instead of using Alexa.Display, represent multiple displays by expressing them as composite endpoints.

Q: How would I target a display by name?

A: Use endpoints, which include endpoint name in their definitions, to target a display by name.

Q: I just want to render something to a screen; how do I choose my default values?

A: For most uses cases, set the preferredUsage field to PRIMARY if you are unsure about how to present your content. However, if your content is highly interactive or intended to be the main focus of the device user, set the preferredUsage field to STANDARD, if available. For shorter interactions that present a small amount of data, presenting small amounts of data, set the preferredUsage field to OVERLAY, if available. You can also use an OVERLAY window to display content on a transparent or semi-transparent background.

Q: Which window maps to a single viewport?

A: Use a value of PRIMARY for preferredUsage for a single viewport.

Q: How can I support multitouch gestures?

A: While APL does not currently support multitouch gesture expressions, you can add these gestures by creating an extension to the touch enumeration in Alexa.Display with interfaces defining types, classes, and fidelity your gestures as needed. For example, to create a pinch-zoom gesture, create an extension to touch indicating MULTITOUCH and an additional interface of Alexa.Display.Gestures indicating PINCHZOOM as a supported property.

Q: How can I force landscape window orientation from my Skill?

A: The published window and display capabilities describe valid window properties, which are translated to Viewport properties to describe how the window may change. To force a window to landscape, augment an existing directive or create a new directive. For example, you can augment the APL runtime to assert a particular orientation, or you could send a system-level directive, translating to the host system to force landscape for the entire device.

Q: What is the initial size, configuration, and runtime status for a window?

A: The initial size, configuration, and runtime status are not required to build an adaptable UI using APL. Starting conditions can vary depending on the interaction model for a device.

Q: How can I tell what the lifetime of a window will be?

A: Individual device policy determine the lifetime of a window. You can model Window lifetime either through timeout or lifetime policies either explicitly through the Alexa.InteractionMode interface or through association, similar to video properties. Because an end user may exit a window at any time, you only need to process that a window has been exited.

Q: Which keyboards are supported by the APL APIs?

A: Currently, the APL APIs do not have specific requirements for keyboard support. However, you do need to indicate that you support keyboards in your call to Alexa.

Q: How are arc minutes calculated for the API?

A: Calculate arc minutes using the interaction mode's interactionDistance field in combination with the physical size of the display.

Q: Why are width and height required for circular or round displays?

A: Because the CIRCLE or ROUND expressions act as masks on top of a square display, Alexa still requires values for the width and height (both physical and pixel) of the square display.

Q: What video players on a device are supported by the APL APIs?

A: Video player support is determined at the device level, not the API level.

Q: How can I set a timeout for my window?

A: Use any of the following approaches to set a timeout for a window: * Create an extension to the Alexa.InteractionModel interface. * Use a supplementary API that expresses the timeout via rendering directives with Alexa.Display.Window.Timeout. * Create an additional configuration property within the Alexa.Display.Window templates.