Gracias por tu visita. Esta página solo está disponible en inglés.

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. All APL skills are required to support the following:

  • Hub Round (hubRoundSmall)
  • Hub Landscape (hubLandscapeMedium and hubLandscapeLarge)
  • TV Fullscreen (tvLandscapeXLarge)

For the best user experience, it is also recommended to support:

  • Hub Landscape, Small (hubLandscapeSmall)

Note that skills must support the required profiles shown above regardless of the skill locale. The set of profiles selected here is a global setting.

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, make sure that your content displays correctly on the hubRoundSmall profile.

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.

Suppose you designed your APL document to display correctly on Hub Round, Hub Landscape, and TV Fullscreen. 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 may 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

  1. In the developer console, navigate to Build > Custom > Interfaces.
  2. Make sure that the Alexa Presentation Language option is enabled.
  3. 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.
    • The Hub Round, Hub Landscape, and TV Fullscreen profiles are required.

Configure the supported viewports with the ASK CLI or SMAPI

To configure the supported viewports 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 valid viewport profile objects are shown in the examples below. Note that you must include the four required viewports.

Required viewports

Your skill must support the viewports shown in the following code block. This includes Hub Round, Hub Landscape, and TV Fullscreen. Add this block to manifest.apis.custom.interfaces, replacing any existing ALEXA_PRESENTATION_APL object:

Copied to clipboard.

{
  "type": "ALEXA_PRESENTATION_APL",
  "supportedViewports": [
    {
      "mode": "HUB",
      "shape": "ROUND",
      "minWidth": 480,
      "maxWidth": 480,
      "minHeight": 480,
      "maxHeight": 480
    },
    {
      "mode": "HUB",
      "shape": "RECTANGLE",
      "minWidth": 1024,
      "maxWidth": 1024,
      "minHeight": 600,
      "maxHeight": 600
    },
    {
      "mode": "HUB",
      "shape": "RECTANGLE",
      "minWidth": 1280,
      "maxWidth": 1280,
      "minHeight": 800,
      "maxHeight": 800
    },
    {
      "mode": "TV",
      "shape": "RECTANGLE",
      "minWidth": 960,
      "maxWidth": 960,
      "minHeight": 540,
      "maxHeight": 540
    }
  ]
}

Optional viewports (Hub Landscape, Small)

You can also choose to support the Hub Landscape, Small profile. Add the code block for the profile to support to the supportedViewports array:

Copied to clipboard.

{
  "mode": "HUB",
  "shape": "RECTANGLE",
  "minWidth": 960,
  "maxWidth": 960,
  "minHeight": 480,
  "maxHeight": 480
}

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 Small Hub - Landscape. 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.