步骤1：将您的应用程序与Fire TV启动器集成

实现通用搜索和浏览

→

为结合使用亚马逊Fire TV的启动器而修改您的应用器会将您的媒体内容和用户的订阅状态集成至亚马逊Fire TV用户界面中的其他内容。此流程也称为亚马逊Fire TV的内容“深层链接”至您的内容。在将您的应用程序集成至启动器后，用户即可在搜索您的内容时，从亚马逊的目录集成设备中发现并启动此内容。本页面描述了为集成目录至Fire TV启动器而必须做出的应用程序更改。

启动器集成概述
步骤A：通过应用程序广播包含其功能的意图
步骤B：接收由启动器发送的功能请求
步骤C：处理启动器发出的播放和登录意图
步骤D：添加错误处理代码，处理目录和可用内容之间发生的同步问题
步骤E：配置Android清单
步骤 F：测试您的启动器集成
适用于启动器集成的用户体验 (UX) 指南
启动器集成常见问题解答
后续步骤

启动器集成概述

当客户在Fire TV上启动应用程序时，它会向Fire TV启动器发送Android广播。广播中包含自有APK的类名（如com.contentcompany.player），其与深层链接结合使用。当客户启动您应用程序的内容时，Fire TV会启动广播所指示的类，并根据目录配置，在服务的LaunchId中为内容传递此类别。

除了在广播中添加类名外，您还可以发送应当由启动器引用的相关类的其他元数据。您可以在广播中添加以下意图：

登录意图
播放意图

除了发送广播意图外，您的应用程序还必须执行以下操作，才能与Fire TV启动器进行集成：

接收由启动器发送的功能请求，并在包含应用程序功能的广播意图中使用相同信息进行响应。
处理启动器发送的播放或登录请求。
解决在处理目录和可用内容之间的同步问题时出现的错误。
在Android清单中提供必要的筛选条件、接收条件和权限。

以下各节列出了每项任务的详细信息。

请注意，您的应用程序仍负责：

播放和登录活动和行为。
管理用户的服务订阅状态。

步骤A：通过应用程序广播包含其功能的意图

要播放您的内容，Fire TV启动器就要用到应用程序的用户信息，以便稍后播放您的内容或发送用户登录服务的请求。您的应用程序必须在以下情况下发送此信息，作为Android广播意图：

每次启动您的应用程序时。
应用程序请求此操作时（请参阅步骤B：接收由启动器发送的功能请求）。
用户的订阅状态更改时，例如用户登录或退出您的服务。
用户购买、续订或升级订阅时。

要集成Fire TV启动器并进行深层链接，请创建两种不同类型的Android意图，用于应用程序广播：

意图	描述
登录意图	如果当前用户未登录应用程序，则广播登录意图。
播放意图	如果当前用户已经登录应用程序，如当用户刚刚登录或激活应用程序时，则广播播放意图。

使用这两种意图类型可向亚马逊Fire TV传达您的应用程序功能。

构建并发送意图

要广播应用程序功能，请构建Android标准意图，然后使用sendBroadcast()方法，将其发送到应用程序环境。在构造意图时：

将意图程序包命名为com.amazon.tv.launcher。
对com.amazon.device.CAPABILITIES设置意图操作。
指定其他所有意图信息为意图附加信息。

以下示例介绍了broadcastCapabilities()示例方法，其基于布尔值userIsSignedIn变量广播各种意图附加信息。此示例中的所有值均为示例数据，必须替换为您自己的值。

public void broadcastCapabilities(Context context)
{
    final Intent intent = new Intent();
    intent.setPackage("com.amazon.tv.launcher");
    intent.setAction("com.amazon.device.CAPABILITIES");
    if (userIsSignedIn) {
        // 播放意图附加信息
        intent.putExtra("amazon.intent.extra.PLAY_INTENT_ACTION","android.intent.action.VIEW");
        intent.putExtra("amazon.intent.extra.PLAY_INTENT_PACKAGE","com.contentcompany.player");
        intent.putExtra("amazon.intent.extra.PLAY_INTENT_CLASS","com.contentcompany.player.PlayActivity");
        intent.putExtra("amazon.intent.extra.PLAY_INTENT_FLAGS", Intent.FLAG_ACTIVITY_NEW_TASK | Intent.MORE_FLAGS);
    } else {
        // 登录意图附加信息
        intent.putExtra("amazon.intent.extra.SIGNIN_INTENT_ACTION","android.intent.action.VIEW");
        intent.putExtra("amazon.intent.extra.SIGNIN_INTENT_PACKAGE","com.contentcompany.player");
        intent.putExtra("amazon.intent.extra.SIGNIN_INTENT_CLASS","com.contentcompany.player.SignInActivity");
        intent.putExtra("amazon.intent.extra.SIGNIN_INTENT_FLAGS", Intent.FLAG_ACTIVITY_NEW_TASK | Intent.MORE_FLAGS);
    }
    
    intent.putExtra("amazon.intent.extra.DATA_EXTRA_NAME", "contentId");
    intent.putExtra("amazon.intent.extra.PARTNER_ID","contentcompany");

    // 向启动器发送广播
    context.sendBroadcast(intent);
}

意图附加信息

使用Intent.putExtra()方法，在附加信息字段的键和值中指定应用程序功能。所有意图附加信息都含有前缀程序包amazon.intent.extra。

下表显示了必填的意图附加信息和专门用于播放和登录的附加内容。所有意图附加值的前缀都是amazon.intent.extra。

意图附加信息	使用情况	描述
`PARTNER_ID`	随时可用	您的合作伙伴ID（由亚马逊提供）与CDF文件的“合作伙伴”字段中用于目录集成的ID相同。请注意，此ID仅属于您的应用程序，而不属于个体或组织。如果您或您的组织拥有多款Fire TV应用程序，则每一款应用程序都会有专属的合作伙伴ID。
`DATA_EXTRA_NAME`	有条件	含有数据内容ID的附加信息标题，如`titleData`。只有当URI未用于描述您的内容ID时，才能指定此值。如果内容ID的格式不是URI（如`123456`），则使用`DATA_EXTRA_NAME`指明启动器应该用于此ID的意图附加信息名称。有关更多信息，请参阅步骤C：处理启动器发出的播放和登录意图。使用`Intent.getStringExtra()`方法，访问该内容ID。
`PLAY_INTENT_ACTION`	如果用户已登录	对于播放意图，启动器通常会发送`android.intent.action.VIEW`的意图操作。
`PLAY_INTENT_PACKAGE`	如果用户已登录	对于播放意图，适用于应用程序的程序包，如`com.contentcompany.player`。
`PLAY_INTENT_CLASS`	如果用户已登录	对于播放意图，适用于应用程序的完整程序包和类名，如`com.contentcompany.player.PlayActivity`。
`PLAY_INTENT_FLAGS`	如果用户已登录	对于播放意图，以整数形式表示应用程序需要从意图中获取的任何标记。有关可能的标记值，请参阅Android参考指南中的`意图`。
`SIGNIN_INTENT_ACTION`	如果用户已注销	对于登录意图，启动器会发送的意图操作，通常为`android.intent.action.VIEW`。
`SIGNIN_INTENT_PACKAGE`	如果用户已注销	对于登录意图，适用于应用程序的程序包，如`com.contentcompany.player`。
`SIGNIN_INTENT_CLASS`	如果用户已注销	对于登录意图，应用程序的类名，如`SignInActivity`。
`SIGNIN_INTENT_FLAGS`	如果用户已注销	对于登录意图，以整数形式表示应用程序需要从意图中获取的任何标记。有关可能的标记值，请参阅Android参考指南中的`意图`。

始终要提供一条必填附加信息：

由亚马逊提供的合作伙伴ID (PARTNER_ID)。此ID与您当进行目录集成时所需的ID相同。

其余的意图附加信息会有所不同，具体取决于用户是否有权播放您的内容（在已登录情况下），或用户是否需要登录才能继续操作。

如果用户已登录，则需要带有PLAY_前缀的附加信息。
如果用户未登录，则需要带有SIGNIN_前缀的附加信息。

示例

例如，在用户登录或激活您的应用程序时，发送包含以下附加信息的意图：

PARTNER_ID
PLAY_INTENT_ACTION
PLAY_INTENT_PACKAGE
PLAY_INTENT_CLASS
PLAY_INTENT_FLAGS

在用户未登录的另一个示例中，如果启动器请求使用应用程序的功能，则发送包含以下附加信息的意图：

PARTNER_ID
SIGNIN_INTENT_ACTION
SIGNIN_INTENT_PACKAGE
SIGNIN_INTENT_CLASS
SIGNIN_INTENT_FLAGS

请勿同时提供两组意图附加信息，因为启动器认为存在PLAY_密钥即表示用户有权查看您的内容。

步骤B：接收由启动器发送的功能请求

亚马逊Fire TV启动器偶尔会请求使用应用程序功能和查看用户订阅状态。启动器会执行com.amazon.device.REQUEST_CAPABILITIES操作，通过Android广播意图请求这些信息。您的应用程序在响应此请求时必须使用与之前在步骤A：通过应用程序广播包含其功能的意图中创建的意图相同的意图。

注意： 不要等到启动器发出请求。如步骤A：通过应用程序广播包含其功能的意图中所述，在每次启动应用程序时以及在用户订阅状态更改时，您都必须发送应用程序的功能信息。

以下示例显示了一个处理启动器广播意图的简单类。发送到启动器的能力信息与在步骤A：通过应用程序广播包含其功能的意图中发送的信息一致，以便使用相同方法（这里是指broadcastCapabilities()）管理这两项任务。

public class CapabilityRequestReceiver extends BroadcastReceiver
{
   @Override public void onReceive(Context context, Intent intent)
   {
      broadcastCapabilities(); // 用于向启动器广播应用程序信息的方法
   }
}

步骤C：处理启动器发出的播放和登录意图

当用户在Fire TV用户界面中查看您的内容详情时，Fire TV会根据用户使用服务的状态显示不同的选项：

如果用户已登录服务（您在功能广播中提供的PLAY_意图附加信息），则会出现一个标有应用程序显示名称的按钮（如MyCompany Player）。如果用户按下此按钮，则启动器会向您的应用程序发出播放意图。
如果用户未登录服务（您提供的SIGNIN_意图附加信息），则会出现一个标有应用程序显示名称的Launch（启动）按钮（如Launch MyCompany Player）。如果用户按下此按钮，则启动器会向您的应用程序发出登录意图。

在这两种情况下，启动器都会使用您在功能广播中提供的信息来构建要发送到应用程序的播放和登录意图。

要处理播放或登录意图，请在您的应用程序中实施活动，以接收和处理这些意图，并播放请求内容。

注意： 在处理这些意图时，您的应用程序必须立即开始播放（或在用户登录后立即开始播放）。请勿在应用程序中显示其他详情页面或其他类型的登录页面。

以下代码显示了播放活动的框架：

public class PlayActivity extends Activity {
   @Override
   public void onCreate(Bundle bundle) {
      super.onCreate(bundle);
      Uri data = getIntent().getData();
      // 播放‘数据’指定的内容
      //或
      String data = getIntent.getStringExtra("titleExtra");
      // 播放您在DATA_EXTRA_NAME中指明的附加信息特定内容
   }
}

播放意图和登录意图均包含所请求内容的ID，以便您的应用程序能够立即播放此内容（播放意图）或在用户登录（登录意图）后播放此内容。您可以在媒体目录中指定该ID及其格式，这也是目录集成的操作内容。

如果内容ID的格式不是URI（如123456），则启动器会以您在DATA_EXTRA_NAME中指定的附加信息中发送此ID，作为功能广播的内容。您可以使用Intent.getStringExtra()方法，访问该内容ID。

注意： 启动器仅发送您在CDF目录中指定的数据。请确保您在目录中指定的ID与应用程序预期的播放格式相同，或者采用应用程序可用的格式。如需向应用程序发送URI格式的数据，您也可以使用LaunchDetails。

如果用户连续按下“后退”按钮（从媒体播放场景开始算起，则通常是按3次），则应用程序最终应将用户返回到他们上一次进入应用程序的位置。在这种情况下，提供启动器中的搜索结果。

步骤D：添加错误处理代码，处理目录和可用内容之间发生的同步问题

目录偶尔与可用的实际内容不同步，这是很多集成了Fire TV的应用程序所面临的常见问题。如果用户通过搜索或浏览选择内容项，但此内容其实无法播放，则用户将遇到黑屏，也找不到导航方法。这可能会破坏用户体验，还会对通过Fire TV访问您应用程序的方式造成负面影响。

此同步问题可能是由以下几个原因导致的：

在实际内容得以播放前的数小时内，视窗成功引入了刚刚上传的新目录。
部分内容已经轮换，但用于反映此变化的更新目录尚未上传/引入。

亚马逊建议您在应用程序中实施错误处理代码，以免用户在选到不可用内容后遇到黑屏。此代码应能够解决以下用例：用户试图选择不可用内容、系统向用户提供有意义的错误消息，以及将用户重定向到合适位置。客户应该更容易接受这种正常故障导致的用户体验。

步骤E：配置Android清单

配置Android清单，处理启动器发出的广播意图。具体需要添加三项内容：

添加意图筛选条件，以处理播放和登录意图。
为启动器的功能添加接收条件，以请求意图。
添加权限，以使用正确权限发送您的意图。

注意： 在清单中声明广播是Fire TV检测应用程序成功启用目录集成的必要条件。

为您的播放和登录活动添加意图筛选条件，以便接收启动器发出的意图。此示例使用了PlayActivity播放活动：

<activity
    android:name=".PlayActivity"
    android:label="Playback Activity">
    ...
    <intent-filter>
        <action android:name="com.contentcompany.player.PlayActivity">
        <category android:name="android.intent.category.DEFAULT">
    </intent-filter>
</activity>

为启动器请求添加接收条件

使用BroadcastReceiver类的名称为清单添加接收条件元素，然后为com.amazon.device.REQUEST_CAPABILITIES操作添加intent-filter。在此示例中，接收条件类为CapabilityRequestReceiver：

<receiver android:name="CapabilityRequestReceiver" >
    <intent-filter>
    <action android:name="com.amazon.device.REQUEST_CAPABILITIES" />
    </intent-filter>
</receiver>

添加权限

在清单中添加uses-permission元素，确保启动器能够接收您的意图：

<uses-permission android:name="com.amazon.device.permission.COMRADE_CAPABILITIES" />

步骤 F：测试您的启动器集成

将应用程序与Fire TV启动器集成后，您需要先验证启动器集成，然后再向亚马逊应用商店提交应用器：

请参阅步骤2：从目录验证深层链接，以了解在提交应用程序前运行的一系列测试用例。

适用于启动器集成的用户体验 (UX) 指南

在与启动器集成时，请记住以下用户体验：

当用户根据Fire TV的通用搜索和浏览结果从您的应用程序中选择内容时，请立即开始播放此内容。在此之前，请勿将客户引导至应用程序或作品的详情画面。
作为启动器集成操作的一环，请确保在每次打开应用程序时都发布了用户订阅状态，这样，在应用程序外部找到您内容的当前订阅用户就能看到Watch Now（立即观看）选项。
如果当前可用目录与用户实际看到的内容不同步，则执行错误处理代码，正常解决用户选到了无法播放的内容项的用例。如未针对此情况执行错误处理代码，用户会遇到黑屏、找不到导航回Fire TV、应用程序或目录的方法，会心生困惑和不满。

启动器集成常见问题解答

问：当用户通过浏览或搜索选择剧集或连续剧时，应该从哪里开始播放？: 答：为保证良好的用户体验，应该通过深层链接，直接从浏览或搜索结果中播放剧集或连续剧。不应将用户引导到应用程序的主屏幕或其他任何位置。
问：用户选择剧集或连续剧时，应该如何立即开始播放？: 答：播放时间可能因应用程序而异，具体取决于缓冲等因素；但应在用户选中内容后直接开始播放，无需任何中间步骤。在开始播放前，不应将用户重定向到应用程序的主屏幕或其他位置。
问：播放完成后，用户应该登录哪里？: 答：如果用户已经通过您的应用程序而不是通过集成目录访问了内容，则用户应该登录其预期的位置。某些应用程序会自动开始播放下一集。其他应用程序则会引导用户到个人推荐。无论是通过Fire TV还是您的应用程序提供内容，都要一如既往地保持优质的用户体验。

后续步骤

完成启动器集成后，转到下一步：步骤2：从目录验证深层链接。

Last updated: 2024年2月23日

步骤1： 将您的应用程序与Fire TV启动器集成

实现通用搜索和浏览

启动器集成概述

步骤A： 通过应用程序广播包含其功能的意图

意图类型：播放和登录意图