-To learn more about searching within your app, see Searching within TV Apps. -
The recommendations row on Android TV is a central feature of the Home Screen that allows
users quick access to dynamic and relevant content for their media-consumption activities. The
diff --git a/docs/html/design/tv/patterns.jd b/docs/html/design/tv/patterns.jd
index be7ae319ac91d..e786ee5bc1909 100644
--- a/docs/html/design/tv/patterns.jd
+++ b/docs/html/design/tv/patterns.jd
@@ -15,24 +15,16 @@ page.title=UI Patterns for TV
-
A key aspect of making your application work well with a D-Pad controller is to make sure +
A key aspect of making your application work well with a D-pad controller is to make sure that there is always an object that is obviously in focus. Your app must clearly indicate what object is focused, so users can easily see what action they can take. Use scale, shadow brightness, opacity, animation or a combination of these attributes to help users see a focused object.
+Apps on TV devices require some additional icon images for presentation in the system - user interface, including home screen launcher images (banners) and recommendation icons. - The visual specifications for these icons are shown below.
- - -App Banners represent your app on the home screen of TV devices and serve and as a way for - users to launch your app. Here are specific requirements for a banner image: +
App Banners represent your app or game on the home screens of TV devices and serve and as a way for + users to launch your app. Here are the specific requirements for a banner image:
See Provide a home screen banner in Get Started with TV Apps for more information.
-Recommendation cards include a small icon that is imposed over a colored background. - An example and specifications for this icon are shown below:
+The first row of the Android TV home screen displays cards for content recommended by applications. +Your application provides these recommendations, as described in +. For a visual overview of recommendations, see +Design for Android TV.
-
+Here are the requirements for recommendation icons:
+The design elements of the recommendation card are as follows:
+The design specifications for these elements are described below.
+ +You can also set a background image (not shown) and the color of the card's text area in the + recommendation notification. See + Recommendations for more information.
+ +
+
+ The background image also appears behind the recommendations +row and fills the Android TV home screen when the user selects the recommendation card. This image +should be different than the one provided for the large icon, and meet the following specifications:
- Note: Your app icon image may be desaturated and blended for some card - displays. + Note: If the background image does not meet the size requirements, the system + scales it to fit.
- -Background images are displayed in the background of your app to provide additional visual
- interest, information, or branding. The user interface widgets provided in the v17 leanback support
+ The user interface widgets provided in the
+ v17 leanback support
library provide specific support for background images and for updating them as items gain
- and lose focus. The specific requirements for background images on TV devices is that they
- should be full color and a size of 1920 x 1080 pixels.
+ and lose focus.
- Important: Background images must not be transparent. Your must not allow any
- portion of another app to be seen through your app.
- Typically, the large icon is an image of the content for the recommendation. It appears
+above a colored area that contains the recommendation content title and text. This image should be
+different from that which you provide for the background image, and conform to the following
+specifications:
- Note: If you background image does not meet the size requirements, it is scaled
- to fit.
+ Note: If the large icon does not meet the size requirements, the system
+ scales it to fit.
Recommendation cards include a small icon that is imposed over a colored background. The icon and
+background color display at 100% opacity when the card is selected, and at 50% opacity when not
+selected. Here are the requirements for recommendation small icons: Sounds on Android TV bring a cinematic quality to the interaction experience. You should
diff --git a/docs/html/images/tv/recommend-card.png b/docs/html/images/tv/recommend-card.png
new file mode 100644
index 0000000000000..1cc43114925f5
Binary files /dev/null and b/docs/html/images/tv/recommend-card.png differ
diff --git a/docs/html/training/tv/discovery/recommendations.jd b/docs/html/training/tv/discovery/recommendations.jd
index 0f6d2568c2a6a..d348c1474c44e 100644
--- a/docs/html/training/tv/discovery/recommendations.jd
+++ b/docs/html/training/tv/discovery/recommendations.jd
@@ -14,6 +14,11 @@ trainingnavtop=true
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 launch screen after
+ 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.
This lesson teaches you how to create recommendations and provide them to the Android framework
- so your app content can be easily discovered and enjoyed by users.
+ so users can easily discover and enjoy your app content. This discussion describes some code from
+ the Android
+ Leanback sample app.
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 list of recommendations.
+ app's catalog to the system's list of recommendations.
@@ -54,26 +61,50 @@ trainingnavtop=true
create a recommendation service for your application:
+
+ UpdateRecommendationsService.java
+Icons
+
+Large icon
+
+
+
Small icon
+
+
+
+
+
+
Audio Feedback
Try it out
+
@@ -25,7 +30,7 @@ trainingnavtop=true
-public class RecommendationsService extends IntentService {
+public class UpdateRecommendationsService extends IntentService {
+ private static final String TAG = "UpdateRecommendationsService";
private static final int MAX_RECOMMENDATIONS = 3;
- public RecommendationsService() {
+ public UpdateRecommendationsService() {
super("RecommendationService");
}
@Override
protected void onHandleIntent(Intent intent) {
- MovieDatabase database = MovieDatabase.instance(getApplicationContext());
- List
@@ -90,125 +136,165 @@ public class RecommendationsService extends IntentService {
app manifest. The following code snippet illustrates how to declare this class as a service:
<manifest ... >
<application ... >
...
- <service android:name=".RecommendationsService"
- android:enabled="true" android:exported="true"/>
+ <service
+ android:name="com.example.android.tvleanback.UpdateRecommendationsService"
+ android:enabled="true" />
</application>
</manifest>
+Base your recommendations on user behavior and data such as play lists, wish lists, and associated +content. 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.
- Once your recommendation server starts running, it must create recommendations and pass them to + Once your recommendation service starts running, it must create recommendations and pass them to the Android framework. The framework receives the recommendations as {@link android.app.Notification} objects that use a specific template and are marked with a specific category.
-- The following code example demonstrates how to get an instance of the {@link - android.app.NotificationManager}, build a recommendation, and post it to the manager: +
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.
+ ++ + RecommendationBuilder.java
-
-public class RecommendationsService extends IntentService {
-
+public class RecommendationBuilder {
...
- public Notification buildRecommendation(Context context, Movie movie)
- throws IOException {
-
- if (mNotificationManager == null) {
- mNotificationManager = (NotificationManager)
- mContext.getSystemService(Context.NOTIFICATION_SERVICE);
+ public RecommendationBuilder setTitle(String title) {
+ mTitle = title;
+ return this;
}
- Bundle extras = new Bundle();
- if (mBackgroundUri != movie.getBackgroundUri()) {
- extras.putString(EXTRA_BACKGROUND_IMAGE_URL, movie.getBackgroundUri());
+ public RecommendationBuilder setDescription(String description) {
+ mDescription = description;
+ return this;
}
- // build the recommendation as a Notification object
+ public RecommendationBuilder setImage(String uri) {
+ mImageUri = uri;
+ return this;
+ }
+
+ public RecommendationBuilder setBackground(String uri) {
+ mBackgroundUri = uri;
+ return this;
+ }
+...
+
+
++ Once you've set the values, you then build the notification, assigning the values from the builder + class to the notification, and calling {@link android.support.v4.app.NotificationCompat.Builder#build() + NotificationCompat.Builder.build()}. +
+ ++ Also, be sure to call + {@link android.support.v4.app.NotificationCompat.Builder#setLocalOnly(boolean) setLocalOnly()} + so the {@link android.support.v4.app.NotificationCompat.BigPictureStyle} notification won't show up + on other devices. +
+ ++ The following code example demonstrates how to build a recommendation, and post it to the manager. +
+ ++ + RecommendationBuilder.java +
+
+public class RecommendationBuilder {
+ ...
+
+ public Notification build() throws IOException {
+ ...
+
Notification notification = new NotificationCompat.BigPictureStyle(
- new NotificationCompat.Builder(context)
- .setContentTitle(movie.getTitle())
- .setContentText(movie.getDescription())
- .setContentInfo(APP_NAME)
- .setGroup("ActionMovies")
- .setSortKey("0.8")
- .setPriority(movie.getPriority())
- .setColor(#FFFF2020)
- .setCategory("recommendation")
- .setLargeIcon(movie.getImage())
- .setSmallIcon(movie.getSmallIcon())
- .setContentIntent(buildPendingIntent(movie.getId()))
+ new NotificationCompat.Builder(mContext)
+ .setContentTitle(mTitle)
+ .setContentText(mDescription)
+ .setPriority(mPriority)
+ .setLocalOnly(true)
+ .setOngoing(true)
+ .setColor(mContext.getResources().getColor(R.color.fastlane_background))
+ .setCategory(Notification.CATEGORY_RECOMMENDATION)
+ .setLargeIcon(image)
+ .setSmallIcon(mSmallIcon)
+ .setContentIntent(mIntent)
.setExtras(extras))
.build();
- // post the recommendation to the NotificationManager
- mNotificationManager.notify(movie.getId(), notification);
+ mNotificationManager.notify(mId, notification);
mNotificationManager = null;
return notification;
}
-
- private PendingIntent buildPendingIntent(long id) {
- Intent detailsIntent = new Intent(this, DetailsActivity.class);
- detailsIntent.putExtra("id", id);
-
- TaskStackBuilder stackBuilder = TaskStackBuilder.create(this);
- stackBuilder.addParentStack(DetailsActivity.class);
- stackBuilder.addNextIntent(detailsIntent);
- // Ensure each PendingIntent is unique
- detailsIntent.setAction(Long.toString(id));
-
- PendingIntent intent = stackBuilder.getPendingIntent(
- 0, PendingIntent.FLAG_UPDATE_CURRENT);
- return intent;
- }
}
-
-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 {@link android.content.BroadcastReceiver} class to start periodic execution of a recommendation service - every 12 hours: + every half hour:
+
-public class BootupReceiver extends BroadcastReceiver {
+public class BootupActivity extends BroadcastReceiver {
private static final String TAG = "BootupActivity";
private static final long INITIAL_DELAY = 5000;
@Override
public void onReceive(Context context, Intent intent) {
+ Log.d(TAG, "BootupActivity initiated");
if (intent.getAction().endsWith(Intent.ACTION_BOOT_COMPLETED)) {
scheduleRecommendationUpdate(context);
}
}
private void scheduleRecommendationUpdate(Context context) {
- AlarmManager alarmManager = (AlarmManager)context.getSystemService(
- Context.ALARM_SERVICE);
- Intent recommendationIntent = new Intent(context,
- UpdateRecommendationsService.class);
- PendingIntent alarmIntent = PendingIntent.getService(context, 0,
- recommendationIntent, 0);
+ Log.d(TAG, "Scheduling recommendations update");
+
+ AlarmManager alarmManager = (AlarmManager) context.getSystemService(Context.ALARM_SERVICE);
+ Intent recommendationIntent = new Intent(context, UpdateRecommendationsService.class);
+ PendingIntent alarmIntent = PendingIntent.getService(context, 0, recommendationIntent, 0);
alarmManager.setInexactRepeating(AlarmManager.ELAPSED_REALTIME_WAKEUP,
INITIAL_DELAY,
- AlarmManager.INTERVAL_HALF_DAY,
+ AlarmManager.INTERVAL_HALF_HOUR,
alarmIntent);
}
}
@@ -221,10 +307,15 @@ public class BootupReceiver extends BroadcastReceiver {
following sample code demonstrates how to add this configuration to the manifest:
+
<manifest ... >
<application ... >
- <receiver android:name=".BootupReceiver" android:enabled="true"
+ <receiver android:name="com.example.android.tvleanback.BootupActivity"
+ android:enabled="true"
android:exported="false">
<intent-filter>
<action android:name="android.intent.action.BOOT_COMPLETED"/>
@@ -234,7 +325,7 @@ public class BootupReceiver extends BroadcastReceiver {
</manifest>
-
+
Important: Receiving a boot completed notification requires that your app
requests the {@link android.Manifest.permission#RECEIVE_BOOT_COMPLETED} permission.
For more information, see {@link android.content.Intent#ACTION_BOOT_COMPLETED}.