内容启动器集成指南

本文档介绍如何将内容启动器集成到您的应用中。媒体应用通常需要与以下三个关键API集成：

• 内容启动器API
• Vega媒体控制API
• 账户登录API

系统以交互式组件的形式实现内容启动器API和Vega媒体控制API，该组件是处理Vega媒体查询的主要组件。账户登录API用作服务组件。

有关如何添加正确的依赖项和更新清单的详细信息，请参阅API自述文件的 @amazon-devices/kepler-media-content-launcher。

Vega媒体内容启动器常见用例

要开始使用Vega媒体内容启动器API，请按照以下步骤操作。

• 实例化一个新的ContentLauncherServerComponent。开发一个用于封装回调函数的处理程序对象。此函数应返回Promise到使用ContentLauncherServerComponent实例创建的ILauncherResponse。搜索参数的检索方式详见本指南的后续内容。回调函数应：
  • 处理内容启动请求。
  • 在LauncherResponse中设置相应状态：
    • 如果请求处理成功，请见ContentLauncherStatusType.SUCCESS。
    • 如果因授权问题导致无法处理，请见ContentLauncherStatusType.AUTH_FAILED。
    • ContentLauncherStatusType.URL_NOT_AVAILABLE适用于其他所有场景。

实现内容启动器API

1. 定义内容启动器处理程序。

   实例化一个新的ContentLauncherServerComponent。开发一个用于封装回调函数的处理程序对象。

   复制代码 已复制到剪贴板。

    import {
      ILauncherResponse,
      IContentLauncherHandler,
      ContentLauncherStatusType,
      ContentLauncherServerComponent,
      IContentSearch,
      ILaunchContentOptionalFields,
    } from '@amazon-devices/kepler-media-content-launcher';
   
    ...
    // 创建一个ContentLauncherServerComponent的实例。
    const factory = new ContentLauncherServerComponent();
   
    // 创建一个在请求启动内容时调用的处理程序。
    const contentLauncherHandler: IContentLauncherHandler = {
        async handleLaunchContent(
          contentSearch: IContentSearch,
          autoPlay: boolean,
          optionalFields: ILaunchContentOptionalFields,
        ): Promise<ILauncherResponse> {
            console.log('Content_Launcher_Sample: handleLaunchContent invoked');
   
            // 在此处迭代以获取数据。
            // 添加业务逻辑以处理启动请求。
   
            const launcherResponse = factory
                .makeLauncherResponseBuilder()
                .contentLauncherStatus(ContentLauncherStatusType.SUCCESS)
                .build();
            return Promise.resolve(launcherResponse);
        },
    };
   

   处理程序应处理请求，向ILauncherResponse返回Promise，然后使用ContentLauncherServerComponent的实例进行创建。

   对于LauncherResponse，如果您的应用成功处理了请求，请将contentLauncherStatus状态设置为ContentLauncherStatusType.SUCCESS。如果您的应用由于授权问题而无法处理请求，请将状态设置为ContentLauncherStatusType.AUTH_FAILED。对于其他所有情况，请将状态设置为ContentLauncherStatusType.URL_NOT_AVAILABLE。

2. 在交互式应用中实现Vega媒体内容启动器。

   1. 获取IContentLauncherServerAsync的单例实例。针对ContentLauncherServerComponent实例使用getOrMakeServer方法，以实现IContentLauncherServerAsync。
   2. 创建一个用于实现IContentLauncherHandler接口的处理程序对象，以处理内容启动请求。
   3. 为'IContentLauncherServerAsync'实例调用'setHandlerForComponent'方法。这样就能将处理程序与正确的组件相关联。
   4. 传递处理程序和相应的IComponentInstance。

在交互式应用中，您可以使用useComponentInstance方法获取IComponentInstance。对于React Native应用，请使用useEffect挂钩设置处理程序。在组件完成挂载和IComponentInstance变得可用之后，处理程序便应该立即对内容启动器进行初始化。这将把Content Launcher功能集成到组件的生命周期中，从而使您的应用能够处理Vega内容启动器命令。此设置对于含有多个组件的应用非常重要，让每个组件都能使用IComponentInstance，从而防止回调路由发生混淆。

复制代码 已复制到剪贴板。

实现详情

handleLaunchContent回调函数采用三个参数：

1. 实现IContentSearch接口的对象。
2. 名为autoPlay的布尔值。
3. 其他字段，作为实现ILaunchContentOptionalFields接口的对象进行传递。

IContentLauncherHandler处理程序采用一个参数来定义要播放的内容或显示搜索结果。

根据autoPlay确定操作

autoPlay参数为处理程序的行为提供指引：

• 当autoPlay设置为true时： 这表示有快速播放请求。应立即开始播放指定内容，无需用户进一步交互。
• 当autoPlay设置为false时： 在此情况下，处理程序应向用户展示搜索结果，而非启动播放。这样一来，用户便可查看可用选项并从中进行选择。

利用这些参数，尤其是autoPlay，IContentLauncherHandler可有效管理内容探索与播放。

检索搜索值

IContentSearch参数包含待搜索的内容信息。以下架构适用于存储在IContentSearch中的值。

复制代码 已复制到剪贴板。

• parameterList有一个或多个条目。contentSearch.getParameterList().length返回参数的数量。使用getParameterList()检索完整列表。（架构中的第1行）
• 表示参数中列出的实体的类型。例如，如果是电影或电视节目，则"type"是`ContentSearchParamType::VIDEO`。有关支持值的完整列表，请参阅`ContentSearchParamType`枚举。调用`getParamType()`来获取类型。（架构中的第1.1行）
• 表示类型中提及的实体的值。调用`getValue()`来检索此字段。（架构中的第1.2行）每个参数都有零个或多个`externalIds`。使用`getExternalIdList()`.length获取列表大小。`getExternalIdList()`返回完整列表。（架构中的第1.3行）
• <externalId name>通过getName()来检索。可识别的两个名称为： （架构中的第1.3.1行）amzn_id—所请求内容的目录ID。launch_url—由外部体验（如Matter投屏）提供的深层链接字符串，可直接用于启动播放。
• <externalId值>表示externalId的值。要检索该值，可使用getValue()。对于amzn_id，此值与您在目录集成中使用的<ID>或<launchId>一致。对于launch_url，此值是请求方体验提供的完整深层链接。
  注意： externalId值可能包含catalogContentId或<catalog id>，两者的值都与amzn_id的值相同。但catalogContentId和<catalog id>元素将弃用，因此请仅使用amzn_id。

内容启动器请求示例

以下示例解释了一些重要内容启动器用例的contentSearch参数值。此示例列出了所有支持的用例。对于每个用例，都会调用内容启动器并启动应用。

以下streamz_us的示例目录包括电影Seabound和电视节目The SeaShow: The Real Story的示例条目。

复制代码 已复制到剪贴板。

通过遥控器启动内容

使用遥控器在Vega TV主屏幕上启动电影Seabound。

复制代码 已复制到剪贴板。

应用应对LaunchId使用tv.streamz/movie/46720000来识别电影，然后直接播放电影。

用语音快速播放

通过语音播放电影Seabound。使用表述“Alexa, Play Seabound”（Alexa，播放Seabound）。

此处的autoPlay为true。以下示例包含了contentSearch: IContentSearch值。应用会启动，并且应该使用ID 1700000725直接播放内容。

复制代码 已复制到剪贴板。

用语音播放特定剧集

以下目录示例代表电视节目SeaShow: The Real story、该电视节目的季以及剧集。通过使用Alexa表述“Alexa, Play Season 2 Episode 5 from The SeaShow: The Real story”（Alexa，播放The SeaShow: The Real story的第2季第5集），可以调用应用以播放特定剧集。

此处的autoPlay为true。contentSearch包含节目ID，而不是剧集ID。应用必须使用ID 1700000123、ContentSearchParamType::SEASON以及ContentSearchParamType::EPISODE值来识别确切的剧集。

复制代码 已复制到剪贴板。

示例： 使用Alexa启动剧集

以下示例通过以下Alexa语音表述启动一个剧集： "Watch The SeaShow: The Real Story season two episode five in Streamz."（在Streamz中观看The SeaShow: The Real story第2季第5集）。

复制代码 已复制到剪贴板。

---

Last updated: 2026年6月18日