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.

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)
nl-NL	Dutch (NL)
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.

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:

• The most recent version of the ASK CLI installed on your machine. For details, see Quick Start: Alexa Skills Kit Command Line Interface (ASK CLI). Install the ASK CLI and configure it to connect with your developer account.
• Your skill ID.

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

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.

Related topics

• Alexa.DataStore.PackageManager Interface Reference
• Add a Widget to Your Skill
• ASK CLI Command Reference

---

---

Last updated: Nov 28, 2023