开发者控制台
登录
登录
开发者控制台

Alexa.Launcher接口 (VSK Fire TV)

Alexa.Launcher接口 (VSK Fire TV)

在下拉导航中选择软件版本。

Alexa.Launcher版本3.1引入了自定义用户界面快捷方式。定义您的终端节点支持的语音快捷方式，让用户能够在您的用户界面中导航。您可以在检测响应中指定自定义用户界面快捷方式。

    有关Launcher接口支持的区域设置列表，请参阅List of Capability Interfaces and Supported Locales（仅提供英文版）。

    指令

    LaunchTarget指令

    这是导航到自定义快捷方式的请求。将把用户请求的快捷方式与合作伙伴提供的目标列表进行匹配。如果有匹配项，Alexa会将名称、标识符和sourceID发回给合作伙伴。

    用户： Alexa, go to <Custom Shortcut>（Alexa，前往<自定义快捷方式>）

    LaunchTarget指令示例

    {
    "directive": {
        "header": {
            "correlationToken": "不透明关联令牌",
            "messageId": "唯一标志符（推荐版本4UUID）",
            "name": "LaunchTarget",
            "namespace": "Alexa.Launcher",
            "payloadVersion": "3.1"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "some-access-token"
            },
            "endpointId": "endpoint id",
            "cookie": {}
        },
        "payload": {
            "name": "自定义快捷方式",
            "identifier": "partner.custom.shortcut.identifier",
            "sourceId": "DISCOVERY"
            }
        }
    }
}

    LaunchTarget指令参数

    属性 描述 类型 必需
    name 与标识符关联的名称。 字符串 是
    identifier 自定义快捷方式的标识符。 字符串 是
    sourceId 以唯一的方式标识目录。

    预定义目录的有效值： ALEXA_VIDEO_SHORTCUT_STORE, ALEXA_VIDEO_APP_STORE.
    自定义快捷方式的有效值： DISCOVERY.    		 字符串 是
    experience.mode 建议显示所请求结果的模式。VOICE_OPTIMIZED表示以语音为中心的结果，例如较简短的搜索结果列表。如果您不支持模式值，使用DEFAULT。

    有效值： DEFAULT, VOICE_OPTIMIZED    		 字符串 否

    LaunchTarget响应示例

    如果您成功处理了LaunchTarget指令，则使用Alexa.Response事件进行响应。在上下文对象中纳入target属性的值。

    复制到剪贴板。

    {
    "event": {
        "header": {
            "namespace": "Alexa",
            "name": "Response",
            "messageId": "唯一标志符（推荐版本4UUID）",
            "correlationToken": "与请求匹配的不透明关联令牌",
            "payloadVersion": "3"
        },
        "endpoint": {
            "endpointId": "endpoint id"
        },
        "payload": {}
    },
    "context": {
        "properties": [
            {
                "namespace": "Alexa.Launcher",
                "name": "target",
                "value": {
                    "name": "自定义快捷方式",
                    "identifier": "partner.custom.shortcut.identifier"
                },
                "timeOfSample": "2021-12-01T18:20:50Z",
                "uncertaintyInMilliseconds": 500
            },
            {
                "name": "connectivity",
                "value": {
                    "value": "OK"
                },
                "timeOfSample": "2021-12-01T18:20:50Z",
                "uncertaintyInMilliseconds": 0
            }
        ]
    }
}

    请参阅Alexa.Discovery响应示例，了解如何发送有效负载目标以启动应用和快捷方式。

    快捷方式名称要求

    • 不用在快捷方式中纳入过渡性措词，因为Alexa会处理它们。示例：使用“settings”而不是“go to settings”。下面列出了要从快捷方式名称中排除的过渡性措词的完整列表。

      • navigate to
      • go
      • go to
      • select
      • pick
      • choose
      • click
      • click on
      • hit
      • launch
      • take me/us to
      • open
      • show
      • show me/us
      • display
    • 定义快捷方式名称时全部使用小写。
    • 快捷方式名称应为字母数字。
    • “Home”是保留的表述，将始终默认设置为Fire TV主页。
    • 快捷方式名称的变化形式将不包括在内。如要让“go to movie”和“go to movies”起作用，您需要将“movie”和“movies”都作为指向相同标识符的快捷方式名称纳入。

    事件和属性

    可报告的属性

    属性名称 类型 描述
    target Target 启动的应用或快捷方式。

    配置对象

    除了常见的检测响应字段外，还可以为Alexa.Launcher纳入一个包含以下字段的配置对象。

    属性 描述 类型 必需
    catalogs 标识要导入的目录。
    仅纳入支持设备上所配置的语言的目录。如果您的终端节点不支持任何预定义的目录，则纳入一个空数组。
    最大值： 5个目录。
    有效值： ALEXA_VIDEO_SHORTCUT_STORE, ALEXA_VIDEO_APP_STORE.    		 Catalog对象数组 是
    targets 纳入您的终端节点支持的自定义用户界面快捷方式。
    如果您的技能定义了自定义快捷方式和预定义快捷方式目录，Alexa会先尝试在目标字段中找到匹配项，然后搜索预定义的快捷方式目录。
    如果您的终端节点不支持自定义快捷方式，则纳入一个空数组。
    最大值： 50个快捷方式。    		 Target对象数组 是

    Catalog对象

    Catalog对象定义终端节点支持的预定义目录。

    下表显示了Catalog对象的定义。

    属性 描述 类型 必需
    sourceId 以唯一的方式标识目录。
    如果您的终端节点支持预定义的应用目录，可设置为ALEXA_VIDEO_APP_STORE。如果您的终端节点支持预定义的用户界面快捷方式目录，可设置为ALEXA_VIDEO_SHORTCUT_STORE。有关预定义目录中的应用和简短目标，请参阅启动目标参考。     		字符串 是
    targets 纳入您的终端节点支持的自定义用户界面快捷方式。
    如果您的技能定义了自定义快捷方式和预定义快捷方式目录，Alexa会先尝试在目标字段中找到匹配项，然后搜索预定义的快捷方式目录。
    如果您的终端节点不支持自定义快捷方式，则纳入一个空数组。
    最大值： 50个快捷方式。    		 Target对象数组 是

    Target对象

    Target对象包含一个名称和标识符，代表您定义的自定义用户界面快捷方式。

    以下示例展示了自定义用户界面快捷方式目标。

    {
  "name": "target",
  "value": {
      "name": "Watchlist",
      "identifier": "custom.shortcut.id.0000"
    }
}

    下表展示了Target对象的定义。

    属性 描述 类型 必需
    name 自定义快捷方式的名称。
    自定义快捷方式名称只能包含字母数字字符。    		 字符串 是
    identifier 与快捷方式相关的自定义标识符。 字符串 是

    响应

    成功处理LaunchTarget指令后发送Response。

    响应示例

    以下示例显示了Response消息。在消息的上下文中报告target属性的值。

    复制到剪贴板。

    {
    "context": {
        "properties": [
            {
                "name": "target",
                "namespace": "Alexa.Launcher",
                "timeOfSample": "2017-05-06T16:20:50.52Z",
                "uncertaintyInMilliseconds": 0,
                "value": {
                     "name": "自定义快捷方式",
                     "identifier": "partner.custom.shortcut.identifier"
                }
            }
        ]
    },
    "event": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8pt90jSqg==",
            "messageId": "abc-123-def-456",
            "name": "Response",
            "namespace": "Alexa",
            "payloadVersion": "3"
        },
        "payload": {}
    }
}

    ErrorResponse

    如果您由于某种原因无法完成客户请求，则应以错误来回应。有关更多信息，请参阅错误处理文档。

    在Alexa.Launcher版本3.0中，第三方可以在其设备上启动目标。这对于启动该第三方的应用或快捷方式（例如设置）很有用。

      Alexa.Launcher接口会公开用于启动的指令：

      用于启动目标的指令包括预定义启动目标列表中的名称和标识符。您应该查看启动目标列表，并确保您的技能能够正确解析支持该技能功能的项目。

      有关Launcher接口支持的区域设置列表，请参阅List of Capability Interfaces and Supported Locales（仅提供英文版）。

      指令

      LaunchTarget

      请求启动指定的应用或快捷方式。用户命名的应用或快捷方式与预定义的启动目标列表中的标识符相匹配，并且名称和标识符在请求中发送。

      用户： Alexa, launch Prime Video（Alexa，启动Prime Video）

      示例： 启动Prime Video

      {
    "directive": {
        "endpoint": {
              "scope": {
                "type": "BearerToken",
                "token": "some-access-token"
              },
              "endpointId": "endpoint-001",
              "cookie": {}
            },
        },
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8pt90jSqg==",
            "messageId": "abc-123-def-456",
            "name": "LaunchTarget",
            "namespace": "Alexa.Launcher",
            "payloadVersion": "3"
        },
        "payload": {
            "identifier": "amzn1.alexa-ask-target.app.72095",
            "name": "Prime Video"
        }
    }
}

      有效负载详情

      属性 描述 类型 必需
      identifier 要启动的项目的标识符。应用标识符包含app，快捷方式标识符包含shortcut。有关标识符的完整列表，请参阅启动目标参考 字符串 是
      name 与标识符关联的名称。 字符串 是

      事件和属性

      可报告的属性

      属性名称 类型 描述
      target Target 启动的应用或快捷方式。

      响应

      成功处理LaunchTarget指令后发送Response。

      响应示例

      以下示例显示了Response消息。在消息的上下文中报告target属性的值。

      {
    "context": {
        "properties": [
            {
                "name": "target",
                "namespace": "Alexa.Launcher",
                "timeOfSample": "2017-05-06T16:20:50.52Z",
                "uncertaintyInMilliseconds": 0,
                "value": {
                    "identifier": "amzn1.alexa-ask-target.app.72095",
                    "name": "Prime Video"
                }
            }
        ]
    },
    "event": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8pt90jSqg==",
            "messageId": "abc-123-def-456",
            "name": "Response",
            "namespace": "Alexa",
            "payloadVersion": "3"
        },
        "payload": {}
    }
}

      ErrorResponse

      如果您由于某种原因无法完成客户请求，则应以错误来回应。有关更多信息，请参阅错误处理文档。

      Last updated: 2022年1月25日