Ti ringraziamo per la visita. Questa pagina è per il momento disponibile solo in inglese.

APL Viewport Characteristics in the Skill Lambda

A skill request includes viewport characteristics when a skill lambda or skill service is invoked by Alexa and the Alexa-enabled device supports APL. When these characteristics are available in the skill lambda, a skill can generate customized responses, including text-to-speech (TTS) responses, that depend upon a device's visual characteristics. For more information, see Viewport property.

This sample skill request shows the viewport characteristics available to the skill lambda in the Viewport objects.

{
    "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 and can be used by skill developers to optimize their skill behavior for a specific experience. 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. Skill developers can use the video properties to determine what types of video resources to send in an APL response. For example, a skill's APL response could return video resources with different encodings depending on the video codec level that a device supports.

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.