Add a Widget to Your Skill

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

Configure your skill to support widgets

To support widgets, your skill must support the following:

In addition, a widget requires an APL package that defines metadata and other assets for the widget.

For details about adding a widget, see Create and Manage Widgets.

Build an APL document to display your widget

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 displays the widget.

An APL document for a widget uses the same structure as a document for a full-screen template. You can use a subset of APL features in a document for a widget. You can also use a subset of responsive components and templates that support widgets.

The developer console provides a separate authoring tool for editing widget documents.

To open the authoring tool for widgets

  1. Sign in to the developer console, and click the name of the skill you want to update.
  2. In the left-hand navigation, click Multimodal Responses.
  3. To see the list of widgets for this skill, click Widget.
  4. To create a new widget, Create Widget. To edit an existing widget, find the widget in the list and click Edit.

For details, see Create an APL document for your new widget in the authoring tool.

If your widget displays content that changes over time, configure the document with the data store extension and bind the properties in the document to the data store instead of a data source. For details about the data store extension, see APL Data Store Extension.

For a reference to APL document structure, see APL document. For details about the responsive components and templates you can use in a widget, see Responsive Components and Templates. For a list of APL features not supported in widgets, see APL features not supported in Widgets.

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

Keep the widget data up-to-date

If your widget displays content that changes over time, you store that data in the data store on the device. Then, periodically update the data store with fresh data. This approach lets the widget always display current information with no latency.

Use the Data store REST API to update the data store. You use this API to push updates to the data store from any request sent your skill, and from outside the skill session.

For example, a weather skill might include a service that pushes an updated forecast to the data store at defined intervals, such as every hour. In addition, when a user taps the widget, the skill might fetch the current conditions to display.

For details about the Data Store REST API, see Data Store REST API Reference.

Handle widget lifecycle events

The widget lifecycle events send requests to your skill to notify you when Alexa installs, updates, or removes your widget from a user's device. Use these events to trigger updates to the data store on the device. For example, when a user installs your widget, your skill can optionally receive the Alexa.DataStore.PackageManager.UsagesInstalled request. In your handler for this request, update the data store on the device with new data for your widget.

For details about the requests your skill receives for these widget actions, see Alexa.DataStore.PackageManager Interface Reference. For an overview of the widget lifecycle, see Lifecycle of a widget.

Handle widget user interactions

As with a standard APL document, a widget supports user interactions. You can use touchable components, such as TouchWrapper, to define buttons and areas the user can tap. The responsive components and templates also include interactive elements. For example, use the FooterActionButton responsive component to display a button at the bottom of a widget.

Run commands in response to these user interactions. Widgets support a subset of commands. For a list of APL commands that support widgets, see Standard Commands.

Use the SendEvent command to send requests to your skill. As with a standard APL document, 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 do one of the following actions:

  • Inline response – Fetch newer weather data and display it in the widget, without launching the full skill or returning any text-to-speech.
  • Standard response – Open the full skill, return text-to-speech with more information, and display forecast details in a standard APL document.

You set the interaction mode for the interaction when you run the SendEvent command, and then return the correct type of response from the event handler in your skill. For details, see the following topics:

Test a widget

Test your widget as you build your document and write request handlers. You can use the authoring tool to preview your widget as you build, but you must use a device with a screen to fully test your widget end-to-end. For details, see Test a Widget.

Was this page helpful?

Last updated: Feb 29, 2024