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'

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.

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.

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.

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

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.

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.

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