APL Package Reference


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 widget authoring tool creates an APL package automatically when you create a new widget. You can download the package to your local machine with the Alexa Skills Kit Command Line Interface (ASK CLI). For details, see Download and update the APL package with the ASK CLI.

APL package manifest

The APL package manifest is a required JSON file that contains metadata for the package. You can edit the package manifest directly in the widget authoring tool.

The following example shows the package manifest for a widget named MyNewWidget.

Copied to clipboard.

{
  "packageVersion": "1.0",
  "packageType": "APL_PACKAGE",
  "publishingInformation": {
    "schemaVersion": "1.0",
    "locales": {
      "en-US": [
        {
          "targetViewport": "WIDGET_M",
          "metadata": {
            "name": "Widget name",
            "description": "Widget description",
            "keywords": [
              "keyword1",
              "keyword2"
            ],
            "iconUri": "https://d3ozx4qyxcxwzd.cloudfront.net/default_icon.png",
            "previews": [
              "https://d3ozx4qyxcxwzd.cloudfront.net/default_preview.png"
            ]
          }
        }
      ]
    }
  },
  "manifest": {
    "id": "MyNewWidget",
    "version": "1.0.0",
    "presentationDefinitions": [
      {
        "url": "presentations/default.tpl"
      }
    ],
    "appliesTo": "${viewport.mode == 'HUB'}"
  }
}

The following table defines the top-level properties for the APL package manifest.

Property Type Description Required

packageVersion

String

Version of the package manifest, as defined by Alexa. Set to 1.0.

Yes

packageType

String

Type of package the manifest represents.
Accepted value: APL_PACKAGE.

Yes

publishingInformation

Object

JSON object that defines the locales where the package is available to users in the Widget Gallery. For details about the properties, see publishingInformation object.

No

manifest

Object

JSON object that defines the metadata for the widget. For details about the properties, see manifest object.

Yes

publishingInformation object

The following table defines the properties for the publishingInformation object in the APL manifest.

Property Type Description Required

schemaVersion

String

Defines the schema version for the publishing information. Set to 1.0

Yes

locales

Map of locale objects

A map of locale objects. For each locale, defines metadata for the widget used when publishing the widget. Use the standard locale convention xx-YY for the key, for example: en-US for US English. At least one locale is required. For a list of locales, see locales.

Yes

locales.{locale}

Array of publishing information objects

Contains an array of publishing information for the specified {locale}.

Yes

locales.{locale}[].targetViewport

Enumeration

Viewport for which the publishing information is defined.
Accepted value: WIDGET_M.

Yes

locales.{locale}[].metadata

Object

Provides metadata used to display the widget in the Widget Gallery.

Yes

locales.{locale}[].metadata.name

String

Name of the package. Users see this name when browsing widgets in the Widget Gallery.

Yes

locales.{locale}[].metadata.description

String

Description of the package. Users see this description when they select a widget in the Widget Gallery. Explains to users what to expect when they install the widget.

Yes

locales.{locale}[].metadata.keywords

Array of strings

Keywords for the package, intended to help users search for widgets.

Yes

locales.{locale}[].metadata.iconUri

String

URI for an icon for the package. Users see this icon when browsing widgets in the Widget Gallery.

The icon must be a PNG image with the dimensions 450x450 pixels.

Yes

locales.{locale}[].metadata.previews

Array of strings

Array of preview images for the widget. Provide at least one URI for each widget size your widget supports. String must be a URI that resolves to an image with the following dimensions:

  • Medium (M) widget – 328 px x 552 px

Yes

locales

Use the locales shown in the following table.

Locale code Language

ar-SA

Arabic (SA)

de-DE

German (DE)

en-AU

English (AU)

en-CA

English (CA)

en-GB

English (UK)

en-IN

English (IN)

en-US

English (US)

es-ES

Spanish (ES)

es-MX

Spanish (MX)

es-US

Spanish (US)

fr-CA

French (CA)

fr-FR

French (FR)

hi-IN

Hindi (IN)

it-IT

Italian (IT)

ja-JP

Japanese (JP)

pt-BR

Portuguese (BR)

manifest object

The following table defines the properties for the manifest object in the APL manifest.

Property Type Description Required

id

String

Unique identifier for the package. Can contain case-sensitive alphanumeric characters (^[a-zA-Z].[a-zA-Z0-9]*$).

Yes

version

String

Version number you provide for the package. Follow the convention x.y.z, for example: 1.0.0. You increment the version when you publish updated versions of the package.

Yes

installStateChanges

Enumeration

Enumeration indicating how Alexa handles requests to install the package.
Accepted values:

  • AUTOMATIC – Alexa installs the package and doesn't send a request to your skill.
  • INFORM – Alexa installs the package and then sends a Alexa.DataStore.PackageManager.UsagesInstalled request to the skill. Use this option to update the data store when the user installs your widget.

Defaults to AUTOMATIC when not provided.

No

updateStateChanges

Enumeration

Enumeration indicating how Alexa handles requests to update the package to a new version.
Accepted values:

  • AUTOMATIC – Alexa updates the package and doesn't send a request to your skill.
  • INFORM – Alexa installs the package and then sends a Alexa.DataStore.PackageManager.UpdateRequest request to the skill. Use this option to update the data store after your widget updates to a newly-published version.

Defaults to AUTOMATIC when not provided.

No

appliesTo

Expression

An APL-style conditional expression. The Widget Gallery uses this expression to determine whether to show your widget on a given device. Use an APL-style expression that returns true or false. For example, ${viewport.mode == 'HUB'} means that this package applies to any device that is considered a HUB.

The appliesTo expression can access properties in viewport and location objects. For details, see appliesTo.

Yes

presentationDefinitions

Array of objects

An array of objects that define presentation templates to display. A template is a file with a TPL extension. The contents of the template identify the APL document and data source to use for the presentation. For details, see presentationDefinitions.

Yes

appliesTo

Provide an APL-style expression that evaluates to true or false. The Widget Gallery uses this expression to determine whether to show your widget on a given device. The expression can use the logical operators and comparison operators described in the data-binding syntax.

The expression has access to a limited context that contains viewport and location.

Property Type description

viewport

Object

Provides properties about the device viewport. You can define criteria to include the package on devices that satisfy the viewport conditions.

viewport.mode

Enumeration

The mode of the viewport.
Accepted value: HUB.

viewport.shape

Enumeration

The shape of the viewport.
Accepted value: RECTANGLE.

viewport.width

Integer

The width of the viewport in density independent pixels (dp). Values are always positive integers in the range 0–3000.

viewport.height

Integer

The height of the viewport in density independent pixels (dp). Values are always positive integers in the range 0–3000.

location

Enumeration

The location where the package can be installed.
Accepted value:

  • FAVORITE – Widget Panel displayed on Echo Show devices.

For example, the following expression indicates that the widget can display on a hub device: ${viewport.mode == 'HUB'}

presentationDefinitions

The presentationDefinitions array contains objects that identify presentation definitions. A presentation definition identifies the APL document and data source to display.

Each object in the presentationDefinitions array has a url property that identifies the location of a presentation definition file. The location is relative to the root directory for the package. For example, the locationpresentations/default.tpl means that the package has a directory called presentations that contains a template called default.tpl.

A widget can provide a single presentation definition file, so this array must contain one item.

For details about the contents of the TPL file, see Presentation definition file format.

APL package file structure

The APL package for a skill is a subset of the full skill package for the skill. You can use the ASK CLI to download and manage a skill package.

The APL package for a skill is stored in a dataStorePackages folder within the skill package. The package is a folder with the widget ID for the name.

The following example shows the skill package structure for a skill that has one standard APL document called helloWorldResponse and one widget called MyNewWidget.

skill-package
├── dataStorePackages
│   └── MyNewWidget
│       ├── datasources
│       │   └── default.json
│       ├── documents
│       │   └── document.json
│       ├── manifest.json
│       └── presentations
│           └── default.tpl
├── interactionModels
│   └── custom
│       └── en-US.json
├── response
│   └── display
│       └── helloWorldResponse
│           ├── datasources
│           │   └── default.json
│           ├── document.json
│           └── sources
│               └── default.json
└── skill.json

The following table shows the folder structure for the widget.

File or folder Description Required?

dataStorePackages

Folder within the skill package that contains a folder for each APL package associated with the skill.

Yes

dataStorePackages/{APL_PACKAGE_ID}

Folder for a specific package. The name must match the ID you use for the widget.

Yes

dataStorePackages/{APL_PACKAGE_ID}/datasources

Folder to contain JSON files that represent the data sources for the widget. For a widget, use the data sources for static data. Provide a JSON file with the data sources, and set the datasourceUrl property in the presentation template file (TPL) to the relative path to this file.

When you create a widget in the authoring tool, the tool saves the datasources you provide in the tool in the datasources/default.json file.

No

dataStorePackages/{APL_PACKAGE_ID}/documents/

Folder to contain the APL documents used to display the widget. Provide a JSON file with the document, and set the documentUrl property in the presentation template file (TPL) to the relative path to this file.

When you create a widget in the authoring tool, the tool saves the document you provide in the tool in the documents/document.json file.

Yes

dataStorePackages/{APL_PACKAGE_ID}/manifest.json

Manifest file for the APL package. For details, see APL package manifest.

Yes

dataStorePackages/{APL_PACKAGE_ID}/presentations/

Folder that contains presentation files. A presentation definition file identifies the APL document and data source to display.

When you create a widget in the authoring tool, the tool saves a default presentation definition file in the presentations/default.tpl file. For details about the contents of the TPL file, see Presentation definition file format.

Yes

For details about the structure for the full skill package, see Skill Package API Reference.

Presentation definition file format

A presentation definition file is a JSON file with the TPL extension. The JSON object in the file has the fields shown in the following table.

Property Type Description Required

type

Enumeration

Describes the presentation to be rendered on the viewport.
Accepted value: APL_PRESENTATION.

Yes

documentUrl

String

Specifies a relative path to the package root directory pointing to a document authored as part of a package.

Yes

datasourceUrl

String

Specifies a relative path to the package root directory pointing to a data source authored as part of a package.

Yes

The following example shows a presentation definition file. This package has a documents directory that contains the APL document document.json and a datasources directory that contains the data source file named default.json.

{
  "type": "APL_PRESENTATION",
  "documentUrl": "documents/document.json",
  "datasourceUrl": "datasources/default.json"
}

A widget can provide a single presentation definition file. When you create a new widget in the developer console, the tool creates a package that includes the default TPL file, configured to refer to a single APL document and data source. To view this file, download the APL package with the ASK CLI.

Download and update the APL package with the ASK CLI

You can use the ASK CLI to download the skill package for your skill. The APL package is a subset of the skill package.

Before you begin, make sure you have the following:

You use the export-package command to download the package.

ask smapi export-package --skill-id {skill-id} -g development

After the command completes, find the APL package for your widget in the folder skill-package/dataStorePackages/{APL_PACKAGE_ID}. For details about the structure of an APL package, see APL package file structure.

To upload your local changes to the APL package, you use either ask deploy or git push, depending on the type of skill.

  • Use git push to upload changes to an Alexa-hosted skill.
  • Use ask deploy to upload changes to a self-hosted skill.

These commands upload your changes and rebuild your skill. Use the ask smapi get-skill-status command to check the progress of the build.


Was this page helpful?

Last updated: Nov 28, 2023