Specify Echo Button Skill Details

Every Alexa skill has various metadata associated with it. Examples of this metadata are the skill name, supported locales, category, publishing information, and so on. You specify this metadata in one of two ways:

This topic describes the metadata that is unique to Echo Button skills, and the options that you can choose.

Echo Button Skill Metadata

In addition to the typical metadata for custom skills, there are several metadata fields that relate specifically to Echo Button skills. This metadata includes:

These are described next.

Alexa Gadget Interfaces

The interfaces that you choose for your skill are the APIs that your skill supports in addition to the custom skill API. The interfaces that are specific to Echo Button skills are:

Although these interfaces are independent, Echo Button skills typically support both interfaces.

Echo Button Use

If your skill supports the Game Engine or the Gadget Controller interface, you must specify whether Echo Buttons are required or optional.

On the skill's detail page in the Alexa Skill Store, this information is displayed as follows:

Specified by Skill Creator Displayed in the Alexa Skill Store
Echo Buttons Required Requires: [N] Echo Buttons
Echo Buttons Optional Optional: [N] Echo Buttons

The following is an example of how a skill with Echo Buttons required is displayed in the Alexa Skill Store:

Echo Button Skill in Alexa Skill Store

Number of Echo Buttons

The following two fields relate to the number of Echo Buttons:

  • Minimum Number of Echo Buttons – This is the minimum number of Echo Buttons that your skill requires. The possible values are 1-4. If the skill supports the Game Engine, this field is required.

  • Maximum Number of Echo Buttons – This is the maximum number of Echo Buttons that your skill supports. The possible values are 1-4. If the skill supports the Game Engine, this field is required. If you choose the same value for the minimum and maximum, the skill's detail page in the Alexa Skill Store will show the matching value as the number of Echo Buttons (required or optional, depending on the value of Echo Button Use).

The following are some examples of how the minimum and maximum number of Echo Buttons are displayed on the skill's detail page in the Alexa Skill Store:

Specified by Skill Creator Displayed in the Alexa Skill Store
Echo Buttons Required, Min Buttons = 1, Max Buttons = 2 Requires: 1-2 Echo Buttons
Echo Buttons Required, Min Buttons = 2, Max Buttons = 2 Requires: 2 Echo Buttons
Echo Buttons Optional, Min Buttons = 1, Max Buttons = 2 Optional: 1-2 Echo Buttons
Echo Buttons Optional, Min Buttons = 2, Max Buttons = 2 Optional: 2 Echo Buttons

Number of Players

The following two fields relate to the number of players:

  • Minimum Number of Players – This is the minimum number of users that the skill supports. The possible values are 1-16. If the skill supports the Game Engine, this field is required.

  • Maximum Number of Players – This is the maximum number of users that the skill supports. The possible values are 1-16 and No Limit. If the skill supports the Game Engine, this field is required. If there is no limit, you can select No Limit in the developer console or, in the skill manifest, omit this field or set it to null.

The following are some examples of how the minimum and maximum number of players are displayed on the skill's detail page in the Alexa Skill Store:

Specified by Skill Creator Displayed in the Alexa Skill Store
Min Players = 1, Max Players = 4 Players: 1-4
Min Players = 1, Max Players = 1 Players: 1
Min Players = 2, Max Players = No Limit Players: 2 or more

How to Specify Skill Metadata

When you create or edit a skill, you specify the skill's metadata using the Alexa Skills Kit developer console or the ASK CLI.

Using the Developer Console

In the Alexa Skills Kit developer console, you can specify the skill metadata by selecting options as you create or edit the skill.

To choose which Alexa Gadget interfaces that your skill supports after you create a skill, do the following:

  1. In the Alexa Skills Kit developer console, find your skill and, under Actions, select Edit.
  2. On the left side, select Interfaces.
  3. In the Alexa Gadget row of the interface list, select Gadget Controller, Game Engine, or both.

To define the Echo Button metadata that is displayed to users on the skill's detail page in the Alexa Skill Store:

  1. In the Alexa Skills Kit developer console, find your skill and, under Actions, select Edit.
  2. Select Distribution from the top menu.
  3. In the middle of the page, select options for Echo Button Use, Number of Echo Buttons, and Number of Players.

Using the Skill Manifest

To add Echo Button support to your skill by using the ASK CLI, you edit the skill manifest. The skill manifest is a file that contains the JSON representation of your skill metadata.

How to Get the Skill Manifest

There are two ways to get the skill manifest:

  • New skill – When you create a new skill by using the ASK CLI new command, a simple skill manifest is created for you. This file is called skill.json and it is in the root of the skill project directory that the ASK CLI created on your computer.
  • Existing skill – You can get the skill manifest of an existing skill by using get-skill.

After you get the skill manifest, you can open and edit the file with a text editor. After you edit it, you can upload it using update-skill or deploy.

Skill Manifest Fields

The following shows the skill manifest representation of the Echo Button-related metadata described earlier. For specific examples, see Use Cases.

{
  "publishingInformation": {
    "gadgetSupport": {
      "requirement": "REQUIRED", // or "OPTIONAL"
      "numPlayersMin": int,
      "numPlayersMax": int, // or null
      "minGadgetButtons": int,
      "maxGadgetButtons": int // or null     
    }
  },
  "apis": {
    "custom": {
      "interfaces": [
        {
          "type": "GAME_ENGINE"
        },
        {
          "type": "GADGET_CONTROLLER"
        }
      ]
    }
  }
}

Use Cases

The following are examples of Echo Button skill metadata for the following use cases:

Skills That Receive Echo Button Input and Control Echo Buttons

If you want your skill to both receive Echo Button input and control Echo Buttons, you:

  • Must specify both the Game Engine and Gadget Controller as supported interfaces.
  • Must specify whether Echo Buttons are required or optional.
  • Must specify the minimum and maximum number of Echo Buttons and the minimum number of players.

In the following example, the skill's detail page in the Alexa Skill Store will display Requires 2-4 Echo Buttons and Players: 2-4.

{
  "publishingInformation": {
    "gadgetSupport": {
      "requirement": "REQUIRED",
      "numPlayersMin": 2,
      "numPlayersMax": 4,
      "minGadgetButtons": 2,
      "maxGadgetButtons": 4     
    }
  },
  "apis": {
    "custom": {
      "interfaces": [
        {
          "type": "GAME_ENGINE"
        },
        {
          "type": "GADGET_CONTROLLER"
        }
      ]
    }
  }
}

Skills That Receive Echo Button Input But Do Not Control Echo Buttons

If you want your skill to receive Echo Button input but not control Echo Buttons, you:

  • Must specify the Game Engine as a supported interface.
  • Must specify whether Echo Buttons are required or optional.
  • Must specify the minimum and maximum number of Echo Buttons and the minimum number of players.

The following example is for a skill that needs to receive Echo Button input, does not need to animate the buttons. The skill's detail page in the Alexa Skill Store will display Requires 2-4 Echo Buttons and Players: 2-4.

{
  "publishingInformation": {
    "gadgetSupport": {
      "requirement": "REQUIRED",
      "numPlayersMin": 2,
      "numPlayersMax": 4,
      "minGadgetButtons": 2,
      "maxGadgetButtons": 4       
    }
  },
  "apis": {
    "custom": {
      "interfaces": [
        {
          "type": "GAME_ENGINE"
        }
      ]
    }
  }
}

Skills That Control Echo Buttons But Do Not Receive Echo Button Input

If you want your skill to control Echo Buttons but not receive input from them, you:

  • Must specify the Gadget Controller as a supported interface.
  • Must specify whether Echo Buttons are required or optional.

The following example is for a skill that can animate Echo Buttons, but cannot receive input from them.

{
  "publishingInformation": {
    "gadgetSupport": {
      "requirement": "REQUIRED"
    }
  },
  "apis": {
    "custom": {
      "interfaces": [
        {
           "type": "GADGET_CONTROLLER"
        }
      ]
    }
  }
}