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

步骤4： 集成Amazon Device Messaging (ADM) (VSK Fire TV)

步骤4： 集成Amazon Device Messaging (ADM) (VSK Fire TV)

 VSK云端集成

步骤1：
创建您的视频技能以及设置设备
→
步骤2：
设置示例Fire TV应用
→
步骤3：
集成Alexa客户端库
→
步骤4：
集成Amazon Device Messaging
→
步骤5：
对应用签名并配置安全配置文件
→
步骤6：
创建和部署Lambda软件包
→
步骤7：
更新Fire TV技能部分
→
步骤8：
测试您的技能以及观察日志
→
步骤9：
解释指令并对指令做出反应
→
步骤10：
将您的应用推送到动态应用测试
→
步骤11：
认证测试
→
步骤12：
上线！

Amazon Device Messaging (ADM) 是一种推送通知技术，让您的应用可以与您的Lambda进行交互。您的Lambda将使用ADM向您的应用发送指令。

请注意，视频技能使用ADM的方式与ADM的最常见用例不同。视频技能仅使用ADM将消息从Lambda传送到您的应用（以单向方式）。因此，此处仅嵌入了ADM文档中的相关部分。如果您直接阅读ADM的文档，会发现许多其他用法和细节，这些用法和细节可能与Fire TV上的视频技能无关。

示例应用程序说明

如果您使用的是示例Fire TV应用，则ADM已经集成到代码中，并且已经添加了ADM JAR（如果您在Android Studio中切换到项目视图并转到app [应用] > libs [库]，会看到amazon-device-messaging-1.1.0.jar）。因此，您可以跳到下一步： 步骤5： 对应用签名并配置安全配置文件。但是，如果您想更好地了解用于集成ADM的代码，请参阅AndroidManifest.xml、MainActivity.java和VSKFireTVMessageHandler.java文件。

更新您的应用清单

在接收通过ADM发送的消息时，第一步是更新您的AndroidManifest.xml文件。对现有文件进行以下更改。

  1. 打开AndroidManifest.xml文件并添加亚马逊命名空间：

    xmlns:amazon="http://schemas.amazon.com/apk/res/android"

  2. 要声明支持ADM所需的权限，请在manifest元素后面添加permission和uses-permission元素。

    <manifest xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:amazon="http://schemas.amazon.com/apk/res/android"
package="[您的程序包名称]"
android:versionCode="1"
android:versionName="1.0">
<!-- This permission ensures that no other application can intercept your
ADM消息。 -->
<permission
    android:name="[您的程序包名称].permission.RECEIVE_ADM_MESSAGE"
    android:protectionLevel="signature" />
<uses-permission android:name="[您的程序包名称].permission.RECEIVE_ADM_MESSAGE" />
<!-- This permission allows your app access to receive push notifications
来自ADM的推送通知。 -->
<uses-permission android:name="com.amazon.device.messaging.permission.RECEIVE" />
<uses-permission android:name="amazon.speech.permission.SEND_DATA_TO_ALEXA" />
<!--ADM使用WAKE_LOCK来防止处理器在收到消息时进入休眠状态。-->
<uses-permission android:name="android.permission.WAKE_LOCK" />
...
</manifest>

  3. 显式启用ADM，并声明您的应用是需要ADM才能运行(android:required="true")，还是在没有ADM的情况下也可以运行(android:required="false")。如果您指定android:required="false"，则您的应用必须在ADM不可用的情况下优雅降级。在清单的application节点中，添加amazon:enable-feature元素。

    ...
<application
      android:icon="@drawable/ic_launcher"
      android:label="@string/app_name"
      android:theme="@style/AppTheme">

      <!-- 您必须显式启用ADM，并声明您的应用在没有
         ADM的情况下无法工作(android:required="true")，还是在没有ADM的情况下可以工作(android:required="false")。
         如果您指定android:required="false"，则您的应用在ADM不可用的情况下
         必须优雅降级。 -->
         <amazon:enable-feature
	  android:name="com.amazon.device.messaging"
             android:required="true"/>
...

  4. 声明一个广播接收器以处理ADM发送的REGISTRATION和RECEIVE意图。ADM要求在AndroidManifest.xml文件中定义该接收器，而不是以编程方式定义。在amazon:enable-feature后面添加以下元素。

     <!-- You must replace the names in the service and receiver tags
     适合您程序包的名称。 -->D

 <service
     android:name="[您的服务名称]"
     android:exported="false" />

 <receiver
     android:name="[您的服务名称]"

     <!-- 此权限可确保只有ADM可以发送您的应用注册广播。 -->
     android:permission="com.amazon.device.messaging.permission.SEND" >

     <!-- 若要与ADM交互，您的应用必须侦听以下意图。 -->
     <intent-filter>
 <action android:name="com.amazon.device.messaging.intent.REGISTRATION" />
 <action android:name="com.amazon.device.messaging.intent.RECEIVE" />

 <!-- 将类别标签中的名称替换为您的应用程序包名称。 -->
 <category android:name="[您的程序包名称]" />
     </intent-filter>
 </receiver>

  5. 更新AndroidManifest.xml文件后，您可以通过调用ADMManifest.checkManifestAuthoredProperly()来确认这些更改是否适合ADM。

    如果收到java.lang.NoClassDefFoundError: com.amazon.device.messaging.ADM错误，请检查清单，确认已将amazon:enable-feature元素添加到步骤3中指定的位置。

以下代码是为ADM启用的AndroidManifest.xml文件的完整示例。

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
   xmlns:amazon="http://schemas.amazon.com/apk/res/android"
   package="[您的程序包名称]"
   android:versionCode="1"
   android:versionName="1.0" >

   <uses-sdk
      android:minSdkVersion="15"
      android:targetSdkVersion="15" />

   <permission
      android:name="[您的程序包名称].permission.RECEIVE_ADM_MESSAGE"
      android:protectionLevel="signature" />
   <uses-permission android:name="[您的程序包名称].permission.RECEIVE_ADM_MESSAGE" />

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

   <uses-permission android:name="amazon.speech.permission.SEND_DATA_TO_ALEXA" />

   <uses-permission android:name="android.permission.WAKE_LOCK" />

   <application
      android:icon="@drawable/ic_launcher"
      android:label="@string/app_name"
      android:theme="@style/AppTheme" >

      <amazon:enable-feature
         android:name="com.amazon.device.messaging"
         android:required="true"/>

      <service
         android:name="[您的服务名称]"
         android:exported="false" />

      <receiver
         android:name="[您的接收器名称]"
         android:permission="com.amazon.device.messaging.permission.SEND" >

         <intent-filter>
         <action android:name="com.amazon.device.messaging.intent.REGISTRATION" />
         <action android:name="com.amazon.device.messaging.intent.RECEIVE" />

         <category android:name="[您的程序包名称]" />
         </intent-filter>

      </receiver>
   </application>
</manifest>

处理注册和消息

清单中所声明的广播接收器会侦听意图，并在意图到达时调用应用。您的应用会通过com.amazon.device.messaging.ADMMessageHandlerBase类中定义的以下回调方法，与广播接收器进行通信：

  • onRegistered：在应用实例的注册ID准备就绪时调用。您的应用必须将此注册ID传输到服务器。这样做即可让您的服务器向该应用实例发送消息。

  • onUnregistered。在应用实例已从ADM注销时调用。

  • onRegistrationError。在应用的ADM注册请求因某一原因（例如，亚马逊用户未登录设备）而失败时调用。

  • onMessage。在ADM客户端将消息传送到应用实例时调用。

当您实现com.amazon.device.messaging.ADMMessageHandlerBase和com.amazon.device.messaging.ADMMessageReceiver的子类时，您的应用必须覆盖这些回调，如以下代码示例中所示：

public class MyADMMessageHandler extends ADMMessageHandlerBase
{
    public static class Receiver extends ADMMessageReceiver
    {
        public Receiver()
        {
            super(MyADMMessageHandler.class);
        }

    // 此处不需要其他内容；广播接收器会将意图自动
    // 转发到您的服务以进行处理。
    }

    @Override
    protected void onRegistered(final String newRegistrationId)
    {
        // 通过在主要活动中调用startRegister()来启动注册
        // 过程。当注册ID就绪时，ADM将对您的应用
        // 调用onRegistered()。将传入的注册ID传输到您的服务器，以便
        // 服务器可以将消息发送到此应用实例。如果
        // 您的注册ID因任何原因发生轮换或更改，ADM也会调用onRegistered()；
        // 如果出现这种情况，您的应用应将新的注册ID传递到您的服务器。
        // 您的服务器需要能够处理长达1536个字符的
        // 注册ID。

  	// 将获得的ADM注册ID提供给Alexa客户端库。
        AlexaClientManager.getSharedInstance().setDownChannelReady(true, newRegistrationId);
    }

    @Override
    protected void onUnregistered(final String registrationId)
    {
        // 如果您的应用在此台设备上已注销，请通知服务器
        // 此应用实例不再是有效的消息发送目标。
    }

    @Override
    protected void onRegistrationError(final String errorId)
    {
        // 注册错误应视为严重错误。因此，您的应用可
        // 优雅降级，或者您可通知用户
        // 应用的这项功能不可用。
    }

    @Override
    protected void onMessage(final Intent intent)
    {
        // 从附加到com.amazon.device.messaging.intent.RECEIVE意图
        // 的额外信息集中提取消息内容。

        // 创建字符串以访问JSON数据中的message和timeStamp字段。
        final String msgKey = getString(R.string.json_data_msg_key);
        final String timeKey = getString(R.string.json_data_time_key);

        // 获取将在onMessage()回调中触发的意图操作。
        final String intentAction = getString(R.string.intent_msg_action);

        // 获取意图中包含的额外信息。
        final Bundle extras = intent.getExtras();

        // 从意图中的额外信息中提取消息和时间。
        // ADM既不会保证消息能够送达，也不会保证消息能够按顺序送达。
        // 由于网络条件的变化，消息可能会被多次传送。
        // 您的应用必须能够处理重复消息的实例。
        final String msg = extras.getString(msgKey);
        final String time = extras.getString(timeKey);
    }
}

在ADM不可用时正常降级

请在清单文件中声明您的应用在没有ADM的情况下可以运行(android:required="false")还是不可以运行(android:required="true")。如果您指定android:required="false"，则您的应用必须在ADM不可用的情况下优雅降级。

通过将应用设计为适应缺少ADM的情况，您只需构建一个APK，无论设备是否包含ADM，该APK均可在其上安装并运行。

修改您的应用以正常降级

  1. 使用如下所示的代码检查ADM。

    ADMAvailable = false ;
try
{
    Class.forName( "com.amazon.device.messaging.ADM" );
    ADMAvailable = true ;
}
catch (ClassNotFoundException e)
{
    // 处理异常。
}

  2. 将以下代码添加到所有需要ADM库运行时的代码中。

    if (ADMAvailable)
{
    // 在此处放置需要ADM的代码。
}

  3. 在AndroidManifest.xml文件中，确认应用元素指定了以下内容：

    amazon:enable-feature android:name="com.amazon.device.messaging" android:required="false" /

ADM的替代方案

除了使用ADM将指令从Lambda函数发送到您的应用，您还可以使用自己的协议和云服务向您的应用发送操作。使用此选项，您将有权向应用传递命令。通信的协议和特性完全由您决定，可以通过您的Lambda代码或对您基础设施的服务调用对其进行管理。

此方法要求在初始化时向Alexa客户端提供该应用实例专属的标识符。当向您的Lambda代码发送指令时，此标识符将用于以此应用实例为目标。（如果您还没有应用实例的标识符或者不希望将其传递给Alexa，可考虑为此使用ANDROID_ID。）

如果您选择此方法，您将需要自己制定大部分实现代码。这些步骤将涉及以下内容：

  • 将Alexa客户端库添加到您的项目
  • 初始化时将应用实例标识符传递至客户端库
  • 确保您的云已知应用实例标识符
  • 根据需要实现Lambda函数和应用通信机制
  • Alexa客户端库的完整应用集成要求

后续步骤

继续执行步骤5： 对应用签名并配置安全配置文件。

（如果遇到任何问题而无法继续，请参阅云端集成故障排除。）

Last updated: 2021年10月13日