Select the Viewport Profiles Your Skill Supports
When you configure your skill to support the Alexa Presentation Language (Alexa.Presentation.APL), you also need to select the viewport profiles your skill supports. These options determine how different devices display your content. As you work on your skill, revisit these options and update them to reflect what your skill supports.
What is a viewport profile?
On an Alexa-enabled device with a screen, the viewport
is the area of the screen that the user can see. A viewport has a shape, orientation, size, and density. A viewport profile is a named resource that represents a range of viewport characteristics. The profile specifies values for the parts of a viewport (shape, size, and so on). Size and density are defined as ranges so that the profile can represent multiple physical devices. For example, the viewport profile hubLandscapeSmall encompasses rectangular, landscape devices where the width is between 960 and 1280 pixels, and the height is less than 600 pixels.
When you build your APL document, you can use the Alexa viewport profiles provided in the Alexa viewport profiles package in your conditional logic to make your document responsive.
How different devices display your APL content
When you configure your skill, you identify the set of viewport profiles that your skill supports. Your skill can support any combination of the following profiles:
- Hub Round Small (
hubRoundSmall) - Hub Landscape, Small (
hubLandscapeSmall) - Hub Landscape, Medium (
hubLandscapeMedium) - Hub Landscape, Large (
hubLandscapeLarge) - Hub Landscape, Extra Large (
hubLandscapeXLarge) - Hub Portrait, Medium (
hubPortraitMedium) - TV Fullscreen (
tvLandscapeXLarge) - Mobile Small (
mobileSmall) - Mobile Medium (
mobileMedium) - Mobile Large (
mobileLarge)
Supporting a viewport profile means that you tested your APL content and verified that it works with that profile. For example, to declare that your skill supports Hub Round Small, make sure that your content displays correctly on small, round hubs.
The set of viewport profiles you support determines how Alexa displays your content on different viewports:
- Supported viewports display your content as is, without any scaling.
- Unsupported viewports scale and letterbox your content to fit within the viewport.
For example, suppose you designed your APL document to display correctly on Hub Round Small, Hub Landscape Medium, and TV Landscape Extra Large. However, you did not specifically support Hub Landscape Small. A user invokes your skill on a device with this unsupported profile (such as an Echo Show 5). Alexa inflates your document according to the nearest supported profile, then scales and letterboxes the content to fit on the Echo Show 5 screen.
Select the viewport profiles to support
You can configure the set of supported viewport profiles in the developer console. Alternatively, you can add the settings to your skill manifest and then update your skill with the ASK Command Line Interface (CLI) or Skill Management API (SMAPI).
Be sure to set the supported profiles option correctly
A mismatch between the selected supported profiles and your skill's actual APL content might cause unexpected results. For example, note these scenarios:
- You update your skill to display correctly on all the different viewport profiles. However, you don't select the Hub Landscape Small option for the skill. In this case, Alexa continues to scale your content. Users never see the experience you designed for small, landscape hubs.
- You don't update your skill for Hub Landscape Small, but you do select that option for the skill. In this case, the result is undefined. Since no scaling is applied, there is no guarantee that your content will fit within the viewport.
Configure the supported viewport profiles in the developer console
- In the developer console, navigate to Build > Custom > Interfaces.
- Make sure that the Alexa Presentation Language option is enabled.
- Select the check boxes for the viewport profiles you support.
- If a profile is selected, your content is displayed on that type of viewport with no scaling.
- If a profile is not selected, your content is scaled and letterboxed to fit on the related viewports.
Configure the supported viewports with the ASK CLI or SMAPI
To configure the supported viewport profiles with the ASK CLI or SMAPI, update the skill manifest, then deploy the manifest.
To indicate APL support in your skill manifest, you need an ALEXA_PRESENTATION_APL object in the interfaces array (manifest.apis.custom.interfaces). Within this object, add a supportedViewports property with an array that contains an object for each viewport profile you support.
The following table shows the object to put in the supportedViewports array to support each available viewport profile.
| Viewport profile | Object |
|---|---|
|
Hub Round Small |
|
|
Hub Landscape Small |
|
|
Hub Landscape Medium |
|
|
Hub Landscape Large |
|
|
Hub Landscape Extra Large |
|
|
Hub Portrait Medium |
|
|
TV Landscape Extra Large |
|
|
Mobile Small |
|
|
Mobile Medium |
|
|
Mobile Large |
|
For example, the following ALEXA_PRESENTATION_APL object configures support for Hub Round Small, Hub Landscape Medium, Hub Landscape Large, and TV Landscape Extra Large.
{
"type": "ALEXA_PRESENTATION_APL",
"supportedViewports": [
{
"mode": "HUB",
"shape": "ROUND",
"minWidth": 100,
"maxWidth": 599,
"minHeight": 100,
"maxHeight": 599
},
{
"mode": "HUB",
"shape": "RECTANGLE",
"minHeight": 600,
"maxHeight": 959,
"minWidth": 960,
"maxWidth": 1279
},
{
"mode": "HUB",
"shape": "RECTANGLE",
"minHeight": 600,
"maxHeight": 1279,
"minWidth": 1280,
"maxWidth": 1920
},
{
"mode": "TV",
"shape": "RECTANGLE",
"minHeight": 540,
"maxHeight": 540,
"minWidth": 960,
"maxWidth": 960
}
]
}
See the following topics for more about the ASK CLI and SMAPI:
Test your skill with different viewports
As you build your skill, test the presentation on the different viewports. Ideally you should test both on the devices you explicitly support and on those you do not support.
Testing on an actual device is always best, but you can also use the authoring tool or the simulator on the Test page. These tools work differently with regard to scaling and supported profiles:
- The authoring tool never does any scaling, regardless of the viewport profiles your skill supports.
-
The simulator on the Test page does do the same scaling as a device, depending on the viewport profiles your skill supports.
For example, in the simulator you can select to test with Hub Landscape Small. If you selected to support the Hub Landscape Small profile, you see your content as is. If you did not select to support this profile, you see the scaled version.
Related topics
Last updated: Jan 26, 2024