Alexa.DataStore.PackageManager Interface Reference

Note: Learn how to improve your skills with APL with Build visually rich experiences using APL at the Alexa Learning Lab.

The Alexa.DataStore.PackageManager interface provides requests that inform your skill when Alexa installs, removes, and updates an APL package on a device. An APL package is a self contained resource of APL documents and related assets used to render an APL experience on a specific viewport, such as for a widget.

Use the Alexa.DataStore.PackageManager interface to manage an APL package on a device.

For more details about the APL package format, see APL Package Reference.

Enable the Alexa.DataStore.PackageManager interface

To use the Alexa.DataStore.PackageManager interface, you must enable it in your skill. You can use either the developer console or the ASK CLI to update your skill to support this interface.

Configure interface in the developer console

Sign in to the developer console, and click the name of the skill you want to configure.
Navigate to the Build > Interfaces page.
Enable the Data Store Packages option.
Click Save Interfaces and then Build Model to re-build your interaction model.

Configure interface with the ASK CLI

Add ALEXA_DATASTORE_PACKAGEMANAGER to your skill manifest in the manifest.apis.custom.interfaces array. When you enable the interface, you also specify the id for each package in your skill. Each package corresponds to a widget.

The following example shows how to enable the interface in your skill manifest in the array.

{
  "manifest": {
    "apis": {
      "custom": {
        "endpoint": {},
        "interfaces": [
          {
            "type": "ALEXA_DATASTORE_PACKAGEMANAGER",
            "packages": [
              {
                "id": "MyWidget1"
              },
              {
                "id": "MyWidget2"
              }
            ]
          }
        ],
        "regions": {}
      }
    },
    "manifestVersion": "1.0",
    "privacyAndCompliance": {},
    "publishingInformation": {}
  }
}

Requests

The following table lists the requests available in the Alexa.DataStore.PackageManager interface.

Request	Description
`UsagesInstalled`	Sent to your skill when Alexa installs your package on a user's device. This request applies when `installStateChanges` is set to `INFORM` in the package manifest.
`UsagesRemoved`	Sent to your skill when a user chooses to remove your widget from a device and Alexa uninstalls the package.
`UpdateRequest`	Sent to your skill when Alexa updates your package on a user's device with a new version. This request applies when `updateStateChanges` is set to `INFORM` in the package manifest.
`InstallationError`	Sent to notify the skill about any errors that happened during package installation, removal, or updates.

UsagesInstalled request

Your skill receives the UsagesInstalled request when Alexa installs your package on a user's device, and that package is configured with installStateChanges set to INFORM. If the installStateChanges property is set to AUTOMATIC, Alexa doesn't send this request.

Use this request to update the data store on the device with initial data to display in the widget. Use the Data Store REST API to update the data store. For details, see Data Store REST API Reference.

The following example shows a UsagesInstalled request.

{
  "type": "Alexa.DataStore.PackageManager.UsagesInstalled",
  "payload": {
    "packageId": "WeatherWidget",
    "packageVersion": "1.0.0",
    "usages": [
      {
        "instanceId": "amzn1.ask.package.v1.instance.v1.{uuid}",
        "location": "FAVORITE"
      }
    ]
  }
}

UsagesInstalled properties

The UsagesInstalled request has the properties shown in the following table.

Property	Type	Required	Description
`type`	String	yes	Type of request. Always `Alexa.DataStore.PackageManager.UsagesInstalled`.
`payload.packageId`	String	yes	Package identifier for the package that was installed on the device.
`payload.packageVersion`	String	yes	Version of the package that was installed on the device.
`payload.usages`	Array of objects	yes	Array of usages for the package.
`payload.usages[].instanceId`	String	no	Identifier of the package instance installed on the device.
`payload.usages[].location`	String	yes	Enumeration indicating where the package is installed on the device. Possible value: `FAVORITE`.

Valid responses

Your skill can respond to the UsagesInstalled request with a standard response.

UsagesRemoved request

Your skill receives the UsagesRemoved request when a user chooses to remove your widget from a device and Alexa uninstalls the package.

Use this request to clear data from data store on the device. Use the Data Store REST API to update the data store. For details, see Data Store REST API Reference.

The following example shows a UsagesRemoved request.

{
  "type": "Alexa.DataStore.PackageManager.UsagesRemoved",
  "payload": {
    "packageId": "WeatherWidget",
    "packageVersion": "1.0.0",
    "usages": [
      {
        "instanceId": "amzn1.ask.package.v1.instance.v1.{uuid}",
        "location": "FAVORITE"
      }
    ]
  }
}

UsagesRemoved properties

The UsagesRemoved request has the properties shown in the following table.

Property	Type	Required	Description
`type`	String	Yes	Type of request. Always set to `Alexa.DataStore.PackageManager.UsagesRemoved`.
`payload.packageId`	String	Yes	Package ID for the widget package that has been removed. You set the package ID when you create the packageFor details, see Create and Manage Widgets.
`payload.packageVersion`	String	Yes	Version of the package that has been removed.
`payload.usages`	Array of objects	yes	Array of usages for the package.
`payload.usages[].instanceId`	String	no	Identifier of the package instance installed on the device.
`payload.usages[].location`	String	yes	Enumeration indicating where the package is installed on the device. Possible value: `FAVORITE`.

Valid responses

Your skill can respond to the UsagesRemoved request with a standard response.

UpdateRequest request

Your skill receives the UpdateRequest request when Alexa updates your package on a user's device with a new version, and that package is configured with updateStateChanges set to INFORM. If the updateStateChanges property is set to AUTOMATIC, Alexa doesn't send this request after an update.

An update occurs when you publish a new version of your package with an incremented version in the package manifest. Alexa determines which user devices have the old version of the package installed, updates the devices with the new version, and sends the UpdateRequest to your skill to inform you of the update. The request includes the old version number and the new version number for the package.

Use this request to update the data store on the device with data to display in the new version of the widget. Use the Data Store REST API to update the data store. For details, see Data Store REST API Reference.

Note: Alexa sends the UpdateRequest request for live skills. Your skill doesn't get this request when the skill is in the development stage.

The following example shows an UpdateRequest request.

{
  "request": {
    "type": "Alexa.DataStore.PackageManager.UpdateRequest",
    "packageId": "WeatherWidget",
    "fromVersion": "1.0.0",
    "toVersion": "1.0.1"
  }
}

UpdateRequest properties

Property	Type	Required	Description
`type`	String	Yes	Type of the request. Set to `Alexa.DataStore.PackageManager.UpdateRequest`.
`packageId`	String	Yes	Package ID for the package to update.
`fromVersion`	String	Yes	The previous version of the package. This version of the package was previously installed on the device.
`toVersion`	String	Yes	New version of the package after the update.

Valid responses

Your skill can respond to the UpdateRequest request with a standard response.

InstallationError request

Sent to notify the skill about any errors that happened during package installation, removal, or updates.

The following example shows an InstallationError request notification.

{
  "type": "Alexa.DataStore.PackageManager.InstallationError",
  "packageId": "WeatherWidget",
  "version": "1.0.0",
  "error": {
    "type": "PACKAGEMANAGER_INTERNAL_ERROR",
    "content": {}
  }
}

InstallationError properties

Property	Type	Required	Description
`type`	String	Yes	Type of request. Set to `Alexa.DataStore.PackageManager.InstallationError`.
`packageId`	String	Yes	Package ID for the widget package that triggered the error.
`version`	String	Yes	Version of the package that triggered the error.
`error`	Error object	No	Error object that contains details about the error that occurred.

Error types

Type	Description
`PACKAGEMANAGER_INTERNAL_ERROR`	An internal error occurred when the device attempted to install or update the package.

Valid responses

Your skill can respond to the InstallationError request with a standard response.

Alexa.DataStore.PackageManager object in the request

The context.Alexa.DataStore.PackageManager object in the skill request provides information about the packages installed on the device. The object provides details for packages installed by your skill.

{
  "version": "1.0",
  "session": {},
  "context": {
    "AudioPlayer": {},
    "Viewports": [],
    "Alexa.Presentation.APL": {
      "presentationUri": "<string>"
    },
    "Alexa.DataStore.PackageManager": {
      "installedPackages": [
        {
          "packageId": "<packageId>",
          "packageVersion": "1.0.0"
        }
      ]
    }
  }
}

Property	Type	Required	Description
`installedPackages`	Array	Yes	Array of objects representing the packages installed on the device. Includes installs packages associated with your skill.
`installedPackages[].packageId`	String	Yes	Identifier of the package installed on the device.
`installedPackages[].packageVersion`	String	Yes	Version of the package installed on the device.

Was this page helpful?

Provide feedback

Last updated: Nov 28, 2023

Alexa.DataStore.PackageManager Interface Reference

Enable the Alexa.DataStore.PackageManager interface

Configure interface in the developer console

Configure interface with the ASK CLI

Requests

UsagesInstalled request

UsagesInstalled properties

Valid responses

UsagesRemoved request

UsagesRemoved properties

Valid responses

UpdateRequest request

UpdateRequest properties

Valid responses

InstallationError request

InstallationError properties

Error types

Valid responses

Alexa.DataStore.PackageManager object in the request

Related topics

Was this page helpful?