步骤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。

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

• 由亚马逊提供的合作伙伴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： 通过应用广播包含其功能的意图中发送的信息一致，以便使用相同方法（这里是指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。

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

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

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

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

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

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

步骤E： 配置Android清单

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

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

为播放和登录添加意图筛选条件

为您的播放和登录活动添加意图筛选条件，以便接收启动器发出的意图。此示例使用了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年9月27日