About Widgets and Alexa Presentation Language (APL)

An Alexa widget displays quick, essential information related to a skill and lets users perform quick actions without leaving the current screen context or asking for updates. A user can interact with a widget by touch or voice. Your skill can respond to these interactions by updating the content displayed in the widget without navigating the user away from their current task ("inline"), or by launching your skill.

For example, a widget for a weather skill might display current conditions. In an inline interaction, a button on the widget refreshes the data displayed in the widget. In a skill experience, the widget button opens the skill and displays a standard APL document with more details, such as the 5-day forecast.

You use Alexa Presentation Language (APL) to add a widget to your skill.

How users interact with widgets

Users browse available widgets in the Widget Gallery. Installing a widget from the gallery makes it available on the device. The Echo Show 15 displays a persistent Widget Panel on the home screen. On smaller devices, such as the Echo Show 8, users access widgets from the Widget Shortcuts on the home screen.

For more details about how users work with widgets on a device, see these topics in Digital Services and Device Support:

Parts of a widget

A widget consists of the following parts:

  • APL document – Defines the template to display for a widget. The widget document can use a subset of standard APL features. A subset of responsive components and templates support widgets.
  • APL package – Defines metadata and assets for the widget and associates the widget with your skill. The package includes the APL document, an initial data source, a manifest, and other assets.
  • Data store – An area on the device that stores data that your widget APL document accesses with data binding. By pulling data from the data store instead of sending requests to your skill and waiting for a response, the widget can display content with no latency. Your skill updates this data store with fresh data with calls to the Data Store REST API on a regular basis.
  • Alexa.DataStore.PackageManager interface – Provides requests that inform your skill when Alexa installs, removes, and updates an APL package on a device.
  • Alexa.DataStore interface – Requests for notifying your skill when an update pushed to the data store fails.
  • Data Store REST API – Operations for updating the data store on a device. You use this API to push updates to the data store from your skill, both when the skill responds to skill requests, and from outside a skill session.

Lifecycle of a widget

The lifecycle for a widget is different from that of a full APL document. The user must choose to install your widget on the device. An installed widget is available to the user whenever the Widget Panel is in view, or when the user selects a Widget Shortcut. Users can therefore access widgets both inside and outside of a skill session.

The widget lifecycle has three main events:

  1. User installs your widget
  2. You publish an updated version of the widget
  3. User removes a widget from the device

These lifecycle events all occur outside of a skill session. The user initiates install from the Widget Gallery and remove from the Widget Panel or Widget Shortcut. You start the update event when you publish a new version of your widget.

For details about the widget lifecycle requests, see Alexa.DataStore.PackageManager Interface Reference. For details about the APL package, see APL Package Reference.

User installs your widget

The following steps show what happens when a user finds and installs a widget:

  1. The user finds the widget in the Widget Gallery and chooses to install it.
  2. Alexa installs the widget on the user's device. Depending on the configuration of the APL package for the widget, Alexa also sends your skill an Alexa.DataStore.PackageManager.UsagesInstalled request.
  3. In the handler for the UsagesInstalled request, your skill can call the Data Store REST API to push data to the data store.

At this point, the widget displays in the Widget Panel whenever the panel is in view.

You publish an updated version of the widget

The following steps show what happens when you publish an updated version of your widget:

  1. You create and publish an updated version of your widget, perhaps with changes to the underlying APL document.
  2. For a device where your widget was already installed, Alexa detects that there is a newer version of your widget available and updates the widget with the new version. Depending on the configuration of the APL package for the widget, Alexa also sends your skill an Alexa.DataStore.PackageManager.UpdateRequest.
  3. In the handler for the UpdateRequest request, your skill can call the Data Store REST API to push updated data to the data store.

At this point, the updated widget displays in the Widget Panel whenever the panel is in view.

User removes a widget from the device

The following steps show what happens when a user removes a widget from the device:

  1. The user decides they no longer want your widget and uses a long-press on the widget in the Widget Panel or on the Widget Shortcut to remove it.
  2. The device uninstalls the widget. Depending on the configuration of the APL package for the widget, Alexa also sends your skill an Alexa.DataStore.PackageManager.UsagesRemoved request.
  3. Your skill can optionally perform any cleanup actions. For example, if you store user settings specifically for the widget, you can use your handler for the UsagesRemoved request to clear that data.

How the widget lifecycle is different from a standard APL document lifecycle

A standard APL document exists within the context of a skill session. The user invokes your skill, which starts a new skill session and sends your skill a LaunchRequest or an IntentRequest. The skill responds with the Alexa.Presentation.APL.RenderDocument directive to display a document on the screen. The document remains on the screen until the skill sends a new RenderDocument directive or until the skill session ends.

A widget APL document operates outside of this skill session, although the widget can launch a new session. You never use RenderDocument with a widget document. An installed widget displays to the user whenever the Widget Panel is in view or when the user taps shortcut for the widget. It remains in the panel until the user chooses to remove it.

A widget document can use the SendEvent command to send a request to your skill, which starts a new skill session. At that point, the normal skill session applies.

Interactions between the skill and widget

A widget can include interactive components, such as buttons and touchable areas. These interactive components can use the APL SendEvent command to send requests to your skill. This command sends an Alexa.Presentation.APL.UserEvent to your skill.

Your request handler for the UserEvent can either launch a full skill experience, or update the widget "inline" without further user interaction. For example, tapping on a widget for a weather skill might fetch newer weather data and display it in the widget, without launching the full skill.

When you use the SendEvent command in a widget, you must set the interactionMode flag to indicate how your skill can respond. For details about SendEvent, see SendEvent. For details about the UserEvent request, see UserEvent.

Widgets and the data store

The data store is an area on the device that stores data your widget APL document accesses with data binding. Your skill uses the Data Store REST API to update this data store with fresh data on a regular basis. The widget then displays this content without sending requests to your skill and waiting for a response.

To use the data store, you enable and configure the data store extension in your APL document. Then, you bind properties to the data store instead of binding them to a data source.

When defining your APL document for the widget, use the data store for any data that might change during the lifecycle of the widget. This approach is different from a standard APL document, where you use a data source for data that changes from one skill invocation to the next. For a widget, you provide an initial data source one time, as part of the static widget package. This means that the data source is static for a widget.

For details about the data store extension, see Data Store Extension. For details about the Data Store REST API for updating the data store, see Data Store REST API Reference. For details requests related to updating the data store, see Alexa.DataStore Interface Reference.

Design guidance

For design guidance when building your widget, see Widgets Introduction in the Alexa Design Guide.

High-level steps to build a widget for your skill

  1. Enable the required interfaces and configure the APL package.

    For details, see Create and Manage Widgets.

  2. Build an APL document to display as a widget. This document can use a subset of APL features, including a subset of responsive components and templates.

    To display data that might change over time, bind the document to the data store instead of a data source.

  3. Implement request handlers in your skill code to manage widget lifecycle events.

    For details, see Alexa.DataStore.PackageManager Interface Reference.

  4. If your widget includes user interactions, such as buttons or other touchable areas, implement request handlers in your skill code to handle those events.

    For details, see Alexa.Presentation.APL Interface.

  5. If your widget displays data that changes over time, use the Data Store REST API to update the data store with new data on a regular basis.

    For details, see Data Store REST API Reference and Alexa.DataStore Interface Reference.

  6. Test the widget with a device.

    For details, see Test a Widget.

  7. Certify and publish your skill to make your widget available in the Widget Gallery.

Start building a widget without a skill

To get started building a widget, you can open the authoring tool directly without starting from a skill. However, you must associate the widget with a skill to save your work.

To open the authoring tool for widgets without a skill, navigate to the following link: https://developer.amazon.com/alexa/console/ask/displays/widget/.

Note the following limitations:

  • Transformers defined in your document don't work.
  • You can't use the Install option to install the widget on a device for testing, although you can use the Preview option. Associate the widget with your skill to fully test.
  • You must associate the widget with a skill to save your work.
    1. Click the Save icon.
    2. Enter the Widget Name.
    3. From the Skill drop-down, select an existing skill.

For details, see Create and Manage Widgets.

Was this page helpful?

Last updated: Feb 29, 2024