Alexa Smart Screen Sample Web App

The Alexa Smart Screen Sample Web App is a configurable client that you can use to showcase Alexa Voice Service(AVS) Device SDK visual capabilities, such as Alexa Presentation Language (APL) and cameras, and interact with the AVS Device SDK IPC Server Sample App through inter-process communication (IPC).

For details about building the alexa-smart-screen-web-components library, including opening the sample web application, see the Alexa Smart Screen Web Components Quick Start Guide. Make sure that you use an IPC server app, such as the AVS SDK IPC Server Sample App, to initialize the Sample Web App through the configureClient API call of the SessionSetupHandler. This API provides the Sample Web App with the required configuration payload.

For details about configuring the Sample Web App to emulate different device setups, see Sample App configuration parameters.

To further control the features and functionality of the Sample Web App, use the Sample App environment properties.

Sample App configuration parameters

As shown in the following example, you can find the Typescript interface for the configuration in ISampleAppConfigPayload.

{
    "version" : "1.0.0",
    "description":"{{STRING}}",
    "mode":{{DeviceMode}},
    "displayMode": {{DisplayMode}},
    "audioInputInitiator":{{AudioInputInitiator}},
    "windows": [
        {{WindowConfig}},
        {{WindowConfig}},
        ...
    ]
    "defaultWindowId":"{{STRING}}",
    "deviceKeys": {{DeviceKeys}},
    "emulateDisplayDimensions":{{BOOLEAN}},
    "scaleToFill":{{BOOLEAN}},
    "liveViewCameraOptions":{{OBJECT}}
}

The following table shows the parameters for configuring the Sample Web App.

Parameter	Description	Type	Default	Required
`version`	Version of the Sample Web App supported by this configuration.	string	None	Yes
`description`	Description of device presented on the Sample Web App `HomeScreen`.	string	None	No
`mode`	The expected DeviceMode of the device. Valid values: `'AUTO', 'HUB', 'MOBILE', 'PC', 'TV'` Note: The mode values are case-sensitive. Currently only `'HUB'` and `'TV'` are fully supported device modes. `'MOBILE'`, `'PC'`, and `'AUTO'` might produce unexpected results in APL content.	string	`HUB`	No
`displayMode`	The expected display mode of the device. Valid values: `'FIXED'`: Display that doesn't change size or orientation (TV, or counter-top hub) . `'ORIENTABLE'`: Display that can be rotated (tablet, hand-held device). `'RESIZABLE'`: Display that can resize (desktop application).	string	`FIXED`	No
`audioInputInitiator`	The AudioInputInitiator type for the Sample Web App. Valid values: `PRESS_AND_HOLD`, `TAP`, `WAKEWORD`.	string	`TAP`	No
`windows`	An array of Window configuration parameters created in the Sample Web App and reported in `Alexa.Display.Window.WindowState` for targeting and presentation of directives such as APL. These windows can be targeted by ID.	Window configuration parameters array []	None	Yes
`defaultWindowId`	The ID of the Window configuration parameters used as the default for visual responses. Note: The configuration for this window ID is also used as the configuration for the PlayerInfo window for audio playback UI presentation.	string	None	Yes
`deviceKeys`	The Device Keys configuration defines core function keys in the Sample Web App about `talk, back, exit, captions, and do-not-disturb` key input.	Device Keys	None	Yes
`emulateDisplayDimensions`	When `true`, the Sample Web App's root container is explicitly sized to the device's display dimensions defined in `Alexa.Display` characteristics.	Boolean	`false`	No
`scaleToFill`	When `true`, the Sample Web App's root container is uniformly scaled to fit within the supplied browser window.	Boolean	`false`	No
`liveViewCameraOptions`	Optional configuration for the Live View Camera UI. Note: This setting is relevant only to device makers who implement live view cameras.	LiveViewCameraOptions	None	No

Window configuration parameters

The following example shows the parameters for creating windows and configuring any additional runtime features of the client, like APL, that might be running in the window.

{
    "id": "{{STRING}}",
    "displayWindowConfig": {{DisplayWindowConfig}},
    "supportedInterfaces: [
        {{STRING}},
        ...
    ],
    "zOrderIndex": {{NUMBER}},
    "windowPosition": "{{STRING}}",
    "aplRendererParameters": {{AplRendererParameters}}
}

Parameter	Description	Type	Default	Required
`id`	A unique identifier for the window instance used to target content to this window.	string	None	Yes
`displayWindowConfig`	Optional configuration if the window should be based on an `Alexa.Display.Window` definition.	DisplayWindowConfig	None	No
`supportedInterfaces`	An array of strings representing the AVS Interface for visual presentations supported by the window.	string array []	None	Yes
`zOrderIndex`	The relative z-order index for the window. Note: The `WindowManager` determines the final z-order.	number	None	Yes
`windowPosition`	The screen position of the window. Valid values are `'center', 'right', 'left', 'top', 'bottom'`. Overridden by any `windowPosition` defined in Display window configuration.	string	`center`	No
`aplRendererParameters`	Parameters for APL renderer supported by the window instance. Used only if window supports `Alexa.Presentation.APL`.	APL Renderer parameters	None	No

Display window configuration parameters

The following table shows the parameters for display window configurations based on visualCharacteristics.

{
    "templateId": "{{STRING}}",
    "configurations":   {
        "landscape": {
            "sizeConfigurationId": "{{STRING}}",
            "interactionMode": "{{STRING}}",
            "position": "{{STRING}}"
        },
        "portrait": {
            "sizeConfigurationId": "{{STRING}}",
            "interactionMode": "{{STRING}}",
            "position": "{{STRING}}"
        }
    }
}

Parameter	Description	Type	Required
`templateId`	The window template in the `Alexa.Display.Window` capability, which is the basis for this configuration.	string	Yes
`configurations`	Template orientation definitions for this display window configuration.	Orientation configurations	Yes

Display window orientation configurations

Note: The orientation configuration is only required for ORIENTABLE display types. When the display type is ORIENTABLE, you must set the orientation definition to either portrait or landscape.

The following table shows the parameters for display window orientations.

Parameter	Description	Type	Required
`landscape`	Optional Window instance configuration for `landscape` orientation.	Window instance configuration	No, unless `portrait` is not defined and display type is not `ORIENTABLE`
`portrait`	Optional Window instance configuration for `portrait` orientation.	Window instance configuration	No, unless `landscape` is not defined and display type is not `ORIENTABLE`

Display window instance parameters

The following table shows the parameters for window template instances.

Parameter	Description	Type	Default	Required
`sizeConfigurationId`	The active size configuration of the window as defined in `Alexa.Display.Window`.	string	None	Yes
`interactionMode`	An "id" value representing the current `Alexa.InteractionMode` of the window.	string	None	Yes
`position`	The optional screen position to use for this window instance configuration. Valid values are `'center', 'right', 'left', 'top', 'bottom'`.	string	None	No

APL Renderer parameters

The following example shwos the parameters for APL Renderer supported by a window instance.

{
    "theme": "{{STRING}}",
    "allowOpenUrl": {{BOOLEAN}},
    "animationQuality": "{{STRING}},
    "supportedExtensions": [
        {{STRING}},
        ...
    ]
}

Parameter	Description	Type	Default	Required
`theme`	Preferred basic color scheme of the window. Content developers might optionally use this value for styling their visual response. Valid values: `'light'` and `'dark'`.	string	`dark`	No
`allowOpenUrl`	Indicates if the window supports the APL `OpenUrl` command.	Boolean	`false`	No
`animationQuality`	Level of AnimationQuality support in the window. Valid Values: `none = 0, slow = 1, normal = 2`.	string	`normal`	No
`supportedExtensions`	An optional array of APL extension URIs supported in the window instance. Note: Any extensions declared here must have been built with the APLClient extension framework to be available to the APL runtime for the window.	string array []	`null`	No

Device Keys parameters

The following table shows the parameters for device input keys.

Parameter	Description	Type	Required
`talkKey`	Key used in the Sample Web App to send a `recognizeSpeechRequestEvent` event to the SDK with the `AudioInputInitiator` type defined in the Sample App config parameters.	Device Key	Yes
`backKey`	Key used in the Sample Web App to send a `navigationEvent` to the SDK with event type `BACK`.	Device Key	Yes
`exitKey`	Key used in the Sample Web App to send a `navigationEvent` to the SDK with event type `EXIT`.	Device Key	Yes
`toggleCaptionsKey`	Key used in the Sample Web App to send a `captionsStateChanged` Event to the SDK.	Device Key	Yes
`toggleDoNotDisturbKey`	Key used in the Sample Web App to send a `doNotDisturbStateChanged` Event to the SDK.	Device Key	Yes

Device key parameters

The following table shows the parameters for each device key.

Parameter	Description	Type	Required
`code`	Property representing a physical key on the keyboard, following the `KeyboardEvent.code` web standard.	string	Yes
`keyCode`	Property representing a system and implementation dependent numerical code identifying the unmodified value of the pressed key, following the `KeyboardEvent.keyCode` web standard.	number	Yes
`key`	Property representing the value of the key pressed by the user, following the `KeyboardEvent.key` web standard.	string	Yes

Sample App environment properties

In addition to the runtime Sample App configuration, the Sample Web App also exposes a few build-time ENV properties, which you can use to control functionality and features within the application.

You can modify the ENV properties when you build the Sample Web App by using the following commands.

cd <path-to-repo-clone>/alexa-smart-screen-web-components/samples/alexa-smart-screen-sample-app
yarn build --env <ENV_PROP>=<ENV_PROP_VALUE> --env <ENV_PROP>=<ENV_PROP_VALUE> ...

The following example shows how to change the log level.

yarn build --env LOG_LEVEL='DEBUG'

Environment properties

The following table shows the Sample App environment properties. Refer to the env configuration file for Typescript definitions.

Parameter	Description	Type	Default
`LOG_LEVEL`	The log level for logs written to the server app from the Sample Web App. Valid values: `'DEBUG'`, `'INFO'`, `'WARN'`, and `'ERROR'`.	LogLevel	`WARN`
`DISABLE_WEBSOCKET_SSL`	The SSL security property for the web socket server when the web socket server is used.	Boolean	`true`
`ENABLE_BINDER_CLIENT`	When `true`, the Sample Web App is built with the binder client instead of the web socket client for message communication.	Boolean	`false`
`ENABLE_TRANSFORM_KEY_CODES`	Sets whether to transform keyboard events to have valid KeyCodes. This setting is required only for use of the Sample Web App in browsers that don't emit KeyCodes.	Boolean	`false`
`ENABLE_LIVE_VIEW_CAMERA`	When `true`, the Sample Web App is built with Live View Camera features enabled. Note: The SDK IPC Server App must also be built with Live View Camera enabled to use this feature.	Boolean	`false`
`DEBUG_LIVE_VIEW_CAMERA_UI`	When `true` (and `ENABLE_LIVE_VIEW_CAMERA=true`), the Sample Web App auto-loads the live view camera sample payload UI on init for debugging purposes.	Boolean	`false`

Last updated: Aug 15, 2022