Prerequisites
- Access to the source code of your app for Fire TV.
- A Fire TV device that supports this integration. Check with your Amazon contact for a list of device types currently supported.
- Your app must participate in the catalog integration process, so Fire TV recognizes the content IDs that your app is passing with the Content Personalization data.
- Your app must share entitlements for each customer, so Fire TV shows the entitled provider as part of our content discovery experience. For details on how to do this, see Step 1: Integrate Your App with the Fire TV Launcher.
Resources
Integration steps
Step 1. Include the SDK in your app
Begin by downloading the Fire TV Integration SDK. This is an archive containing Javadocs and a jar file namedcom.amazon.tv.developer.content.sdk.jar. Copy the jar file to the libs directory in your app. This directory must be at the same package level as your build.gradle file. After you have copied or added the file, add the following line to the dependencies section in your build.gradle file.
uses-library line to your AndroidManifest.xml file, inside the app tag.
AndroidManifest.xml file.
Step 2. Implement a library check function
To ensure the device has the correct library, implement the following function to check before using the SDK code. Do this by calling thehasSystemFeature function on Android’s package manager, it is part of the standard Android API, and you can use it on any Android TV platform before attempting to make calls to the SDK.
Implement the library check function as follows:
- Java
- Kotlin
ClassNotFound exception when attempting to access any SDK class.
Step 3. Make a call to the SDK
Begin with a sample event, which indicates the customer has started watching a piece of content. To construct the event and send it, use the following code:- Java
- Kotlin
Step 4. Validate the integration
Trigger the sample event code you constructed to run inside your app. After you run the code successfully, view the logs to validate the SDK has been linked to your app and is processing the message. You can monitor these logs from the command line by running:- Mac
- Windows
Step 5. Implement SDK calls as part of in-app functionality
For each data type, review the data type’s When to Send section to understand where in your code you will need to make calls to the SDK. For example, when a customer adds an item to the watchlist we expect you call theaddCustomerListEntry API with the relevant information. You will need to first locate the code in your app that handles adding items to the watchlist and then include the API call to the Fire TV Integration SDK as part of this logic.
Implementation details
Access instances
The SDK consists of five receiver classes for different types of data:AmazonPlaybackReceiverAmazonContentEntitlementReceiverAmazonCustomerListReceiverAmazonContentInteractionReceiverAmazonSubscriptionEntitlementReceiver
getInstance. This instance can be used to call a function in-line (as seen in the example in Step 3), or you can store the instance and reuse as needed.
Amazon content ID
The SDK supports content identification across different namespaces, therefore all content IDs must be passed with an associated namespace in order for Amazon to properly identify the content item. Amazon supports the following namespace.| Namespace | Description |
|---|---|
| cdf_id | The content ID namespace for Amazon catalog integration. Use the content ID from your catalog file. In the Enhanced Metadata Bridge for Entertainment Resources (EMBER) schema, this is the id attribute on program elements such as Movie, TVEpisode, and TVSeries. In the legacy Catalog Data Format (CDF), this corresponds to the ID field of a work. |
Amazon profile ID
All data types allow you to share an associated profile ID. As there are different profile types, specify the namespace, Amazon currently supports the following profile ID namespace:| Namespace | Description |
|---|---|
| app_internal | This namespace indicates you are sharing a string representation of your internal profile ID for the active profile. This ID serves to identify specific profiles in your app, so we can attribute activity to the right Fire TV profile. Do not provide the actual ID you use internally, and the provided value should not be capable of identifying the customer. We recommend taking a hash value of your internal profile ID, which should be the same across all devices. Also, do not send us the profile name provided by the customer. Even if your app doesn’t use profiles, provide a consistent value. |
List sharing
The SDK contains functionality to share lists for both customer lists and lists of content entitlements. Lists have three types of operations:Add- This represents an incremental update to add new entries to the list.Remove- This represents a decremental update to remove entries from the list.Set- This represents replacing an existing state with a list of entries you provide.
Add and Remove are useful when the customer is interacting with content in the app and performing adds or removes. The Set update is useful when a customer first signs into the TV if you suspect the list is out of sync, and when sending off-device activity.
Limits when passing a list
If a list is small enough to safely fit in memory (less than 10,000 items), you can pass the entire list to the Fire TV Data Service without issue. The SDK handles any batching necessary to communicate data to the data service. If the data list is too large to fit in memory, or you would like to limit the memory footprint, you may send data in increments. This works well with a paging protocol between your app and your backend services that provide data. See the code sample in the Share a list in large chunks section.Share large sets of data
Set list operations might require large amounts of data to be passed. If you have too much data to reasonably fit into your memory profile within the app, use theAmazonSetListStatus parameter to work with large data sets.
The AmazonSetListStatus parameter allows for basic paging of data, and contains two static values:
ITEMS_PENDINGindicates more data for the list is expected.COMPLETEindicates that the list is complete and that all recent messages received withITEMS_PENDINGwill be used to construct the customer’s full list.
Share a list in large chunks
This example assumes you retrieve data in pages from your backend. Data is shared with theITEMS_PENDING flag until we reach the final page of data and send the COMPLETE flag.
- Java
- Kotlin
Exception handling
Calls to the SDK are “fire-and-forget” meaning you will not receive any errors when sending data. However, it is possible to receive aRuntimeException when creating the model objects if you are missing required data or have invalid data.

