Upgrade from Alexa Smart Screen SDK 2.x to AVS Device SDK 3.0

With the release of AVS Device SDK 3.0, Amazon has consolidated all features and functionality provided by the Alexa Smart Screen SDK 2.x into the AVS Device SDK. As a developer or device maker, you are likely affected by the significant refactoring of some core components in the upgrade. The following sections serve as a reference for the things you need to consider when you upgrade.

Things to consider

The impact of each of the release changes on the complexity of your upgrade varies based on the degree of modification you have made to the different layers listed in the following sections. In most scenarios, to use the upgraded components, you probably need to do some porting of your existing development work.

SDK GitHub source code changes

The following table covers the changes to SDK source code on GitHub for the AVS Device SDK version 3.0.

The two main changes are that the Alexa Smart Screen SDK-based partners now access all C++ SDK components directly from the AVS Device SDK 3.0 repository, and all JavaScript-based web components are now on the Alexa Smart Screen Web Components repository.

Components GitHub release prior to AVS Device SDK 3.0 GitHub release as of AVS Device SDK 3.0
Core C++ SDK components and capabilities AVS Device SDK AVS Device SDK
Smart screen C++ SDK components and capabilities Alexa Smart Screen SDK AVS Device SDK
Smart screen web components Alexa Smart Screen SDK Alexa Smart Screen Web Components

Smart Screen Sample Application changes

The SampleApp provided by the Alexa Smart Screen SDK is repurposed in AVS Device SDK 3.0 as the IPC Server Sample Application. While it offers all the same core functionality, and some similarly named components, it is largely refactored from the Smart Screen SDK implementation. If you made significant modifications to the previous application for your device integration, you must port them to the IPC Server Sample Application, but the underlying components and architecture should remain familiar.

Just like the Alexa Smart Screen Sample App, the new IPC Server Sample Application offers build guides for the following platforms:

The following table gives an overview of many, but not all, of the core components of each sample application in the Alexa Smart Screen SDK and in the AVS Device SDK 3.0.

Sample app components Description Alexa Smart Screen SDK Sample App AVS Device SDK 3.0 - IPC Server Sample Application
Base SampleApplication directory Root directory and CMAKE listing for Smart Screen Sample Application. SampleApp IPCServerSampleApplication
Application client Central client component used to declare and configure all SDK capabilities supported by the application. SmartScreenClient DefaultClient, which is refactored to be configurable by the consuming application.
Websocket server implementation Default implementation of the Websocket++ server used for IPC communication from the application. Communication Communication
GUI manager/GUI client Application bridges between the IPC components and the application client for the purposes of GUI presentation and communication. GUIManager/GUIClient GUIManager/GUIClient
IPC message interfaces Full definition of the message types and property values that can be handled by the applicaiton's IPC components. GUIClientMessage IPC
APLClientBridge Application wrapper integration of the APLClientLibrary components. APLClientBridge APLClientBridge

Inter-process communication (IPC) message changes

Just like the Alexa Smart Screen SDK Sample Application, the new IPC Server Sample Application in AVS Device SDK 3.0 implements an IPC Server for communication with a separate client on the device that handles all graphical output and rendering. The IPC Server uses Websocket by default. The rendering most commonly is done through a web application. The primary difference between the Smart Screen SDK Sample Application and the new IPC Server Sample Application is in the schema of the IPC messages that pass between the Server Sample App and the IPC Client. In AVS Device SDK 3.0, the schema is redesigned by using the AVS Device SDK IPC Client Framework. This means that you must refactor any custom usage of the old IPC schema and messages that you might have implemented in your IPC Client to the new format.

The following table shows the IPC API Specifications for each sample application.

Alexa Smart Screen SDK IPC API AVS Device SDK 3.0 IPC API
Alexa Smart Screen SDK GUI API Specification AVS SDK IPC Client Framework (ICF)

Message schema difference

The Alexa Smart Screen SDK IPC API only used type designations for messages. With the AVS Device SDK ICF message schema, Amazon introduces a namespace-based organization to IPC messages to allow for more robust routing and handling.

The following example shows a comparison of the same IPC message from both APIs for completing Code-Based Linking (CBL) authorization in the IPC Client.

Alexa Smart Screen SDK: requestAuthorization message AVS Device SDK IPC Client Framework: completeAuthorization message
{
    type: 'requestAuthorization',
    url : string,
    code : string,
    clientId : string
}
 
{
    "header": {
        "version": 1
        "namespace": "System",
        "name": "completeAuthorization"
    },
    "payload": {
        "url": "{{STRING}}",
        "code": "{{STRING}}"
        "clientId": "{{STRING}}"
    }
}
 

For details about the requestAuthorization message in the Alexa Smart Screen SDK, see requestAuthorization.

For details about the completeAuthorization message in the AVS Device SDK IPC Client Framework, see completeAuthorization in the System interface.

JavaScript framework changes

Another change that affects you, as a current Alexa Smart Screen SDK user, is the extraction and redesign of the JavaScript-based web components. These components are for building web applications that interact with the AVS Device SDK. The Alexa Smart Screen SDK uses ReactJS-based reference Node.js application. The AVS Device SDK 3.0 replaces the ReactJS with the new Alexa Smart Screen Web Components Node.js framework. Unlike the reference offering in the Alexa Smart Screen SDK, you can use the Smart Screen Web Components as a complete product library of standalone node packages to build the web application for your Alexa Built-in device.

Although you likely need to port any changes or extensions you might have made to your existing implementation of the Smart Screen SDK web app, you still have access to a fully configurable Sample Web Application as a starting point.

The following table shows the JavaScript framework changes for AVS Device SDK 3.0.

Area Alexa Smart Screen SDK Sample Web App Alexa Smart Screen Web Components
Node.js package manager npm yarn
Node.js modules provided reference gui web application alexa-smart-screen-common
alexa-smart-screen-app-utils
alexa-smart-screen-router
alexa-smart-screen-web-socket
alexa-smart-screen-window-manager
alexa-smart-screen-apl
alexa-smart-screen-live-view-camera
alexa-smart-screen-template-runtime
alexa-smart-screen-binder-client
alexa-smart-screen-sample-attention-system
alexa-smart-screen-sample-captions
alexa-smart-screen-sample-display-cards
alexa-smart-screen-sample-app
Sample Web App config specification GUI Parameters Sample Web App configuration parameters