Web API Extensions for Games Overview

Alexa web API extensions are add-ons to the existing Web API JavaScript SDK that enable, enhance, and modify the capabilities of compatible devices. Today, extensions are developed and maintained by Amazon, but future extensions might be contributed by third-party developers.

You can use the extensions to add features to your web app to enhance the user game experience. For example, you can turn the screen to face the player in a multiplayer game or detect the presence of a player in view of the camera. Extensions add a visually engaging and immersive experience to your game, but a given extension might not be available on all devices.

Available extensions

Before you use an extension, review Understand the Alexa Web API for Games for details about how to create a web app that users can play on Alexa-enabled devices.

Add extensions to your skill

Before you can use an extension in your web app, you must declare the extensions you intend to use in the skill manifest. In addition, some extensions have default behavior that you can turn on or off in the manifest. For details about the skill manifest, see Skill Manifest Schema.

Declare these extensions in the manifest in apis.custom.interfaces in the ALEXA_EXTENSION interface. The ALEXA_EXTENSION interface has the following properties.

Field Description Type
type Must be ALEXA_EXTENSION. string
requestedExtensions Contains an array of extensions you want to use in your web app.
Each object in the array has the uri property set to the URI of the extension to enable. The specific uri is unique per extension.
For example, the smart-motion extension URI is alexaext:smartmotion:10.
To determine the uri for the specific extension, see Available extensions.
An array of objects
autoInitializedExtensions Contains an array of settings that you can configure with default behavior. These settings let you turn on no code behavior for extensions that support it.

Each object has two properties:
* uri – The URI of the extension to configure. The extension must support default settings.
* settings – A set of key/value pairs for each extension setting you can configure in the skill manifest.

For example, for the smart-motion extension, you can set a default wakeWordResponse in autoInitializedExtensions.
An array of objects

The following example shows the manifest configured for two new extensions, entity sensing and smart motion. This example also shows the wakeWordResponse setting for smart motion.

  "apis": {
    "custom": {
      "interfaces": [
        {
          "type": "ALEXA_EXTENSION",
          "requestedExtensions": [
            {
              "uri": "alexaext:entitysensing:10"
            },
            {
              "uri": "alexaext:smartmotion:10"
            }
          ],
          "autoInitializedExtensions": [
            {
              "uri": "alexaext:smartmotion:10",
              "settings": {
                  "wakeWordResponse": "turnToWakeWord"
              }
            }
          ]
        }
      ]
    }
  }

For details about the settings you can configure for an extension, see Available extensions.

After you save your manifest file, update the skill manifest by using the Alexa Skills Kit Command Line Interface.

You can also configure the skill manifest in the developer console. For details, see Available extensions.

Add extensions to your web app

Just like the Web API for Games JavaScript SDK, extensions are available as JavaScript libraries. Your web app code uses the extension interfaces to communicate with the device.

To load an Alexa JavaScript extension library, include the URL in a script tag on your HTML page. Include one script tag for each extension library you want to use. To determine the URL for a specific extension, see Available extensions.

The following example shows how to add two new extensions, entity sensing and smart motion.

<head>
      <script src="https://cdn.html.games.alexa.a2z.com/extensions/entity-sensing/v10/entity-sensing.js"></script>
      <script src="https://cdn.html.games.alexa.a2z.com/extensions/smart-motion/v10/smart-motion.js"></script>
</head>

Initialize the extension client to allow the app to talk to the device. Include an await for each extension library you want to use. You can determine whether the device supports the extension by checking the alexa.capabilities object. For details about the initialization procedure for a specific extension, see Available extensions.

The following example shows initialization of two extensions, entity sensing and smart motion.

Alexa.create({version: "1.1"})
    .then(async ({alexa, message, createExtensionsMessageProvider}) => {
        if(alexa.capabilities.extensions['alexaext:entitysensing:10']) {
            entitySensing = await EntitySensing.create(createExtensionsMessageProvider);
        }
        if(alexa.capabilities.extensions['alexaext:smartmotion:10']) {
            smartMotion = await SmartMotion.create(createExtensionsMessageProvider);
        }
    });