Viewport Profiles (1.1.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 this 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}"

See Data-binding Syntax and Conditional Component Inflation for more about data-binding expressions and conditional logic in APL documents.

Profiles

These resources provide complete viewport profiles.

Resource Options
viewportProfile One of:
  • hubRoundSmall
  • hubLandscapeSmall
  • hubLandscapeMedium
  • hubLandscapeLarge
  • tvLandscapeXLarge
Resource Shape
Condition
Orientation
Condition
Size Class
Condition
Density
Condition
hubRoundSmall viewportShapeRound viewportOrientationEqual viewportClassSmallSmall viewportDensityLow
hubLandscapeSmall viewportShapeRectangle viewportOrientationLandscape viewportClassMediumXSmall viewportDensityNormal
hubLandscapeMedium viewportShapeRectangle viewportOrientationLandscape viewportClassMediumSmall viewportDensityNormal
hubLandscapeLarge viewportShapeRectangle viewportOrientationLandscape viewportClassLargeSmall viewportDensityNormal
tvLandscapeXLarge viewportShapeRectangle viewportOrientationLandscape viewportClassXLargeLarge viewportDensityHigh
 

Shape

The shape resource definitions can be used to distinguish between different viewport shapes.

"when": "${@viewportShape == @viewportShapeRectangle}"
Resource Options
viewportShape One of:
  • viewportShapeSquare
  • viewportShapeRectangle
  • viewportShapeRound
Resource Condition
viewportShapeSquare viewport.width == viewport.height
viewportShapeRectangle viewport.width != viewport.height
viewportShapeRound viewport.shape == 'round'

Orientation

The viewport orientation resource values can be used to distinguish viewport orientation.

"when": "${@viewportOrientation == @viewportOrientationLandscape}" 
Resource Options
viewportOrientation One of:
  • viewportOrientationEqual
  • viewportOrientationLandscape
  • viewportOrientationPortrait
Resource Condition
viewportOrientationEqual viewport.width == viewport.height
viewportOrientationLandscape viewport.width > viewport.height
viewportOrientationPortrait viewport.width < viewport.height

Size Classes

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

Sample conditional clause:

"when": "${@viewportSizeClass == @viewportClassMediumLarge}"
Resource Options
viewportSizeClass One of:
  • viewportClassSmallSmall
  • viewportClassSmallMedium
  • viewportClassMediumXSmall
  • viewportClassMediumSmall
  • viewportClassMediumMedium
  • viewportClassMediumLarge
  • viewportClassLargeSmall
  • viewportClassLargeMedium
  • viewportClassLargeLarge
  • viewportClassXLargeLarge
  • viewportClassXLargeXLarge
Resource width height
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

Viewport density (DPI) grouping resources

Sample conditional clause:

"when": "${@viewportDensity == @viewportDensityHigh}"
Resource Options
viewportDensity One of:
  • viewportDensityXLow
  • viewportDensityLow
  • viewportDensityNormal
  • viewportDensityHigh
  • viewportDensityXHigh
  • viewportDensityXXHigh
Resource Condition (viewport.dpi)
viewportDensityXLow < 140
viewportDensityLow ≥ 140 && < 200
viewportDensityNormal ≥ 200 && < 280
viewportDensityHigh ≥ 280 && < 400
viewportDensityXHigh ≥ 400 && < 560
viewportDensityXXHigh ≥ 560 && < 720

Was this page helpful?

Last updated: Nov 28, 2023