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

APL Viewport Characteristics in the Skill Lambda

The request sent to a skill service includes viewport characteristics when the device supports APL. You can use this information in your skill code to create a customized response that depends upon a device's visual characteristics. For more information, see Viewport property.

Viewport object in the request

The viewport details are available in the context.Viewport object in the skill request:

{
    "version": "1.0",
    "session": { 
        ...
    },
    "context": {
        "AudioPlayer": {
            "playerActivity": "IDLE"
        },
        "Display": {
            "token": "listToken"
        },
        "Viewport": {
           "experiences": [
               {
                   "canRotate": true,
                   "canResize": true
               },
               {
                   "canRotate": false,
                   "canResize": false
               }
           ],
           "shape": "RECTANGLE",
           "pixelWidth": 1024,
           "pixelHeight": 600,
           "dpi": 160,
           "currentPixelWidth": 640,
           "currentPixelHeight": 500,
           "touch": [ "SINGLE" ],
           "keyboard": [ "DIRECTION" ],
           "video": {
              "codecs": ["H_264_42", "H_264_41"]
           }
        },
        "System": {
            ...
        }
    },
    "request": {
        ...
    }
}

Properties

The following properties are defined in the Viewport object.

Property Type/Values Description
experiences Array of experience objects Different modes in which the customer is expected to interact with the viewport.
shape ROUND or RECTANGLE Shape of the viewport.
pixelHeight Integer Height of the viewport in pixels.
pixelWidth Integer Width of the viewport in pixels.
currentPixelWidth Integer Width of the viewport in pixels that is currently in use.
currentPixelHeight Integer Height of the viewport in pixels that is currently in use.
dpi Integer Pixel density of the viewport.
touch Array of strings Touch events that the viewport supports.
keyboard Array of strings Input mechanisms for interacting with the viewport.
video Object Specification of which technologies are available for playing video on a device

Experiences

The experiences property contains a list of experience types supported by the device. The experience types depend on the modes supported by a viewport. You can use this information to optimize your skill's behavior for a specific experience. For example, a tablet device might have two different experiences: one for when it is docked and the other for when the customer is holding it. In these cases the skill's visual response should be optimized for both experiences, as the device owner can arbitrarily switch between the experiences.

experience properties

Property Type/Values Description
canRotate Boolean Whether the viewport can be rotated through 90, 180, and 270 degrees.
canResize Boolean Whether the viewport can be resized.

Pixel height and width

The pixelHeight and pixelWidth properties represent the number of pixels present in the viewport at its maximum height and width. These values assume a static device orientation, and express the entire viewport size regardless of whether areas of the viewport are currently in use by other applications.

Current pixel width and height

The currentPixelWidth and currentPixelHeight properties represent the number of horizontal and vertical pixels that are available for Alexa to render an experience. These values also assume a static device orientation.

Shape

The shape of the screen is set to either ROUND or RECTANGLE.

dpi

The display-independent pixel (dp) measurement of a screen is an artificial value that represents the visual size of the screen assuming that the screen is held at a mobile-phone viewing distance and has a pixel density of approximately 160 pixels per inch. Two screens viewed at the same distance with the same physical size have approximately the same dp dimensions regardless of the actual pixel density of the screen.

The dots-per-inch (dpi) of a viewport is an artificial value that reflects the visual size of a point or pixel relative to the observer, and it does not match the actual pixels-per-inch size of the screen. The formula for dpi is:

dpi = 160 * (pixelSize / dpSize)

For simplicity, dpi values are simplified to fall into consistent buckets of 120, 160, 240, 320, and so forth.

Touch

The touch property represents what kind of touch inputs the device supports. The touch array can contain the following values:

  • SINGLE - indicates that the device supports single-touch inputs

Keyboard

The keyboard property represents physical button input mechanisms that can be used to interact with the viewport. The keyboard array can contain the following values:

  • DIRECTION - there are inputs for the up/down/left/right directions as well as a button to select whatever is at the current location

Video

The video property details which technologies are available for playing video on a device. Use the video properties to determine what types of video resources to send in an APL response. For example, your skill's APL response could return video resources with different encodings depending on the video codec level that a device supports.

Note that some devices with screens do not support video playback. In this case, the video property is not present. If your skill includes video, be sure to check for this property and provide an appropriate experience for devices that do not support video. If you send a Video to a device that does not support video, the component remains on the screen, but displays no content so users will see a blank area on the screen.

video properties

Property Type/Values Description
codecs Array of Strings

The video codecs that the output device supports. Supported values:

  • H_264_41: H.264 at a maximum resolution of 1080p @ 30fps (codec level 4.1) and supporting the main- and high-capability profiles (MP and HP).
  • H_264_42: H.264 at a maximum resolution of 1080p @ 60fps (codec level 4.2) and supporting the main- and high-capability profiles (MP and HP).

H_264_41 is a subset of H_264_42. All skill requests that specify H_264_42 will also specify H_264_41. All video-capable devices support the MPEG-4 Part-14 container (MP4), along with AAC and MP3 audio codecs.

Access the viewport information in your code

The Alexa Skills Kit SDKs include helper functions for getting viewport information from the skill request. The getViewportProfile method checks multiple criteria within context.Viewport to return a value that corresponds to the viewport profiles available in the viewport profiles package:

  • HUB-ROUND-SMALL
  • HUB-LANDSCAPE-SMALL
  • HUB-LANDSCAPE-MEDIUM
  • HUB-LANDSCAPE-LARGE
  • TV-LANDSCAPE-XLARGE
  • UNKNOWN-VIEWPORT-PROFILE

Copied to clipboard.

This sample code uses the Alexa Skills Kit SDK for Node.js (v2). For a complete working sample that includes this code, see: APL Pager Karaoke sample.

In a handler, access getViewportProfile like this:

const Alexa = require('ask-sdk-core');

//...Other code. 

const viewportProfile = Alexa.getViewportProfile(handlerInput.requestEnvelope);

// returns a ViewportProfile such as HUB_LANDSCAPE_LARGE.

Copied to clipboard.

This sample code uses the Alexa Skills Kit SDK for Python. For a complete working sample that includes this code, see: APL Pager Karaoke sample.

In a handler, access get_viewport_profile like this:

from ask_sdk_core.utils import viewport

# other code...

viewport.get_viewport_profile 

# Returns a ViewportProfile such as viewport.ViewportProfile.HUB_LANDSCAPE_MEDIUM

Copied to clipboard.

This sample code uses the Alexa Skills Kit SDK for Java. For a complete working sample that includes this code, see: APL Pager Karaoke sample.

Use the ViewportUtils static class to get viewport information. The following code returns value from the ViewportProfile enumeration.

ViewportProfile viewportProfile = ViewportUtils
    .getViewportProfile(input.getRequestEnvelope());