Recommendations in Android N and earlier

When interacting with TVs, users generally prefer to give minimal input before watching
content. An ideal scenario for many TV users is: sit down, turn on, and watch. The fewest steps
to get users to content they enjoy is generally the path they prefer.

Note: Use the APIs described here for making recommendations
in apps running in Android versions up to and including Android 7.1 (API level 25) only. To supply
recommendations for apps running in Android 8.0 (API level 26) and later, your app must use
recommendations channels.

The Android framework assists with minimum-input interaction by providing a recommendations row
on the home screen. Content recommendations appear as the first row of the TV home screen after
the first use of the device. Contributing recommendations from your app's content catalog can help
bring users back to your app.

Figure 1. An example of the recommendations row.

This lesson teaches you how to create recommendations and provide them to the Android framework
so users can easily discover and enjoy your app content. This discussion describes some code from
the Android Leanback sample app in the
Android TV GitHub repository
.

Best practices for recommendations

Recommendations help users quickly find the content and apps they enjoy. Creating
recommendations that are high-quality and relevant to users is an important factor in creating a
great user experience with your TV app. For this reason, you should carefully consider what
recommendations you present to the user and manage them closely.

Types of recommendations

When you create recommendations, you should link users back to incomplete viewing activities or
suggest activities that extend that to related content. Here are some specific type of
recommendations you should consider:

Continuation content recommendations for the next episode for users to resume
watching a series. Or, use continuation recommendations for paused movies, TV shows, or podcasts
so users can get back to watching paused content in just a few clicks.

New content recommendations, such as for a new first-run episode, if the user
finished watching another series. Also, if your app lets users subscribe to, follow, or track
content, use new content recommendations for unwatched items in their list of tracked content.

Related content recommendations based on the users' historic viewing behavior.

For more information on how to design recommendation cards for the best user experience, see
Recommendation Row in the Android TV Design Spec.

Refresh recommendations

When refreshing recommendations, don't just remove and repost them, because doing so causes
the recommendations to appear at the end of the recommendations row. Once a content item, such as a
movie, has been played,
remove it from the recommendations.

Customize recommendations

You can customize recommendation cards to convey branding information, by setting user interface
elements such as the card's foreground and background image, color, app icon, title, and subtitle.
To learn more, see
Recommendation Row in the Android TV Design Spec.

Group recommendations

You can optionally group recommendations based on recommendation source. For example, your app
might provide two groups of recommendations: recommendations for content the user is subscribed to,
and recommendations for new trending content the user might not be aware of.

The system ranks and orders recommendations for each group separately when creating or updating
the recommendation row. By providing group information for your recommendations, you can ensure
that your recommendations don’t get ordered below unrelated recommendations.

Use
NotificationCompat.Builder.setGroup() to set the group key string of a recommendation. For
example, to mark a recommendation as belonging to a group that contains new trending content,
you might call setGroup("trending").

Create a recommendations service

Content recommendations are created with background processing. In order for your application to
contribute to recommendations, create a service that periodically adds listings from your
app's catalog to the system's list of recommendations.

The following code example illustrates how to extend IntentService to
create a recommendation service for your application:

Build recommendations

Once your recommendation service starts running, it must create recommendations and pass them to
the Android framework. The framework receives the recommendations as Notification objects that use a specific template and are marked with a specific
category.

Setting the values

To set the UI element values for the recommendation card, you create a builder class that follows
the builder pattern described as follows. First, you set the values of the recommendation card
elements.

Run recommendations service

Your app's recommendation service must run periodically in order to create current
recommendations. To run your service, create a class that runs a timer and invokes
it at regular intervals. The following code example extends the BroadcastReceiver class to start periodic execution of a recommendation service
every half hour:

This implementation of the BroadcastReceiver class must run after start
up of the TV device where it is installed. To accomplish this, register this class in your app
manifest with an intent filter that listens for the completion of the device boot process. The
following sample code demonstrates how to add this configuration to the manifest: