Viewport Profiles (1.2.0)

---

(This is not the most recent version of the alexa-viewport-profiles package. Use the Other Versions option to see the documentation for the most recent version of the alexa-viewport-profiles package)

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
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

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": "${@viewport.width == @viewportSizeMedium}"

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 == @viewportClassMediumLarge}"

Resource	width	height
viewportClassXSmallXSmall	viewportSizeXSmall	viewportSizeXSmall
viewportClassSmallSmall	viewportSizeSmall	viewportSizeSmall
viewportClassSmallMedium	viewportSizeSmall	viewportSizeMedium
viewportClassMediumXSmall	viewportSizeMedium	viewportSizeXSmall
viewportClassMediumSmall	viewportSizeMedium	viewportSizeSmall
viewportClassMediumMedium	viewportSizeMedium	viewportSizeMedium
viewportClassMediumLarge	viewportSizeMedium	viewportSizeLarge
viewportClassLargeSmall	viewportSizeLarge	viewportSizeSmall
viewportClassLargeMedium	viewportSizeLarge	viewportSizeMedium
viewportClassLargeLarge	viewportSizeLarge	viewportSizeLarge
viewportClassLargeXLarge	viewportSizeLarge	viewportSizeXLarge
viewportClassXLargeLarge	viewportSizeXLarge	viewportSizeLarge
viewportClassXLargeXLarge	viewportSizeXLarge	viewportSizeXLarge

Density (@viewportDensity)

The @viewportDensity resource distinguishes between different densities in dpi.

Sample conditional clause:

"when": "${@viewportDensity == @viewportDensityHigh}"

Resource	Condition (viewport.dpi)
viewportDensityXLow	< 140
viewportDensityLow	≥ 140 && < 200
viewportDensityNormal	≥ 200 && < 280
viewportDensityHigh	≥ 280 && < 400
viewportDensityXHigh	≥ 400 && < 560
viewportDensityXXHigh	≥ 560 && < 720

Related topics

• Select the Viewport Profiles Your Skill Supports
• Build Responsive APL Documents

---

---

Last updated: Nov 28, 2023