开发者控制台

Discovery接口 (VSK Fire TV)

Discovery接口 (VSK Fire TV)

当用户首次开始使用您的应用时,Alexa会通过Alexa.Discovery接口发送Discover指令,以确定您的视频技能支持哪些功能。您对Discover指令的响应决定了Alexa将向您的Lambda函数发送哪些类型的指令。

例如,如果您指明支持频道更改,则当用户说出“将频道更改为PBS”时,Alexa将发送ChannelController指令。 但是,如果您不指明此项支持,Alexa不会发送指令。

Discover指令

在用户将Alexa技能与其亚马逊账户关联后,Alexa会发送Discover指令;之后,Alexa会定期发送Discover指令以更新任何发现的设备。当您的Lambda函数收到Discover指令时,您无需对其进行处理。

指明Alexa客户端库中的功能

步骤3: 集成Alexa客户端库中,当您将Alexa客户端库集成到Android项目中时,必须在capabilities数组中指明您的应用支持的功能:

// 创建技能中支持的功能的列表。
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将同时查询Alexa客户端库中的这个capabilities列表以及您的Lambda函数,以确定您的应用支持哪些功能。

下文的功能数组部分对这些功能进行了描述。尽管Alexa客户端库和Lambda中定义的功能之间的名称不同,但它们本质大致相同:

客户库功能名称 指令功能名称
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指令示例

除了在初始化Alexa客户端库时指明功能支持外,您还必须在Lambda函数中指明您的视频技能功能。有关创建Lambda函数的详细信息,请参阅步骤6: 创建和部署Lambda程序包

以下是Alexa发送的Discover指令示例(您的Lambda函数必须处理该指令)。

{
    "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字段。

有效负载描述
字段 描述 数据类型
scope
必需
请求范围。包括tokentype属性。 对象
token
必需
OAuth2持有者令牌

示例:b68f05cc-6a25-4134

字符串
type
必需
范围的类型。当前支持的值是 BearerToken

示例: BearerToken

枚举

响应示例

当您的Lambda收到Discover指令时,您的Lambda必须发回Discover.Response以指明您的技能支持哪些功能。您在capabilities数组中指明此类支持。

{
  "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对象。

有效负载描述
字段 描述 数据类型
endpoints
必需
一组终端节点对象,代表与客户的设备云账户关联的设备。 对象
capabilities
必需
您的技能对终端节点支持的功能接口。有关更多详细信息,请参阅下面的功能对象 功能对象数组
interface
必需
描述设备操作的Alexa.Interface的限定名称。

示例: Alexa.RemoteVideoPlayer

字符串
type
必需
范围的类型。当前支持的值是 BearerToken

示例: BearerToken

枚举
version
可选
表示此终端节点支持的接口版本。

示例: 1.0

字符串
cookie
可选
字符串名称/值对,提供有关设备的其他信息,供技能适配器使用。此属性的内容不能超过5000字节。(亚马逊不使用此字段,客户也不会看到您输入的值。但是,您输入的值不能与视频技能名称相同。)

示例:key1

对象
extraDetail
可选
cookie对象的密钥。

示例:key1

description
必需
设备的描述。如果可能,描述应当包含您的公司名称或实现。此值最多可包含128个字符。(亚马逊不使用此字段,客户也不会看到您输入的值。但是,您输入的值不能与视频技能名称相同。)

示例: 亚马逊流媒体应用

字符串
endpointId
必需
终端节点的标识符。例如,VSKTV注意:​ 您输入的值不能与视频技能名称相同。还建议您在该值前加上TEST_PROD_,以确保它与您的视频技能名称不同。

示例: TEST_VSKTV

字符串
friendlyName
必需
此名称标识了视频技能的实现类型。此值最多可包含128个字符,不应包含特殊字符或标点符号。注意:​ 请勿输入与视频技能名称相同的值。例如,如果您的视频技能名称是“ACME Media”,则不要再输入“ACME Media”作为易记型名称。这样做会导致错误。在名称前加上“TEST_ACME_Media”或“PROD_ACME_Media”之类的内容。

示例: TEST_VSK_FTV

字符串
manufacturerName
必需
设备制造商的名称。此值最多可包含128个字符。(亚马逊不使用此字段,客户也不会看到您输入的值。但是,您输入的值不能与视频技能名称相同。)

示例: Amazon

字符串

功能数组

capabilities数组可以有一个对象列表,每个对象都包含一个interfacetypeversionsupportOperations属性。例如,capabilities数组中声明支持播放功能的项目可能如下所示:

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

Alexa.PlaybackController接口是包含supportedOperations属性的唯一接口。

Alexa.KeypadController接口是包含keys属性的唯一接口。

下表描述了支持的视频技能功能和相关指令:

功能 描述
Alexa.RemoteVideoPlayer 您的技能可以支持来自RemoteVideoPlayer接口的指令,包括SearchAndPlaySearchAndDisplayResults指令。这些指令让用户可以搜索和播放视频内容。例如,“搜索Breaking Bad”或“Alexa,观看Breaking Bad”。
Alexa.PlaybackController 您的技能可以支持来自Alexa.PlaybackController接口的指令,这些指令用于音频或视频内容的播放、停止和导航播放。例如 “Alexa, fast forward”(Alexa,快进)或 “Alexa, stop”(Alexa,停止)。 请注意,PlaybackController接口还允许supportedOperations属性,如上所示。对supportedOperations允许的属性如下: Play, Pause, Stop, StartOver, Next, Previous, Rewind, FastForward.
Alexa.SeekController 您的技能可以支持来自Alexa.SeekController接口的指令,该接口用于允许用户导航到媒体时间线上的特定位置。例如,“Alexa, fast-forward 60 seconds”(Alexa快进60秒)或 “Alexa, skip back 5 minutes”(Alexa,后退5分钟),而不是“Alexa, fast-forward”(Alexa,快进)或 “Alexa, rewind”(Alexa,倒回)。(如果您的应用只能快进或倒回媒体项目,而不能搜索到时间线上的另一个点,请改为实现PlaybackController接口。)
Alexa.ChannelController 您的视频技能可以支持来自Alexa.ChannelController接口的指令,该接口用于更改或增加娱乐设备的频道。例如,“Alexa, change the channel to PBS”(Alexa,将频道更改为PBS)。
Alexa.KeypadController 您的视频技能可以支持来自Alexa.KeypadController接口的指令,该接口用于向右或向左、向上或向下滚动,或选择聚焦的小组件。例如 "Alexa, scroll right"(Alexa向右滚动)。 按照上面的代码示例列出您的视频技能支持的keyskey值包括以下值: UPDOWNLEFTRIGHTSELECTPAGE_UPPAGE_DOWNPAGE_LEFTPAGE_RIGHTINFOMORE。有关更多详细信息,请参阅下面的声明KeypadController接口的功能。请注意,KeypadController需要Alexa客户端库版本1.4.5或更高版本。
Alexa.Launcher
仅适用于3.1及更高版本
您的视频技能可以支持来自Alexa.Launcher 3.1+接口的指令,这些指令可用于导航到技能中的任何标识符/快捷方式。例如,“Alexa,转到观看列表”(当您的视频技能/应用处于打开状态时)。按照示例响应部分来形成快捷方式列表的结构。

声明KeypadController接口的功能

默认情况下,Fire TV提供应用内滚动和选择,如应用内语音滚动和选择中所述。如果您没有在Alexa.Discovery响应中指明支持KeypadController接口功能,VSK会回退到默认的应用内语音滚动和选择功能。

但是,如果您在Discovery响应中明确指明支持KeypadController接口功能,则默认的应用内语音滚动和选择功能将关闭。滚动和选择只会通过您对Lambda收到的KeyStroke指令的响应而发生。

当您声明支持KeypadController时,您需要列出您的视频技能支持的keysUPDOWNLEFTRIGHTSELECTPAGE_UPPAGE_DOWNPAGE_LEFTPAGE_RIGHTINFOMORE。如果您声明支持任何key命令,Alexa会假设您正在管理所有key命令的操作。简而言之,您不能声明支持某些key命令,但不支持其他此类命令。例如,如果您不声明UP,Alexa仍会发送带有UP值的keystroke有效负载。默认的应用内语音滚动和选择不会启动以补偿不支持的UP功能。


Last updated: 2022年6月15日