Alexa.Display.Window 1.0

The Alexa.Display.Window interface communicates to the Alexa Voice Service (AVS) about windows potentially created on a device display.

To learn more about the Alexa.Display interface, see Alexa.Display

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

Capability assertion

A device might implement Alexa.Display.Window on its own behalf, but not on behalf of any connected endpoints.

For new AVS integrations, assert support through Alexa.Discovery. However, AVS provides support for existing integrations through the Capabilities API.

templates parameters

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

The Alexa.Display.Window interface has one configuration object: templates. The objects in the templates array have the following schema:

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

Use the following syntax for templates objects:


{
  "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}",
            "..."
          ]
        }
      }
    ]
  }
}

Window template

All Window template objects share the following parameters:

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

Window type. Valid values are STANDARD and OVERLAY.

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

Window templates

All Window templates share the following parameters:

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. Express all values within the collection as "id" string values within the Alexa.InteractionMode interface.

Window template size configuration

All Window Template size configurations share the following parameters:

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

DISCRETE Window template parameters

All Window templates with type = DISCRETE share the following parameters:

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

CONTINUOUS Window template type parameters

All Window templates with type = CONTINUOUS share the following parameters:

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

Resolution value

All Resolution Value objects share the following parameters:

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

Devices use the WindowState context object to communicate active and available windows to AVS. Devices then receive presentation directives, such as an APL directive, which target one of the reported active windows.

Sample WindowState context entry

The following sample code shows the structure for a WindowState context entry:

{
    "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 context object:

Field Type Required Description
defaultWindowId string Yes Indicates which window is the default target for the device. Informs how experiences behave if they don't 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 to target content to the window.
templateId string Yes Identifies the window template in the Alexa.Display.Window capability which is the basis for the instance.
token string No Token identifying the content 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 parameters

The following table lists the parameters each instance of a Window 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.
Was this page helpful?

Last updated: Feb 03, 2023