Widgets Reference

Widgets use standard Alexa Presentation Language (APL) features, such as documents, data binding, and APL extensions. Widgets also use widget-specific APIs and interfaces. The following sections summarize the reference material related to widgets.

APL document for widgets

An APL document is a JSON object that defines a template to display. For a widget, the document defines the template to display when the device shows the widget in the Widget Panel. An APL document for a widget uses the same structure as a document for a full-screen template. For a reference to APL document structure, see APL document.

APL commands

APL commands let you change the presentation displayed on the screen and send messages to your skill. You can start commands from multiple places:

  • You can run APL commands from APL event handlers within the document, such as the onPress handler of a TouchWrapper. For example, you can define a TouchWrapper component that runs the SendEvent command to send a request to your skill from the widget.
  • You can use the Alexa.Presentation.APL.ExecuteCommands directive to send commands to your widget from your skill. This directive is the same directive you use to send commands to a full APL document. Instead of providing a token as you do for a full APL document, you must provide a presentationUri that corresponds to a widget installed on the user's device to target a widget with a command

For a list of APL commands that support widgets, see Standard Commands.

Data binding and the data store

APL documents use data binding to retrieve data from a separate data source. An APL document for a widget uses the same syntax for data-binding expressions. However, note the following differences:

  • A document for a widget can retrieve data from the data store on the user's device. Widgets use the data store so that they can access data without sending a request back to your skill and waiting on a response. To access the data store in a data-binding expression, your APL document must use the data store extension.
  • A document for a widget can also retrieve data from a data source, the same as a document for a full-screen template. However, the data source is part of the APL package that Alexa installs on the user's device. Your skill can't update the data source after Alexa installs the widget.

Use the data source or data store under the following conditions:

  • Use the data source for the initial widget data and for static content.
  • Use the data store for any data that you want to update after the user has chosen to install your widget.

For details about the data store extension, see APL Data Store Extension.

For details about data binding and data-binding expressions, see APL Data-Binding Evaluation and APL Data-Binding Syntax.

APL package

An APL package is a self contained resource of APL documents and related assets used to render an APL experience on a specific viewport. You use an APL package to define an APL experience that renders in the widget viewports. When a user installs your widget on a device, Alexa installs your package on the device, and then the device uses the content of the package to render your widget in the Widget Panel.

The package includes the APL document, an initial data source, and a manifest.

For details about the APL package structure, see APL Package Reference.

Request and response interfaces for widgets

The following skill request and response interfaces provide requests for managing APL packages and the data store on a device:

  • Alexa.DataStore interface – Provides requests that notify your skill about errors that might occur when you update the data store on a device. For details about this interface, see Alexa.DataStore Interface Reference.
  • Alexa.DataStore.PackageManager interface – Provides requests that inform your skill when Alexa installs, removes, and updates your widget on a device. For details about this interface, see Alexa.DataStore.PackageManager Interface Reference.
  • Alexa.Presentation.APL interface – Provides standard directives and events for interacting with APL. You can use this interface with widgets, similar to how you use it with full APL documents. Your APL document can send your skill UserEvent requests. Your skill can send the widget commands to run with the ExecuteCommands directive.
    • To see a list of directives in this interface that support widgets, see Directives
    • To see a list of requests in this interfaces that support widgets, see Requests

When Alexa sends a request to your skill when your widget is in view, the request includes information about the widget. For details, see Widget Information in the Skill Request.

Data store REST API and data store commands

The Data Store REST API provides operations for updating the data store on a device. You can use the API to push updates to the data store from requests sent to your skill and from outside of a skill session. You use this API to send the device data store commands to update the data store.

For details about the Data Store REST API and the commands you can send, see Data Store REST API Reference.

APL features not supported in Widgets

Widgets display in the Widget Panel on a device. Because of this interface, widgets don't support all APL features.

The environment object in the data-binding context includes flags that return true for some unsupported features.

Feature Disallow flag

The EditText component for editable text fields.

environment.disallowEditText

The Video component for playing video.

environment.disallowVideo

The SpeakList and SpeakItem command.

environment.disallowDialog

The LongPress gesture.

Users use a long press gesture in the Widget Panel to remove or rearrange widgets.

None

Dynamic data sources.

To update a list of items in the data store with the Data Store REST API or Alexa.DataStore interface, you must send the entire list.

None

The SwipeAway gesture.

This gesture is supported, but not recommended. If you use a swipe gesture within a widget, you might confuse users by interfering with expanding or closing the Widget Panel.

None

Was this page helpful?

Last updated: Nov 28, 2023