Discovery Interface (VSK Fire TV)

Warning: Video Skills Kit (VSK) is no longer supported. For questions about existing integrations, please contact your Amazon technical account manager.

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.

Note: Discovery directives are used with Cloudside integrations only. App-only integrations relay the same information but in a different way. See Supported Capabilitiesfor details.

Discover Directives
Indicating Capabilities in Alexa Client Library
Discover Directive Example
Payload Description
Example Response
Payload Description
Capabilities Array
Declaring Capabilities for KeypadController Interface

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 in the following Capabilities Array section. 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`

Note: Declaring capabilities is still valid, but can only be used for those capabilities not requiring configuration. If configuration is required, use the granular capability builder interface. This is located in the Alexa Client Library (cloudside integration only) package, which also includes documentation with more details.

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. 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 previous code example 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. Note that `KeypadController` requires Alexa Client Library version 1.4.5 or later.
`Alexa.Launcher` Only for version 3.1 and higher	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