用于引入Amazon Catalog的Cordova插件

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

仍必须通过内容标准提交流程将应用内容提交至Amazon Catalog。该插件仅添加Fire TV启动程序的意图（intent)，以表明应用能播放视频。

Cordova和本插件介绍
先决条件 — 添加Cordova项目
安装用于Amazon Catalog集成的Cordova插件

Cordova和本插件介绍

本Amazon Catalog插件基于Apache Cordova。Apache Cordova提供了一个包装器，允许您在HTML5网页应用中包含原生Android功能。您可以使用Cordova为您的网页应用创建APK文件。

开发该插件的目的是集成HTML5网页应用与Amazon Catalog。（当用户在Fire TV上进行语音搜索或全局文本搜索时，需要目录集成，以显示您应用的媒体搜索结果。）若不采用此插件，网页应用无法与Amazon Catalog集成。

先决条件 — 添加Cordova项目

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

要创建Cordova项目，您需要先安装npm和Cordova命令行工具。

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

cordova create hello com.example.hello HelloWorld

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

此外，必须为Cordova项目添加Android平台：

cordova platform add android

务必从Cordova项目目录中运行cordova platform add android命令。（若收到错误提示（内容为：“错误：当前工作目录不是基于Cordova的项目”，说明安装目录错误。）

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

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

满足上述先决条件后，请参阅以下章节，以便了解安装和配置插件的详细信息。

安装用于Amazon Catalog集成的Cordova插件

注意： 如果您尚未将Cordova项目添加到HTML5网页应用中，请参阅上一节“先决条件：添加Cordova项目”。以下步骤假定已为网页应用创建了Cordova项目。要创建Cordova应用，需要安装npm和Cordova命令行工具。

（可选）安装plugman（Node程序包管理器），确保它在整个电脑上均可用：
```
npm install -g plugman
```
提示： 虽然其他插件管理器也能用于Apache Cordova项目，但是推荐使用plugman，因为采用Plugman时，只能针对特定平台（在本例中为Android）安装插件。相比之下，若采用Cordova命令行工具的默认插件管理器，则该插件将同时添加到Android和iOS中。若未将应用推送到iOS，可用Cordova命令行工具的默认插件管理器。但是，如果您正在推送到iOS，请使用plugman，而非Cordova命令行工具，因为此Amazon Catalog集成插件与iOS不兼容。
从GitHub克隆用于Fire TV启动程序集成的Cordova插件。将文件夹放在方便的位置。

使用以下命令安装用于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。（有关更多信息，请参阅步骤2：从目录验证深层链接。）	`true`
`--variable DEEP_LINK_REGEX="正则表达式"`	用于从意图数据解析内容ID的正则表达式。内容ID应位于第一个捕获组中。例如，如果您的内容ID以`myapp://watch/content/123456`格式传递，则解析内容ID `123456`的正则表达式将是`^myapp:\\/\\/watch\\/content\\/([0-9]+)$`。如果未指定，则默认为发送整个字符串。（有关更多信息，请参阅步骤2：从目录验证深层链接。）	`^(.+)$`

成功添加插件时，您会收到以下响应：

正在为Android安装“com.amazon.cordova.plugins.launcher”
正在向Android清单添加intent-filter
已创建新活动Extending CordovaActivity
已调整新活动包来匹配项目包
主活动的父类已更改为DeepLinkingCordovaActivity

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

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

注意： 跳过此步骤，除非您在添加插件时看到错误： “找不到主活动。按照在线文档操作，编辑启动活动以启用深层链接”。

如果您自定义了Cordova项目，但不知道主启动活动，可以通过识别Android清单(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/）中查找，并将其复制到主活动所在的同一目录。
编辑网页应用以接受启动参数

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

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

此外，必须针对上传的目录和可用内容不同步的情形，在应用中实施错误处理。我们发现，一条有意义的错误消息后跟指向适当位置的重定向，可提供最佳客户体验。
成功添加插件后，应用应该准备好构建。使用以下命令构建它：
```
cordova build android
```
如果构建成功，Cordova会生成APK文件。您可以将其侧载到Fire TV设备上进行测试。要旁侧载您的APK，请使用ADB。例如，adb install /<path-to-apk>/android-debug.apk。有关详细信息，请参阅安装和运行Fire TV应用。

侧载应用后，您可以通过按遥控器上的麦克风按钮并从应用中搜索媒体内容来测试功能。搜索结果将显示应用中匹配的媒体，单击图像磁贴将启动应用并播放内容。
要更改signedIn/signedOut状态，请在应用的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)
```
onDeviceReady事件告知网页应用Cordova已执行完毕，可以开始执行与Cordova相关的代码，例如设置signedIn状态。

提示： 要在尚未引入目录时测试深层链接，请参阅验证Fire TV深层链接的测试案例。