Alexa.Display.Window (v1.0)

The Alexa.Display.Window interface enables device makers to describe their visual display to the Alexa Voice Service (AVS). This communication enables any number of 'visual response' directives so that the device can respond appropriately. Alexa.Display.Window describes the potential windows that can be created for a display. A display can contain multiple windows. These characteristics will be published by the Device Capabilities Framework (DCF) to the device.

To learn more about the Alexa.Display interface, see Display (v1.0)

To learn more about APL, its interfaces, and how to use those interfaces together, see Alexa Presentation Language (APL) Overview.

Capability Assertion

Alexa.Display.Window 1.0 may be implemented by the device on its own behalf, but not on behalf of any connected endpoints.

New AVS integrations must assert support through Alexa.Discovery, but Alexa will continue to support existing integrations using the Capabilities API.

Sample Declaration

{
    "type": "AlexaInterface",
    "interface": "Alexa.Display.Window",
    "version": "1.0"
}

Object Syntax

The following code snippet shows the parameters, valid values, and types for the Alexa.Display.Window interface:


{
  "type": "AlexaInterface",
  "interface": "Alexa.Display.Window",
  "version": "1.0",
  "configurations": {
    "templates": [
      {
        // Standard Continuous window resize example
        "id": "STRING",
        "type": "STANDARD",
        "configurations": {
          "sizes": [
            {
              "id": "{STRING}",
              "type": "CONTINUOUS",
              "minimum": {
                "unit": "PIXEL",
                "value": {
                  "width": "{INTEGER}",
                  "height": "{INTEGER}"
                }
              },
              "maximum": {
                "unit": "PIXEL",
                "value": {
                  "width": "{INTEGER}",
                  "height": "{INTEGER}"
                }
              }
            }
          ],
          "interactionModes": [
            "{STRING}",
            "..."
          ]
        }
      },
      {
        // Overlay Discrete window size example
        "id": "{STRING}",
        "type": "OVERLAY",
        "configuration": {
          "sizes": [
            {
              "id": "{STRING}",
              "type": "DISCRETE",
              "value": {
                "unit": "PIXEL",
                "value": {
                  "width": "{INTEGER}",
                  "height": "{INTEGER}"
                }
              }
            }
          ],
          "interactionModes": [
            "{STRING}",
            "..."
          ]
        }
      }
    ]
  }
}

Configuration Parameters

This section discusses the parameter information separately for continuously resized and discreet sized windows for the Alexa.Display.Window interface.

Alexa.Display.Window parameters

The parameters in the following table are shared across all Alexa.Display.Window configurations:

Field Type Required Description
templates Array of WindowTemplate objects Yes Collection of window templates supported by the device. Windows are displayed within targeted displays.

Window Template

The parameters in the following table are shared across all Window Template objects:

Field Type Required Description
id String Yes Developer-derived unique identifier for the window template.
type String Yes

Type of window. Valid values are "STANDARD" and "OVERLAY".

  • STANDARD: Permanent, static window.
  • OVERLAY: Temporary window that can share the screen with other experiences. Overlay windows may be transparent.
configuration Window Template Configuration object Yes Supported typed configuration changes by the window template.

Window Template Configuration

The parameters in the following table are shared across all Window Template configurations:

Field Type Required Description
sizes Array of Window Template Size Configuration objects Yes Collection of size objects describing the valid ranges of window sizes. These values must be consistent with the size expressed in Alexa.Display resolution values. If the device supports different rotations, express separate discrete sizes that properly represent the height and width of those rotations.
interactionModes Array of Strings Yes A collection of one or more "id" values representing interaction modes the window template supports. All values within this collection must be expressed as "id" string values within the Alexa.InteractionMode interface.

Window Template Size Configuration

The parameters in the following table are shared across all Window Template size configurations:

Field Type Required Description
id String Yes Unique identifier for the specified size configuration.
type String Yes The range type of resizing. Accepted values are “DISCRETE” and “CONTINUOUS”. Specify DISCRETE for a window size with fixed points. Specify CONTINUOUS to allow any window size below a specified maximum width and height.

Discrete Window Template Size Configuration

The parameters in the following table are shared across all Discreet Window Template configurations:

Field Type Required Description
value Resolution Value object representing discrete window Yes The fixed size of the window.

Continuous Window Template Size Configuration

The parameters in the following table are shared across all Continuous Window Template configurations:

Field Type Required Description
minimum Resolution Value object representing minimum range of continous window Yes The minimum size of the window.
maximum Resolution Value object representing minimum range of continous window Yes The maximum size of the window.

Resolution Value

The parameters in the following table are shared across all Resolution Value objects:

Field Type Required Description
unit String Yes The unit of measurement used to define the resolution of the display. Accepted value is "PIXEL".
width Integer Yes Width of the display in pixels.
height Integer Yes Height of the display in pixels.

WindowState Event

Devices use the the WindowState event to currently available windows to Alexa. A device then receives APL directives targeted for one of the reported active windows.

Sample WindowState Event message

The following sample code shows the structure for a WindowState event message:

{
    "context": [
        {
           "header": {
                "namespace": "Alexa.Display.Window",
                "name": "WindowState"
            },
            "payload": {
                  "defaultWindowId": "{STRING}",
                  "instances" : [
                        {
                          "id": "{STRING}",
                          "templateId": "{STRING}",
                          "token": "{STRING}",
                          "configuration": {
                             "interactionMode": "{STRING}",
                             "sizeConfigurationId": "{STRING}"
                          }
                        },

                        ...
                  ]          
            }
        }
    ],
    "event": {
    ..
}

WindowState payload parameters

The following table lists the payload parameters for the WindowState event:

Field Type Required Description
defaultWindowId string Yes Indicates which window is the default target for this device. Informs how experiences will behave when they do not explicitly target a window.
instances array of Window Instance objects Yes List of all available window instances. Devices must always report at least one window instance.

Window Instance parameters

The following table lists the parameters for a Window Instance object:

Field Type Required Description
id string Yes A unique identifier for the window instance that is used to target content to this window.
templateId string Yes Identifies the window template in the Alexa.Display.Window capability which is the basis for this instance.
token string No Token identifying the content currently occupying the window, such as the presentationToken of an APL RenderDocument that targeted the window.
configuration Window Instance Configuration object Yes The current configuration of the window.

Window Instance Configuration Parameters

The following table lists the parameters for a Window Instance Configuration object:

Field Type Required Description
interactionMode string Yes Id value representing the current interaction mode of the window.
sizeConfigurationId object Yes Indicates the active size configuration of the window.