Create and Manage Widgets

To add a widget to your skill, you enable the interfaces used to manage widgets on the device. Then, you create an Alexa Presentation Language (APL) document for the widget and configure an APL package. The package contains a manifest and other assets for displaying your document in the Widget Gallery and Widget Panel on the device.

You can complete these steps in the developer console.

Enable the interfaces for widgets

To support widgets, your skill must support the following:

Configure your skill with the required interfaces

  1. Sign in to the developer console, and click the name of the skill you want to configure.
  2. Navigate to the Build > Interfaces page.
  3. Enable the Data Store Packages option.
  4. Enable the Data Store option.
  5. Under Alexa Extensions, make sure that Data Store is selected.
  6. Click Save Interfaces and then Build Model to re-build your interaction model.

Create or edit a widget in the authoring tool

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 on the device.

You can use the widget authoring tool to edit the widget and preview it on a device. The widget authoring tool is similar to the authoring tool for normal APL documents, but includes some additional widget-specific features.

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.

Create a widget for a skill

To access the list of widgets for a skill in the developer console

  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.

The authoring tool provides several templates you can use as a starting point. These templates are based on the responsive templates for widgets.

To create a new widget document

  1. Open your skill in the developer console and navigate to the list of widgets.
  2. Click Create Widget.
  3. Do one of the following:
    • To start from a template, click one of the available templates.
    • To start from a blank document, click Blank Document.
    • To upload an APL document from a file, click Upload and follow the prompts.
  4. Click the Save button to save your widget document. The name you provide becomes the widget ID you use when referencing the widget in the package manifest and in your skill code.

After you create a new widget, use the authoring tool to build out your document. Widgets support most APL features. 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.

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.

To edit an existing widget in the authoring tool

  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. Find the widget in the list and click Edit.

Update the APL package manifest for your widget

A widget requires an APL package that includes a manifest with information about the widget. When you create and save a new widget document in the authoring tool, the tool creates this package automatically. You can edit the package manifest directly in the authoring tool.

Edit the package manifest to provide the user-facing name, description, and preview image assets for your widget.

To edit the package manifest for the widget

  1. Open the list of widgets in the authoring tool.
  2. Find the widget to update and click Edit.

  3. In the toolbar, click Manifest

    Manifest toolbar button

    The Manifest section opens a JSON editor with the APL Package manifest for the widget.

  4. Edit the data in the manifest:
    • To update the name and description users see in the Widget Gallery, update the fields in the publishingInformation section.
    • For a full reference to the package structure and the manifest.json schema, see APL Package Reference.

You can also use the Alexa Skills Kit Command Line Interface (ASK CLI) to download and update the APL package. For details, see Download and update the APL package with the ASK CLI.

Preview your widget

Preview and test your widget as you build. You can use the authoring tool to preview your widget layout 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