Recommendations Overview

V: Add Recommendations

→

You can send recommendations to users about the content in your feed you want them to watch. Recommendations appear on a "Recommended By Your Apps" row on the Fire TV home screen. Because they appear on the Fire TV home screen, recommendations encourage users to engage with your app with minimal effort.

To learn more about recommendations, see the Recommendations Overview in the Fire TV documentation. Fire App Builder has all the necessary Android code set up to send recommendations. You just have to include the recommendations information in your feed and configure some recipes in Fire App Builder to target your feed's recommendations elements.

Recommended By Your Apps Row
Two Types of Recommendations
Recommendations Requirements
See How Recommendations Works with the Sample LightCast Feed
Next Steps

Recommended By Your Apps Row

The following screenshot shows the Recommended By Your Apps row on the Fire TV home screen:

The Recommended By Your Apps row appears below Netflix or HBO Go rows if you have the Netflix or HBO Go apps. Otherwise, this row appears directly below the "Featured Apps & Games" row.

The Recommended By Your Apps row shows all recommendations from apps the user has currently installed (and opened at least once). Some top apps, like Netflix and HBO Go, get their own recommendations row all to themselves. But all other apps share space in the same "Recommended By Your Apps" row.

Two Types of Recommendations

Fire App Builder has two types of recommendations:

Global recommendations: These recommendations are sent periodically, such as when the app is started. See Send Global Recommendations for more details.
Related recommendations: These recommendations are sent when a specific video is watched. See Send Related Recommendations for more details.

If your feed does not already contain recommendations information, you will need to add this information to your feed. Each video in your feed must have a unique ID to work with the recommendations.

Note: Recommendations aren't the same as "Related Content." Related content appears as cards under the video on the media playback screen and shows other videos in the same category. Recommendations are content IDs that are specifically noted in your feed, regardless of any category grouping.

Recommendations Requirements

Fire TV requires at least 5 recommendations to be sent (from all apps combined) in order for the Recommended By Your Apps row to appear to users. However, Android has a limit of 50 recommendations max that can be sent by an app, so do not exceed 50. (See Best Practices for Recommendations for more details.)

See How Recommendations Works with the Sample LightCast Feed

When you build the sample Fire App Builder app that uses the LightCast feed, recommendations aren't sent because the LightCast feeds don't contain any recommendations info, nor is the default Navigator.json file configured with recommendations recipes.

If you want to see how recommendations works using the sample Fire App Builder app and LightCast feed, we've included a modified feed that contains recommendations information. This feed is hard-coded in a file included with the app. Follow these steps to implement it:

In your app directory, rename Navigator.json to something like Navigator_original.json. Rename navigator_with_recommendations.json to Navigator.json.

In your app's assets > configurations, open DataLoadManagerConfig.json and specify the following:

{
  "data_downloader.impl": "com.amazon.dataloader.datadownloader.BasicFileBasedDataDownloader",
  "is_cache_manager_enabled": true,
  "data_updater.duration": 14400
}

In the same folder, open BasicFileBasedDownloaderConfig.json and specify the following:
```
 {
   "data_file_path": "sample_feed_with_recommendations.json"
 }
```
On your Fire TV, activate the Developer Tools Menu using either of the following options:
- Amazon Remote Control: On the directional pad, press and hold the center and down together for 5 seconds. Then press the remote's Menu button.
- Amazon Game Controller: Press and hold A and Y buttons together for 5 seconds. Then press the controller's menu button.
Slide the Developer Options to On. Then slide the Developer Row to On:
Select the Shared Recommendation Developer Row package.
Restart your Fire TV by going go to Settings > Device > Restart.
In Android Studio, click the Run App button .

When the app starts, the following global recommendations are sent to Fire TV:
- 99605: "Cooking Tips : How to Deep Fry Chicken"
- 99551: "How to Cook with Herbs"
- 99570: "Consuming Passions Chips Recipe | Belgian Style"
- 99580: "How to Make Mapo Tofu 麻婆豆腐の作り方"
- 112683: "My Healthy Snacks & Eating Tips"
These videos are specified in a globalRecommendations array in the feed:
```
"globalRecommendations": [
    "99605",
    "99551",
    "99570",
    "99580",
    "112683"
]
```
You can see the recommendations info in the logs in Android Studio. If you click Android Monitor at the bottom of the screen and then filter on the word recommendation, you'll see logs indicating that recommendations have been built and sent. The logs will look something like this:
```
03-24 18:39:09.365 18717-18757/com.amazon.android.calypso D/RecommendationTable: record updated in database: RecommendationRecord{mContentId='99570', mRecommendationId=4, mType='Global'}
03-24 18:39:09.368 18717-18757/com.amazon.android.calypso D/RecommendationSender: Built recommendation - Consuming Passions Chips Recipe | Belgian Style
```
The mType='Global' indicates that this is a global recommendation.

In the app, browse to the first video, Thai Recipes - Thai Chicken Noodles Recipe and play it for several minutes. This video has related recommendations included in its details:

{
    "id": "162270",
    "title": "Thai Recipes - Thai Chicken Noodles Recipe",
    "description": "Thai Recipes - Thai Chicken Noodles Recipe",
    "duration": "355",
    "thumbURL": "http://l2.cdn01.net/_thumbs/0000162/0162270/0162270__015f" type="jpg",
    "imgURL": "http://l2.cdn01.net/_thumbs/0000162/0162270/0162270__015f" type="jpg",
    "videoURL": "http://media.cdn01.net/802E1F/process/encoded/video_1880k/0000162/0162270/D8HFLX0AC.mp4?source=firetv&channel_id=6341",
    "categories": [
    "International Cuisine"
    ],
    "channel_id": "6341",
    "recommendations": [
    "162269",
    "162266",
    "162265",
    "162264"
    ]
}

When you play this video, the related recommendations get sent to the Fire TV home screen:

162269: "Thai Tom Yum Soup Vegan Vegetarian Recipe"
162266: "Thai Green Curry With Chicken"
162265: "Homemade Chicken Pad Thai"
162264: "Thai Peanut Chicken Tenders"

In the logs, you'll see mType='Related' for related recommendations instead of mType='Global'.

Press the home button and return to the Fire TV home screen. Refresh the home screen by navigating to Settings, wait a few seconds, and then go back to the home screen.
Look for a row called "Recommendations Testing Row."

Look to see if any of your recommendations appear in this row. If the recommendations were successful, you should see one of the videos:

This video is the Consuming Passions Chips Recipe \| Belgian Style.

Note: If you don't see any videos in the row, most likely the Fire TV home screen needs some more time to refresh and update the recommendations row. Check back later.

To watch the video, you can click the video to launch it directly. Or you can click the menu button on your remote to launch a context menu in the lower-right corner of Fire TV. The context menu gives you the option to either watch the video or open the app.

All videos have the same priority in the recommendation settings, so their order in the recommendations row will be somewhat random.

Fire App Builder contains a database and creates a record for the recommendation. Fire App Builder retains a watch history for 12 days, but currently there isn't any logic that filters out recommendations for items the user already been watched. If your feed isn't updated with new recommendations, the same recommendations will be sent for items previously watched. Later versions of Fire App Builder might implement more advanced filtering logic.

After you're done trying out recommendations, revert some of the changes you made to the way Fire App Builder loads feeds. In particular, undo step 2 or your web-based feeds won't load properly, or see Load Your Media Feed for the proper settings for the data loader files.

Next Steps

Now that you've got a basic understanding of recommendations, go to the first instructional topic: Send Global Recommendations. Global recommendations that are sent regardless of the content the user watches.

Last updated: Oct 05, 2021