Developer Console

Discovery Interface (VSK Fire TV)

When users first start using your app, Alexa sends a Discover directive through the Alexa.Discovery interface to determine what capabilities your video skill supports. Your response to the Discover directive determines what types of directives Alexa will send to your Lambda function.

For example, if you indicate support for channel changing, Alexa will send ChannelController directives when users say "Change the channel to PBS." But if you don't indicate this support, Alexa won't send the directive.

Discover Directives

Alexa sends a Discover directive after the user associates an Alexa skill with their Amazon account; after that, Alexa periodically sends Discover directives to update any discovered devices. When your Lambda function receives a Discover directive, you do not need to handle it.

Indicating Capabilities in Alexa Client Library

In Step 3: Integrate the Alexa Client Library, as you integrate the Alexa Client Library into your Android project, you must indicate the capabilities your app supports in the capabilities array:

// Create a list of supported capabilities in your skill.
List<String> capabilities = new ArrayList<>();
capabilities.add(AlexaClientManager.CAPABILITY_CHANNEL_CONTROLLER);
capabilities.add(AlexaClientManager.CAPABILITY_REMOTE_VIDEO_PLAYER);
capabilities.add(AlexaClientManager.CAPABILITY_PLAY_BACK_CONTROLLER);
capabilities.add(AlexaClientManager.CAPABILITY_SEEK_CONTROLLER);

Alexa will consult both this capabilities list in the Alexa Client Library as well as your Lambda function to determine which capabilities your app supports.

The capabilities are described below in the Capabilities Array section below. Although the names differ between the capabilities defined in the Alexa Client Library and the Lambda, they are mostly the same:

Client Library Capability Name Directive Capability Name
AlexaClientManager.CAPABILITY_CHANNEL_CONTROLLER Alexa.ChannelController
AlexaClientManager.CAPABILITY_REMOTE_VIDEO_PLAYER Alexa.RemoteVideoPlayer
AlexaClientManager.CAPABILITY_PLAY_BACK_CONTROLLER Alexa.PlaybackController
AlexaClientManager.CAPABILITY_SEEK_CONTROLLER Alexa.SeekController
AlexaClientManager.CAPABILITY_KEYPAD_CONTROLLER Alexa.KeypadController

Discover Directive Example

In addition to indicating capability support when you initialize the Alexa Client library, you must also indicate your video skill's capabilities in your Lambda function. See Step 6: Create and Deploy Lambda Package for details on creating the Lambda function.

The following is an example Discover directive that Alexa sends (and which your Lambda function must handle).

{
    "directive": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "46e09424-9c8a-4868-9db5-6c851e967b32",
            "name": "Discover",
            "namespace": "Alexa.Discovery",
            "payloadVersion": "3"
        },
        "payload": {
            "scope": {
                "token": "[User OAuth Token here]",
                "type": "BearerToken"
            }
        }
    }
}

Payload Description

The following table describes the payload fields.

Payload Descriptions
Field Description Data Type
scope
required
Scope of the request. Includes token and type properties. Object
token
required
An OAuth2 bearer token

Example: b68f05cc-6a25-4134

String
type
required
The type of the scope. The current supported value is BearerToken.

Example: BearerToken

Enum

Example Response

When your Lambda receives a Discover directive, your Lambda must send a Discover.Response back to indicate which capabilities your skill supports. You indicate your support in the capabilities array.

{
  "event": {
    "header": {
      "namespace":"Alexa.Discovery",
      "name":"Discover.Response",
      "payloadVersion":"3",
      "messageId":"2aa731f1-b6dd-471c-98fe-3ac5fa5d6554"
    },
    "payload": {
        "endpoints": [
            {
                "capabilities": [
                    {
                        "interface": "Alexa.RemoteVideoPlayer",
                        "type": "AlexaInterface",
                        "version": "1.0"
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.PlaybackController",
                        "version": "3",
                        "supportedOperations" : ["Play", "Pause", "Stop", "StartOver", "Next", "Previous", "Rewind", "FastForward"]
                    },
                    {
                        "interface": "Alexa.SeekController",
                        "type": "AlexaInterface",
                        "version": "1.0"
                    },
                    {
                        "interface": "Alexa.ChannelController",
                        "type": "AlexaInterface",
                        "version": "1.0"
                    },
                    {
                        "interface": "Alexa.KeypadController",
                        "type": "AlexaInterface",
                        "version": "3",
                        "keys": [
                          "INFO", "MORE", "SELECT",
                          "UP", "DOWN", "LEFT", "RIGHT",
                          "PAGE_UP", "PAGE_DOWN", "PAGE_LEFT", "PAGE_RIGHT"
                        ]
                    },
                    {
                        "interface": "Alexa.Launcher",
                        "type": "AlexaInterface",
                        "version": "3.1",
                        "configuration": {
                            "catalogs": [],
                            "targets": [
                            {
                                "name": "profile",
                                "identifier": "primevideo.PPCALkmhnlkChAFHNtGsxM95rZw="
                            }, 
                            {
                                "name": "settings",
                                "identifier": "primevideo.PPCALkmhnlkChAFHNtGsxM95rZw"
                            }, 
                            {
                                "name": "browse",
                                "identifier": "primevideo.Byb9lM7y5cjvtKF2q1i0samxtKc="
                            }, 
                            {
                                "name": "watchlist",
                                "identifier": "primevideo.OUlgBIlNyZkxB5+MPP+MPo/Yl5Y"
                            }, 
                            {
                                "name": "movies",
                                "identifier": "primevideo.zYYLxEVy5FSUC6oCrza6ly7FWLg"
                            }]
                        }
                    }
                ]
              }
          ]
       }
  }
};

Payload Description

The following table describes the payload object in your response.

Payload Descriptions
Field Description Data Type
endpoints
required
An array of endpoint objects that represents the devices associated with a customer’s device cloud account. Object
capabilities
required
The capability interfaces that your skill supports for the endpoint. See the Capabilities Object below for more detail. An array of capability objects
interface
required
The qualified name of the Alexa.Interface that describes the actions for the device.

Example: Alexa.RemoteVideoPlayer

String
type
required
The type of the scope. The current supported value is BearerToken.

Example: BearerToken

Enum
version
optional
Indicates the interface version that this endpoint supports.

Example: 1.0

String
cookie
optional
String name/value pairs that provide additional information about a device for use by the skill adapter. The contents of this property cannot exceed 5000 bytes. (Amazon doesn't use this field nor will customers see the value you put. However, you cannot enter the same value as your video skill name.)

Example: key1

Object
extraDetail
optional
Keys for the cookie object.

Example: key1

description
required
The description of the device. The description should might contain your company name or implementation. This value can contain up to 128 characters. (Amazon doesn't use this field nor will customers see the value you put. However, you cannot enter the same value as your video skill name.)

Example: Amazon Streaming Media App

String
endpointId
required
The identifier for the endpoint. For example, VSKTV. Note: You cannot enter the same value as your video skill name. It's also recommended that you preface the value with TEST_ or PROD_ to ensure that it's unique from your video skill name.

Example: TEST_VSKTV

String
friendlyName
required
This name identifies the type of implementation for the video skill. This value can contain up to 128 characters and should not contain special characters or punctuation. Note: Do not enter the same value as your video skill name. For example, if your video skill's name is "ACME Media," do not also enter "ACME Media" for the friendly name. Doing so will result in an error. Preface the name with something like "TEST_ACME_Media" or "PROD_ACME_Media".

Example: TEST_VSK_FTV

String
manufacturerName
required
The name of the manufacturer of the device. This value can contain up to 128 characters. (Amazon doesn't use this field nor will customers see the value you put. However, you cannot enter the same value as your video skill name.)

Example: Amazon

String

Capabilities Array

The capabilities array can have a list of objects that each contain an interface, type, version, and supportOperations properties. For example, an item in a capabilities array declaring support for playback capabilities might look as follows:

{
    "type": "AlexaInterface",
    "interface": "Alexa.PlaybackController",
    "version": "3",
    "supportedOperations" : ["Play", "Pause", "Stop", "StartOver", "Next", "Previous",
      "Rewind", "FastForward"]
}

The Alexa.PlaybackController interface is the only interface that includes a supportedOperations property.

The Alexa.KeypadController interface is the only interface that includes a keys property.

The following table describes the supported capabilities for video skills and the related directives:

Capability Description
Alexa.RemoteVideoPlayer Your skill can support directives from the RemoteVideoPlayer interface, including SearchAndPlay and SearchAndDisplayResults directives. These directives allow users to search and play video content. For example, "Search for Breaking Bad" or "Alexa, watch Breaking Bad."
Alexa.PlaybackController Your skill can support directives from the Alexa.PlaybackController interface, which is used to play, stop, and navigate playback for audio or video content. For example, "Alexa, fast forward" or "Alexa, stop." Note that the PlaybackController interface also allows a supportedOperations property as shown above. Allowed properties for supportedOperations are as follows: Play, Pause, Stop, StartOver, Next, Previous, Rewind, FastForward.
Alexa.SeekController Your skill can support directives from the Alexa.SeekController interface, which is used to allow the user to navigate to a specific position on the media timeline. For example, "Alexa, fast-forward 60 seconds" or "Alexa, skip back 5 minutes" (as opposed to "Alexa, fast-forward" or "Alexa, rewind"). (If your app can only fast-forward or rewind a media item, not seek to another point in the timeline, implement the PlaybackController interface instead.)
Alexa.ChannelController Your video skill can support directives from the Alexa.ChannelController interface, which is used to change or increment the channel for an entertainment device. For example, "Alexa, change the channel to PBS."
Alexa.KeypadController Your video skill can support directives from the Alexa.KeypadController Interface, which is used to scroll right or left, up or down, or select a widget in focus. For example, "Alexa, scroll right." Follow the code example above to list the keys that your video skill supports. key values include the following: UP, DOWN, LEFT, RIGHT, SELECT, PAGE_UP, PAGE_DOWN, PAGE_LEFT, PAGE_RIGHT, INFO, MORE. For more details, see Declaring Capabilities for KeypadController Interface below. Note that KeypadController requires Alexa Client Library version 1.4.5 or later.
Alexa.Launcher
Only for version 3.1 and above
Your video skill can support directives from the Alexa.Launcher 3.1+ interface, which can be used to navigate to any identifier/shortcut within your skill. For example, "Alexa, go to watchlist" (while your video skill/app is open). Follow the Example Response section to form the structure of your shortcut list.

Declaring Capabilities for KeypadController Interface

By default, Fire TV provides in-app scrolling and selection as described in In-App Voice Scrolling and Selection. If you don't indicate capability support for the KeypadController interface in your Alexa.Discovery response, the VSK falls back to the default in-app voice scrolling and selection functionality.

However, if you do indicate capability support for the KeypadController interface in your Discovery response, then the default in-app voice scrolling and selection functionality is turned off. The only scrolling and selection that will occur is through your response to the KeyStroke directives that your Lambda receives.

When you declare support for KeypadController, you list the keys that your video skill supports: UP, DOWN, LEFT, RIGHT, SELECT, PAGE_UP, PAGE_DOWN, PAGE_LEFT, PAGE_RIGHT, INFO, MORE. If you declare support for any key commands, Alexa assumes you are managing actions for all of the key commands. In short, you cannot declare support for some key commands but not others. As an example, if you don't declare UP, Alexa will still send keystroke payloads with UP values. The default in-app voice scrolling and selection won't kick in to compensate for the unsupported UP functionality.


Last updated: 6-15-2022