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 必需 |
请求范围。包括token 和type 属性。
|
对象 |
token 必需 |
OAuth2持有者令牌
示例: |
字符串 |
type 必需 |
范围的类型。当前支持的值是 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 的限定名称。
示例: |
字符串 |
type 必需 |
范围的类型。当前支持的值是 BearerToken 。
示例: |
枚举 |
version 可选 |
表示此终端节点支持的接口版本。
示例: |
字符串 |
cookie 可选 |
字符串名称/值对,提供有关设备的其他信息,供技能适配器使用。此属性的内容不能超过5000字节。(亚马逊不使用此字段,客户也不会看到您输入的值。但是,您输入的值不能与视频技能名称相同。)
示例: |
对象 |
extraDetail 可选 |
cookie 对象的密钥。
示例: |
|
description 必需 |
设备的描述。如果可能,描述应当包含您的公司名称或实现。此值最多可包含128个字符。(亚马逊不使用此字段,客户也不会看到您输入的值。但是,您输入的值不能与视频技能名称相同。)
示例: |
字符串 |
endpointId 必需 |
终端节点的标识符。例如,VSKTV 。注意: 您输入的值不能与视频技能名称相同。还建议您在该值前加上TEST_ 或PROD_ ,以确保它与您的视频技能名称不同。
示例: |
字符串 |
friendlyName 必需 |
此名称标识了视频技能的实现类型。此值最多可包含128个字符,不应包含特殊字符或标点符号。注意: 请勿输入与视频技能名称相同的值。例如,如果您的视频技能名称是“ACME Media”,则不要再输入“ACME Media”作为易记型名称。这样做会导致错误。在名称前加上“TEST_ACME_Media”或“PROD_ACME_Media”之类的内容。
示例: |
字符串 |
manufacturerName 必需 |
设备制造商的名称。此值最多可包含128个字符。(亚马逊不使用此字段,客户也不会看到您输入的值。但是,您输入的值不能与视频技能名称相同。)
示例: |
字符串 |
功能数组
capabilities
数组可以有一个对象列表,每个对象都包含一个interface
、type
、version
和supportOperations
属性。例如,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 接口的指令,包括SearchAndPlay 和SearchAndDisplayResults 指令。这些指令让用户可以搜索和播放视频内容。例如,“搜索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向右滚动)。 按照上面的代码示例列出您的视频技能支持的keys ,key 值包括以下值: UP 、DOWN 、LEFT 、RIGHT 、SELECT 、PAGE_UP 、PAGE_DOWN 、PAGE_LEFT 、PAGE_RIGHT 、INFO 、MORE 。有关更多详细信息,请参阅下面的声明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
时,您需要列出您的视频技能支持的keys
: UP
、DOWN
、LEFT
、RIGHT
、SELECT
、PAGE_UP
、PAGE_DOWN
、PAGE_LEFT
、PAGE_RIGHT
、INFO
、MORE
。如果您声明支持任何key
命令,Alexa会假设您正在管理所有key
命令的操作。简而言之,您不能声明支持某些key
命令,但不支持其他此类命令。例如,如果您不声明UP
,Alexa仍会发送带有UP
值的keystroke
有效负载。默认的应用内语音滚动和选择不会启动以补偿不支持的UP
功能。
Last updated: 2022年6月15日