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 Voice Service (AVS).
- Q: Tablets support multi-touch gestures. What value should I specify for
touch
? - Specify a value of
SINGLE
for thetouch
field. This field indicates that the device supports single input mode, not thatSINGLE
touch is the only mode. - Q: As a Skill developer designing landscape and portrait experiences for tablets, how do I determine the window orientation?
- Unlike Android and other host systems, the
Alexa.Window
API doesn't offer explicit constants for orientation because orientation isn't universal 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? - Instead of using
Alexa.Display
, represent multiple displays by expressing them as composite endpoints. - Q: How would I target a display by name?
- Use endpoints, which include endpoint name in their definitions, to target a display by name.
- Q: I want to render something to a screen; how do I choose appropriate default values?
- For most uses cases, set the
preferredUsage
field toPRIMARY
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 thepreferredUsage
field toSTANDARD
, if available. For shorter interactions that present a small amount of data, presenting small amounts of data, set thepreferredUsage
field toOVERLAY
, if available. You can also use anOVERLAY
window to display content on a transparent or semi-transparent background. - Q: Which window maps to a single viewport?
- Use a value of
PRIMARY
forpreferredUsage
for a single viewport. - Q: How can I support multi-touch gestures?
- Although APL doesn't support multi-touch gesture expressions, you can add these gestures by creating an extension to the
touch
enumeration inAlexa.Display
with interfaces defining types, classes, and fidelity your gestures as needed. For example, to create a pinch-zoom gesture, create an extension totouch
indicatingMULTITOUCH
and an additional interface ofAlexa.Display.Gestures
indicatingPINCHZOOM
as a supported property. - Q: How can I force landscape window orientation from my Skill?
- The published window and display capabilities describe valid window properties, which convert to viewport properties to describe how the window could 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's the initial size, configuration, and runtime status for a window?
- Building an adaptable UI with APL doesn't require an initial size, configuration, or runtime status. Starting conditions vary depending on the interaction model for a device.
- Q: How can I tell what the lifetime of a window is?
- 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 a user might exit a window at any time, you can just process that the user has exited the window. - Q: Do the APL APIs require certain keyboards?
- The APL APIs don't have specific requirements for keyboard support. However, you must indicate that you support keyboards in your call to AVS.
- Q: How are arc minutes calculated for the API?
- Calculate arc minutes using the interaction mode
interactionDistance
field in combination with the physical size of the display. - Q: Why are width and height required for circular or round displays?
- Because the
CIRCLE
orROUND
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 do the APL APIs support?
- Devices, not APIs, determine video player support.
- Q: How do I set a timeout for a window?
- 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.
- Create an extension to
Last updated: Oct 28, 2020