Viewport Profiles


The Alexa viewport profiles package provides a collection of viewport profiles you can use in conditional logic. Using viewport profiles rather than low-level viewport characteristics is a key technique in building responsive APL documents.

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.

Import the Alexa viewport profiles package

To use the resources in the Alexa viewport profiles package, add the alexa-viewport-profiles package to the import array in your document. The latest version of the alexa-viewport-profiles package is 1.6.0.

For example:

{
  "import": [
    {
      "name": "alexa-viewport-profiles",
      "version": "1.6.0"
    }
  ]
}

Use viewport information in conditional logic

The viewport profiles package provides named resources for profiles, as well as the viewport characteristics that are combined into the profile. Use these resources instead of hard-coding values such as viewport size.

To use a resource from the package in your conditional logic, use the reserved character "@" in the resource name.

In the following example, this when clause evaluates to true if the user's device meets the criteria for the hubRoundSmall profile:

"when": "${@viewportProfile == @hubRoundSmall}"

In this example, the when clause evaluates to true for any rectangular viewport:

"when": "${@viewportShape == @viewportShapeRectangle}"

For more details about data-binding expressions and conditional logic in APL documents, see Data-binding Syntax and Conditional Component Inflation. For details about how resources work in APL, see APL Resources.

Viewport profile resource (@viewportProfile)

The @viewportProfile resource classifies devices into different categories. Basing your conditional logic on these categories instead of hard-coding device characteristics makes your logic more robust as new devices become available.

he following example shows a conditional statement that evaluates to true when the user's device meets the criteria for the hubLandscapeMedium profile, such as an Echo Show.

"when": "${@viewportProfile == @hubLandscapeMedium}"

The following table describes the available viewport profiles. In this table, the width and height values are provided in dp.

Viewport profile Shape / Orientation Mode minWidth / maxWidth minHeight / maxHeight

hubRoundSmall

round / equal

hub

100 – 599

100 – 599

hubLandscapeSmall

rectangle / landscape

hub

960 – 1279

100 – 599

hubLandscapeMedium

rectangle / landscape

hub

960 – 1279

600 – 959

hubLandscapeLarge

rectangle / landscape

hub

1280 – 1920

600 – 1279

hubLandscapeXLarge

rectangle / landscape

hub

1920 – 2560

960 – 1279

hubPortraitMedium

rectangle / portrait

hub

960 – 1279

1920 – 2560

tvLandscapeXLarge

rectangle / landscape

tv

960 – 960

540 – 540

mobileSmall

rectangle / portrait

mobile

600 – 959

320 – 1920

mobileMedium

rectangle / landscape

mobile

960 – 1279

320 – 1920

mobileLarge

rectangle / landscape

mobile

1280– 1920

320 – 1920

hubWidgetMedium

rectangle

hub

134 / 425

222 / 711

Widget viewport profile sizes

For the widget viewport profiles, the size varies depending on the size of the viewport that contains the widget. For example, a device with the Hub Landscape Extra Large viewport profile displays a larger version of the Widget Medium profile than a device with the Hub Landscape Medium profile. As you build your widget, you can preview how it renders on different devices in the authoring tool.

Resources for viewport characteristics

The viewport profiles package defines additional resources for viewport characteristics such as shape, size, and density.

Shape (@viewportShape)

The @viewportShape resource distinguishes between different viewport shapes.

"when": "${@viewportShape == @viewportShapeRectangle}"
Resource Condition

viewportShapeSquare

viewport.width == viewport.height

viewportShapeRectangle

viewport.width != viewport.height

viewportShapeRound

viewport.shape == 'round'

Orientation (@viewportOrientation)

The @viewportOrientation resource distinguishes between different viewport orientations.

"when": "${@viewportOrientation == @viewportOrientationLandscape}" 
Resource Condition

viewportOrientationEqual

viewport.width == viewport.height

viewportOrientationLandscape

viewport.width > viewport.height

viewportOrientationPortrait

viewport.width < viewport.height

Size Classes

The size and size class resources distinguish between viewports of different sizes.

Viewport size grouping resources for viewport width and height in dp

Sample conditional clause:

"when": "${@viewportWidth == @viewportSizeMedium}"
"when": "${@viewportHeight == @viewportSizeSmall}"
Resource Condition (viewport.width/viewport.height) dp

viewportSizeXSmall

< 600

viewportSizeSmall

≥ 600 && <960

viewportSizeMedium

≥ 960 && <1280

viewportSizeLarge

≥ 1280 && <1920

viewportSizeXLarge

≥ 1920

Viewport size class grouping resources for combined viewport width and height (@viewportSizeClass)

The @viewportSizeClass resource combines the width and height to distinguish between different viewport sizes.

Sample conditional clause:

"when": "${@viewportSizeClass == @viewportClassMediumSmall}"
Resource width height

viewportClassXSmallXSmall

viewportSizeXSmall

viewportSizeXSmall

viewportClassSmallSmall

viewportSizeSmall

viewportSizeSmall

viewportClassSmallMedium

viewportSizeSmall

viewportSizeMedium

viewportClassMediumXSmall

viewportSizeMedium

viewportSizeXSmall

viewportClassMediumSmall

viewportSizeMedium

viewportSizeSmall

viewportClassMediumMedium

viewportSizeMedium

viewportSizeMedium

viewportClassMediumLarge

viewportSizeMedium

viewportSizeLarge

viewportClassMediumXLarge

viewportSizeMedium

viewportSizeXLarge

viewportClassLargeSmall

viewportSizeLarge

viewportSizeSmall

viewportClassLargeMedium

viewportSizeLarge

viewportSizeMedium

viewportClassLargeLarge

viewportSizeLarge

viewportSizeLarge

viewportClassLargeXLarge

viewportSizeLarge

viewportSizeXLarge

viewportClassXLargeMedium

viewportSizeXLarge

viewportSizeMedium

viewportClassXLargeLarge

viewportSizeXLarge

viewportSizeLarge

viewportClassXLargeXLarge

viewportSizeXLarge

viewportSizeXLarge

Density (@viewportDensity)

The @viewportDensity resource distinguishes between different densities in dpi.

Sample conditional clause:

"when": "${@viewportDensity == @viewportDensityNormal}"
Resource Condition (viewport.dpi)

viewportDensityXLow

< 140

viewportDensityLow

≥ 140 && < 200

viewportDensityNormal

≥ 200 && < 280

viewportDensityHigh

≥ 280 && < 400

viewportDensityXHigh

≥ 400 && < 560

viewportDensityXXHigh

≥ 560 && < 720

Viewport profiles example

The following example displays information about the viewport from the viewport object in the data-binding context. The example then uses several when statements to display additional details when they are true for the profile. For example, change the viewport profile to "Hub Landscape Medium" to see all of the additional details.



Was this page helpful?

Last updated: Nov 28, 2023