Cordova plugin for Amazon Catalog Ingestion (Fire TV)

The Cordova plugin for Amazon Catalog Integration makes it possible to integrate your HTML5 web app with the Amazon Catalog. By integrating with Amazon Catalog, users can perform voice searches for media in your app, and the Fire TV search results will show your app's content.

You still have to submit your app content to the Amazon Catalog using the standard submission process for content. This plugin just adds intents with the Fire TV launcher to indicate that your app has the capability to play video.

About Cordova and this Plugin
Prerequisites — Add a Cordova project
Install the Cordova Plugin for Amazon Catalog Integration

About Cordova and this Plugin

This Amazon Catalog plugin is based on Apache Cordova. Apache Cordova provides a wrapper that allows you to include native Android functionality in HTML5 web apps. Using Cordova, you can create an APK file for your web app.

This plugin was developed to allow HTML5 web apps to be integrated with Amazon Catalog. (Catalog integration is required to surface media results from your app when users perform voice searches or global text searches on Fire TV.) Without this plugin, you can't integrate your web app with Amazon Catalog.

Prerequisites — Add a Cordova project

The instructions in the next section, "Install the Cordova Plugin for Amazon Catalog Integration", assume that you've already added a Cordova project to your web app. If you haven't, see Create an App in the Cordova documentation for details.

To create a Cordova project, you'll need to first install npm and the Cordova command-line tool .

After you install npm and the Cordova command-line tool, you would add Cordova to your web app project somewhat like this:

cordova create hello com.example.hello HelloWorld

The command specifies a package name of hello for your project. A new directory called "hello" gets created inside your web app directory. Among other files, the directory includes a config.xml file that lists the available intents that your app can handle.

Additionally, you must add the Android platform for your Cordova project:

cordova platform add android

Make sure you run the cordova platform add android command from your Cordova project directory. (If you get an error that says, "Error: Current working directory is not a Cordova-based project." you're trying to install it in the wrong directory.)

The config.xml file of your Cordova project should list the source of your content in the <content> tag. For example:

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

After you've complete these prerequisites, see the following section for details on how to install and configure the plugin.

Install the Cordova Plugin for Amazon Catalog Integration

Note: If you haven't already added a Cordova project to your HTML5 web app, see the previous section, "Prerequisites: Add a Cordova project." The steps that follow assume you have a Cordova project created for your web app. Creating the Cordova app requires you to have npm and Cordova command-line tool installed.

(Optional) Install plugman, a package manager for Node, so that it's available globally on your computer:
```
npm install -g plugman
```
Tip: Although other plugin managers are available for Apache Cordova projects, plugman is recommended because it allows you to install the plugin for a specific platform only (in this case, Android). By contrast, if you use the Cordova command-line tool's default plugin manager, the plugin will be added to both Android and iOS. If you're not pushing your app out to iOS, you can just use the Cordova command-line tool's default plugin manager. But if you are pushing out to iOS, use plugman instead of the Cordova command-line tool because this Amazon Catalog Integration plugin is not compatible with iOS.
Clone the Cordova plugin for Fire TV Launcher Integration from GitHub. Place the folder in a convenient location.

Install the Cordova plugin for Amazon Catalog using the following command. Customize the plugin's parameter values based on the parameter table below:

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" ;

Here's an example with actual parameter values configured:

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" ;

If you're not using plugman, you can install the plugin using the default Cordova command-line tool:

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

Plugin Parameters

The following table provides more detail about each parameter:

Parameter	Description	Default Value
`--project YOUR_CORDOVA_PROJECT`	The file location of your Cordova directory. If you're running the command from your Cordova directory, use "`.`" to indicate the current directory.	N/A (required)
`--plugin LOCATION_OF_PLUGIN`	The location of the Cordova Amazon Catalog plugin directory. (Note: In the beta, the plugin is available as a zip file that you download locally.)	N/A (required)
`--variable DISPLAY_NAME="Your App's Display Name"`	The name of your app.	N/A (required)
`--variable PARTNER_ID="Your App's Partner Id"`	Your Partner ID (supplied by Amazon) is the same ID that you use for catalog integration in the Partner field of your CDF file. Note that this ID is unique to your app, not to an individual or organization. If you or your organization has multiple Fire TV apps, each app will all have different Partner IDs. (See "Intent Extras" in Integrating Your App with the Fire TV Launcher for more information.)	N/A (required)
`--variable DEFAULT_SIGNEDIN_STATUS="TRUE or FALSE"`	Modifies the intent that is sent to the app. The app defaults to sending the corresponding intent if `signIn`/`signout` is never called from the web app. If no sign-in flow is available in your app, set this value to `TRUE`. (See Integrating Your App with the Fire TV Launcher for more information.)	`false`
`--variable VIDEO_ID_IS_URI="TRUE or FALSE"`	Modifies behavior of the app to correctly retrieve the content ID based on if the content IDs are in URI format or not. (See Step 2: Verify Deep Links from the Catalog for more information.)	`true`
`--variable DEEP_LINK_REGEX="A Regular Expression"`	The regular expression used to parse the content ID from the intent data. The content ID should be in the first capture group. For example, if your content ID is being passed in the format `myapp://watch/content/123456` the regular expression to parse the content ID `123456` would be `^myapp:\\/\\/watch\\/content\\/([0-9]+)$`. If not specified it defaults to sending the whole string. (See Step 2: Verify Deep Links from the Catalog for more information.)	`^(.+)$`

When you add the plugin successfully, you receive the following response:

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

The plugin files are added to your Cordova project (look in <CORDOVA_PROJECT>/platforms/android/src/com/amazon).

Edit your main activity to accept deep linking.

Note: Skip this step unless you saw the error: "Could not find a Main Activity. Follow online documentation to edit your launch Activity to enable deep linking" while adding the plugin.

If you have customized your Cordova project, but you do not know the main launch activity, you can find it by identifying the activity in the Android manifest (platforms/android/AndroidManifest.xml) that has the 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>
```
Change your main activity (e.g., MainActivity.java), so that it extends DeepLinkingCordovaActivity instead of CordovaActivity. Please verify that DeepLinkingCordovaActivity is in the same directory as your main activity. Also, please verify that DeepLinkingCordovaActivity has the same package name as your main activity.

If you cannot find the DeepLinkingCordovaActivity.java, look in the plugin directory (i.e. src/com/amazon/cordova/plugins/launcher/) and copy it to the same directory as your main activity.
Edit your web app to accept the launch parameter

When your app receives a launch intent for specific content, the extracted content ID is appended to the standard launch URL as a query parameter. The query parameter is named amazonLauncherIntegrationContentId.

Implement the functionality in your web app to handle receiving this query parameter. When your app receives the amazonLauncherIntegrationContentId parameter, it should route the contentId value directly to the player. Playback of the selected content should begin immediatedly upon app launch, with no interaction required from the customer.

Also, it is important to implement error handling within your app for situations when your uploaded catalog and available content are out of sync. We have found that a meaningful error message, followed by a redirect to an appropriate location, provides the best customer experience.
After you have successfully added the plugin, your app should be ready to build. Build it using the following command:
```
cordova build android
```
If the build is successful, Cordova generates an APK file. You can sideload this onto a Fire TV device to test it. To sideload your APK, use adb. For example, adb install /<path-to-apk>/android-debug.apk. See Installing and Running Your Fire TV App for details.

After you sideload your app, you can test the functionality by pressing the microphone button on your remote and searching for media content from your app. The search results will show the matched media from your app, and clicking the image tiles will launch your app and play the content.
To change your signedIn/signedOut status, in the onDeviceReady handler of your app, save the result of cordova.require('com.amazon.cordova.plugins.launcher'). (For example: this.launcherPlugin = cordova.require('com.amazon.cordova.plugins.launcher');.)

The launcherPlugin object has two functions:
- isSignedIn(successCallback(status), errorCallback)
- setSignedInStatus(status, successCallback, errorCallback)
Here's an example:
```
var launcherPlugin;

function myHandlerFunction(){
      launcherPlugin = cordova.require('com.amazon.cordova.plugins.launcher');
}
document.addEventListener(“deviceready”,myHandlerFunction, false)
```
The onDeviceReady event tells the web app that Cordova is finished executing and that it is okay to start executing Cordova-related code, such as setting the signedIn status.

Tip: To test the deep linking when your catalog has not been ingested yet, see Test Cases for Verifying Fire TV Deep Links.

Last updated: Oct 29, 2020