Alexa.DataStore.PackageManager Interface Reference


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

  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. 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.

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?

Last updated: Nov 28, 2023