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

1. From the command line, clone the apl-client-library v2022.1.1 and alexa-smart-screen-web-components version 1.0.0.

  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.

  cd <path-to-repo-clone>/alexa-smart-screen-web-components/packages/alexa-smart-screen-apl

  yarn add file: <path-to-apl-client-library-repo-clone>/apl-client-js -D

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

  cd <path-to-repo-clone>/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.

  cd <path-to-repo-clone>/alexa-smart-screen-web-components

  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.

cd <path-to-repo-clone>/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.

cd <your-node-project>

yarn add file: <path-to-repo-clone>/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": "<path-to-repo-clone>/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.

cd <path-to-repo-clone>/alexa-smart-screen-web-components

yarn clean:all

rm -rf node_modules