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

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 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.

Last updated: Feb 03, 2023