开发人员控制台

用于引入Amazon Catalog的Cordova插件


用于引入Amazon Catalog的Cordova插件

通过Amazon Catalog集成的Cordova插件,能够将HTML5 网页应用与Amazon Catalog集成。通过与Amazon Catalog集成,用户可对应用中的媒体进行语音搜索,Fire TV搜索结果中将显示应用的内容。

仍必须通过内容标准提交流程将内容提交至Amazon Catalog。该插件仅添加FireTV启动器的请求(intent),以表明应用能播放视频。

Cordova和本插件介绍

本Amazon Catalog插件基于Apache Cordova。Apache Cordova提供了一个包装器(wrapper),可用于在HTML5 网页应用中包含原生安卓功能。通过Cordova,可为网页应用创建APK文件。

本插件开发目的是将HTML5 网页应用(例如采用WASK开发的应用)与Amazon Catalog集成。(当用户在Fire TV上进行语音搜索或全局文本搜索时,需要目录集成,以显示收索的结果。) 若不采用此插件,无法将网页应用与Amazon Catalog集成。

先决条件 — 添加Cordova项目

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

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

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

cordova create hello com.example.hello HelloWorld

该命令用于为项目指定hello程序包命名。在网页应用目录中创建名为“hello”的新目录。除其他文件外,该目录还包含一个config.xml文件,该文件列出了相关请求(intent)(可通过应用处理)。

此外,必须为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="应用显示名称" --variable PARTNER_ID="应用的合作伙伴ID" --variable DEFAULT_SIGNEDIN_STATUS="TRUE或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="您的应用的合作伙伴ID" --variable DISPLAY_NAME="您的应用的显示名称"
    

    插件参数

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

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

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

    正在为Android安装“com.amazon.cordova.plugins.launcher”
    正在向Android清单添加 intent-filter
    已创建新活动 Extending CordovaActivity
    已调整新活动包来匹配项目包
    主活动的父类已更改为 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. 编辑网页应用以接受启动参数

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

    在网页应用中实现功能以接收此查询参数。当您的应用收到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事件告诉网页应用Cordova已执行完毕,可以开始执行与Cordova相关的代码,例如设置signedIn状态。