Alexa Smart Screen Web Components Quick Start Guide

Follow this quick start guide to build and run the Alexa Smart Screen Sample Web App.

Prerequisites

Browser requirements

The Alexa Smart Screen Sample Web App requires a web browser to play APL media. The browser must support the following features:

Step 1: Build the Alexa Smart Screen Web Components

The following instructions use your home directory represented by $HOME and create a folder called wc-folder to hold your Node.js project. If you want to store the folder under a different path, update the commands accordingly.

1. Open a Terminal window, and then create your folder structure. Clone the apl-client-library v2022.1.1 and alexa-smart-screen-web-components version 1.0.0.

Copied to clipboard.

cd $HOME
mkdir wc-folder

cd wc-folder

git clone --single-branch --branch v2022.1.1 https://github.com/alexa/apl-client-library.git

git clone --single-branch --branch v1.0.0 https://github.com/alexa/alexa-smart-screen-web-components.git

2. Install the local APL Client JS module in the associated alexa-smart-screen-apl module.

Copied to clipboard.

cd $HOME/wc-folder/alexa-smart-screen-web-components/packages/alexa-smart-screen-apl

yarn add file: $HOME/wc-folder/apl-client-library/apl-client-js -D

3. Build the monorepo and all packages, including the Sample Web App.

Copied to clipboard.

cd $HOME/wc-folder/alexa-smart-screen-web-components

yarn install

yarn build

Step 2: Run the IPC Server Sample App

To use the alexa-smart-screen-web-components Sample App, complete the setup of the AVS Device SDK IPC Server Sample App, and then run the IPC Server Sample App.

For more details about how to run the IPC Server Sample App, see AVS SDK IPC Server Sample App Overview and choose the quick start guide that matches with your device's build platform.

Step 3: Open your Smart Screen Sample Web App

After the IPC Server Sample App is running, use the following commands to open the Smart Screen Sample Web App in your browser, and then initiate a connection to the IPC Server Sample App.

MacOS or Raspberry Pi

Copied to clipboard.

cd $HOME/wc-folder/alexa-smart-screen-web-components

open samples/alexa-smart-screen-sample-app/dist/index.html

Ubuntu

Copied to clipboard.

cd $HOME/wc-folder/alexa-smart-screen-web-components

xdg-open samples/alexa-smart-screen-sample-app/dist/index.html

For details about interacting with the Sample Web App, see Use the Smart Screen Sample Applications.

Create projects (optional)

If you want to start new Node.js projects based on the alexa-smart-screen-web-components module, initiate a Command Line Interface (CLI) for generating projects from templates in the repo.

Copied to clipboard.

cd $HOME/wc-folder/alexa-smart-screen-web-components

yarn createProject

The createProject command initiates a CLI that allows you to select a project template and name your new project.

#################################################################################
#       Welcome to the Alexa Smart Screen Web Components Project Creator!       #
#        Use the following command-line prompts to start a new project.         #
#################################################################################

? What project template would you like to use: (Use arrow keys)
  alexa-smart-screen-bare-ts 
❯ alexa-smart-screen-sample-app-copy 

? What project template would you like to use: alexa-smart-screen-sample-app-copy
? Project name: my-new-project

###################################
#       Configuring Project       #
###################################
...

The CLI copies the requested project template and its dependencies, installs all required alexa-smart-screen modules on the local path, and then builds the new project parallel to the alexa-smart-screen-web-components repo path.

Project templates

The following table shows the available template projects.

Template Description Recommended use case
alexa-smart-screen-sample-app-copy Copy of the alexa-smart-screen-sample-app as a standalone project leveraging all components from both the packages and samples workspaces. You want to use the provided Sample Web App as the starting point for your product.
alexa-smart-screen-bare-ts Bare typescript project setup including only the modules from the packages workspace. You want to implement your own app design based on alexa-smart-screen-web-components.

Install modules locally (optional)

Install any of the pre-built alexa-smart-screen-web-component modules in your local Node.js project by using yarn.

Copied to clipboard.

cd $HOME/wc-folder

yarn add file: $HOME/wc-folder/alexa-smart-screen-web-components/packages/alexa-smart-screen-apl -D

The following example shows a dependency output in your project's package.json.

 "devDependencies": {
  "@alexa-smart-screen/apl": "$HOME/wc-folder/alexa-smart-screen-web-components/packages/alexa-smart-screen-apl",
  ...
 }

Clean up dependencies (optional)

To clean up dependencies before a rebuild, run the following commands.

Copied to clipboard.

cd $HOME/wc-folder/alexa-smart-screen-web-components

yarn clean:all

rm -rf node_modules

Last updated: Nov 29, 2022