用于 Amazon Catalog 引入的 Cordova 插件


用于 Amazon Catalog 引入的 Cordova 插件

用于 Amazon Catalog 集成的 Cordova 插件可以将您的 HTML5 Web 应用与 Amazon Catalog 集成。通过与 Amazon Catalog 集成,用户可以对应用中的媒体执行语音搜索,Fire TV 搜索结果将显示应用的内容。

您仍然必须使用内容的标准提交流程将应用内容提交至 Amazon Catalog。这个插件只是随 Fire TV 启动器一起添加意图,以表明您的应用有播放视频的功能。

关于 Cordova 和这个插件

这个 Amazon Catalog 插件基于 Apache Cordova。Apache Cordova 提供了一个包装器,允许您在 HTML5 Web 应用中包含原生安卓功能。使用 Cordova,您可以为您的 Web 应用创建 APK 文件。

这个插件是为了允许 HTML5 Web 应用(如使用 WASK 开发的那些应用)与 Amazon Catalog 集成而开发的。(当用户在 Fire TV 上执行语音搜索或全局文本搜索时,需要目录集成才能显示应用中的媒体结果。) 没有这个插件,您就无法将您的 Web 应用与 Amazon Catalog 集成。

先决条件 — 添加 Cordova 项目

下一节“安装用于 Amazon Catalog 集成的 Cordova 插件”中的说明假定您已将 Cordova 项目添加到您的 Web 应用中。如果尚未添加,请参阅 Cordova 文档中的创建应用以了解详细信息。

要创建 Cordova 项目,您需要先安装 npmCordova 命令行工具

安装 npm 和 Cordova 命令行工具后,您可以将 Cordova 添加到您的 Web 应用项目中,如下所示:

cordova create hello com.example.hello HelloWorld

该命令为您的项目指定 hello 程序包名称。在您的 Web 应用目录中创建一个名为“hello”的新目录。除其他文件外,该目录还包含一个 config.xml 文件,该文件列出了您的应用可以处理的可用意图。

此外,您必须为您的 Cordova 项目添加安卓平台:

cordova platform add android

确保从您的 Cordova 项目目录中运行 cordova platform add android 命令。(如果您收到一个错误,指出:“错误: 当前工作目录不是基于 Cordova 的项目”,则表示您试图将它安装在错误的目录中。)

Cordova 项目的 config.xml 文件应该在 <content> 标记中列出内容的来源。例如:

<content src="https://firetv.acme.com/" />

完成这些先决条件后,请参阅以下部分了解有关如何安装和配置插件的详细信息。

为 Amazon Catalog 集成安装 Cordova 插件

  1. (可选)安装 plugman(一个 Node 程序包管理器),以便它在您的计算机上全局可用:

    npm install -g plugman
    
  2. GitHub 克隆用于 Fire TV 启动器集成的 Cordova 插件。将文件夹放在一个方便的位置。

  3. 使用以下命令为 Amazon Catalog 安装 Cordova 插件。根据下面的参数表自定义插件的参数值:

    plugman install --platform android --project YOUR_CORDOVA_PROJECT/platforms/android --plugin LOCATION_OF_PLUGIN --variable DISPLAY_NAME="Your App's Display Name" --variable PARTNER_ID="Your App's Partner Id" --variable DEFAULT_SIGNEDIN_STATUS="TRUE or FALSE" ;
    

    以下是一个配置了实际参数值的示例:

    plugman install --platform android --project ./platforms/android --plugin ../../CI-Plugin-For-Release --variable DISPLAY_NAME="ACME" --variable PARTNER_ID="ACME" --variable DEFAULT_SIGNEDIN_STATUS="TRUE" ;
    

    如果您不使用 plugman,则可以使用默认的 Cordova 命令行工具来安装插件:

    cordova plugin add LOCATION_OF_PLUGIN --variable PARTNER_ID="Your App's Partner Id" --variable DISPLAY_NAME="Your App's Display Name"
    

    插件参数

    下表提供了有关每个参数的更多详细信息:

    参数 描述 默认值
    --project YOUR_CORDOVA_PROJECT 您的 Cordova 目录的文件位置。如果您从您的 Cordova 目录运行命令,请使用 “.” 来指示当前目录。 不适用(必填)
    --plugin LOCATION_OF_PLUGIN Cordova Amazon Catalog 插件目录的位置。(注意:​ 在测试版中,该插件作为一个 zip 文件提供,您可将其下载到本地。) 不适用(必填)
    --variable DISPLAY_NAME="Your App's Display Name" 您的应用的名称。 不适用(必填)
    --variable PARTNER_ID="Your App's Partner Id" 您的合作伙伴 ID(由亚马逊提供)与 CDF 文件的“合作伙伴”字段中用于目录集成的 ID 相同。请注意,此 ID 对您的应用而言是唯一的,而不是针对个人或组织。如果您或您的组织有多个 Fire TV 应用,则每个应用都将具有不同的合作伙伴 ID。(有关更多信息,请参阅“将您的应用与 Fire TV 主屏幕启动器集成”中的“意图额外信息”。) 不适用(必填)
    --variable DEFAULT_SIGNEDIN_STATUS="TRUE or FALSE" 修改发送到应用的意图。如果从未从 Web 应用调用 signIn/signout,则应用默认会发送相应的意图。如果应用中没有可用的登录流程,请将此值设置为 TRUE。(有关更多信息,请参阅将您的应用与 Fire TV 主屏幕启动器集成。) false
    --variable VIDEO_ID_IS_URI="TRUE or FALSE" 修改应用的行为,以根据内容 ID 是否为 URI 格式正确检索内容 ID。(请参阅步骤 3: 从启动器处理播放和登录意图,以获取更多信息。) true
    --variable DEEP_LINK_REGEX="A Regular Expression" 用于从意图数据解析内容 ID 的正则表达式。内容 ID 应位于第一个捕获组中。例如,如果您的内容 ID 以 myapp://watch/content/123456 格式传递,则解析内容 ID 123456 的正则表达式将是 ^myapp:\\/\\/watch\\/content\\/([0-9]+)$。如果未指定,则默认为发送整个字符串。(请参阅步骤 3: 从启动器处理播放和登录意图,以获取更多信息。) ^(.+)$

    当您成功添加插件时,您会收到以下响应:

    Installing "com.amazon.cordova.plugins.launcher" for android
    Adding intent-filter to Android Manifest
    New Activity Extending CordovaActivity created
    New Activity package adjusted to match project package
    Main Activity Parent Class changed to DeepLinkingCordovaActivity
    

    插件文件被添加到您的 Cordova 项目(在 <CORDOVA_PROJECT>/platforms/android/src/com/amazon 中查找)。

  4. 编辑您的主要活动以接受深层链接。

    如果您自定义了您的 Cordova 项目,但不知道主启动活动,则可以通过识别安卓清单 (platforms/android/AndroidManifest.xml) 中具有 intent-filter 的活动来找到它:

    <intent-filter android:label="@string/launcher_name">
      <action android:name="android.intent.action.MAIN" />
      <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
    

    更改您的主要活动(例如 MainActivity.java),以便它扩展 DeepLinkingCordovaActivity 而不是 CordovaActivity。请验证 DeepLinkingCordovaActivity 与您的主要活动是否位于同一目录中。此外,请验证 DeepLinkingCordovaActivity 与您的主要活动是否具有相同的程序包名称。

    如果您找不到 DeepLinkingCordovaActivity.java,请在插件目录(即 src/com/amazon/cordova/plugins/launcher/ 中查找),并将其复制到您的主要活动所在的同一目录。

  5. 编辑 Web 应用以接受启动参数

    当您的应用收到针对特定内容的启动意图时,提取的内容 ID 将作为查询参数附加到标准启动 URL 中。查询名为 amazonLauncherIntegrationContentId 的参数。

    在 Web 应用中实现功能以接收此查询参数。当您的应用收到 amazonLauncherIntegrationContentId 参数时,它应将该 contentId 值直接路由给播放器。所选内容应在应用启动后立即开始播放,无需客户互动。

    此外,当上传的目录和可用内容不同步时,务必在应用中实施错误处理。我们发现,一条有意义的错误消息后跟指向适当位置的重定向,可提供最佳客户体验。

  6. 成功添加插件后,应用应该准备好构建。使用以下命令构建它:

    cordova build android
    

    如果构建成功,Cordova 会生成 APK 文件。您可以将其旁加载到 Fire TV 设备上进行测试。要旁加载您的 APK,请使用 adb。例如,adb install /<path-to-apk>/android-debug.apk。有关详细信息,请参阅安装和运行 Fire TV 应用

    旁加载应用后,您可以通过按遥控器上的麦克风按钮并从应用中搜索媒体内容来测试功能。搜索结果将显示应用中匹配的媒体,单击图像磁贴将启动应用并播放内容。

  7. 要更改您的登录/注销状态,请在您的应用的 onDeviceReady 处理程序中保存 cordova.require('com.amazon.cordova.plugins.launcher') 结果。(例如:this.launcherPlugin = cordova.require('com.amazon.cordova.plugins.launcher');。)

    launcherPlugin 对象有两个函数:

    • isSignedIn(successCallback(status), errorCallback)
    • setSignedInStatus(status, successCallback, errorCallback)

    示例如下:

    var launcherPlugin;
    
    function myHandlerFunction(){
          launcherPlugin = cordova.require('com.amazon.cordova.plugins.launcher');
    }
    document.addEventListener(deviceready,myHandlerFunction, false)
    

    如果您使用 WASK 构建您的应用,请注意 WASK 旨在与亚马逊的自定义版本 Cordova(而不是 vanilla Cordova)一起使用。因此,侦听器为 onAmazonPlatformReadyOnDeviceReady 事件告诉 Web 应用 Cordova 已执行完毕,可以开始执行与 Cordova 相关的代码,例如设置 signedIn 状态。