diff options
Diffstat (limited to 'docs/html/preview/tv/ui/recommendations.jd')
| -rw-r--r-- | docs/html/preview/tv/ui/recommendations.jd | 209 |
1 files changed, 209 insertions, 0 deletions
diff --git a/docs/html/preview/tv/ui/recommendations.jd b/docs/html/preview/tv/ui/recommendations.jd new file mode 100644 index 0000000..2c78064 --- /dev/null +++ b/docs/html/preview/tv/ui/recommendations.jd @@ -0,0 +1,209 @@ +page.title=Making Recommendations + +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + <h2>In this document</h2> + <ol> + <li><a href="#service">Create a Recommendations Service</a></li> + <li><a href="#build">Build Recommendations</a></li> + <li><a href="#run-service">Run Recommendations Service</a></li> + <li><a href="#DesignLandscapeLayouts">Design Landscape Layouts</a></li> + </ol> + +</div> +</div> + + +<p>Content recommendations appear as the first row of the TV launch screen after the first use + of the device. This row is intended to help users quickly find content they enjoy. Contributing + recommendations from your apps content catalog can help bring users back to your app.</p> + + +<img src="{@docRoot}preview/tv/images/home-recommendations.png" alt="" id="figure1" /> +<p class="img-caption"> + <strong>Figure 1.</strong> An example of the recommendations row. +</p> + + +<h2 id="service">Create a Recommendations Service</h2> + +<p>Content recommendations are created with background processing. In order for your application + to contribute to recommendations, you create a service that periodically adds listings from your + app's catalog to the system list of recommendations.</p> + +<p>The following code example illustrates how to extend the {@link android.app.IntentService} to + create a recommendation service for your application.</p> + +<pre> +public class RecommendationsService extends IntentService { + private static final int MAX_RECOMMENDATIONS = 3; + + public RecommendationsService() { + super("RecommendationService"); + } + + @Override + protected void onHandleIntent(Intent intent) { + MovieDatabase database = MovieDatabase.instance(getApplicationContext()); + List<Movie> recommendations = database.recommendations(); + + int count = 0; + + try { + for (Movie movie : recommendations) { + // build the individual content recommendations + buildRecommendation(getApplicationContext(), movie); + + if (++count >= MAX_RECOMMENDATIONS) { + break; + } + } + } catch (IOException e) { + Log.e(TAG, "Unable to update recommendation", e); + } + } +} +</pre> + +<p>In order for this class to be recognized and run as a service, you must register this service + using your app manifest. The following code snippet illustrates how to add this class as a + service:</p> + +<pre> +<manifest ... > + <application ... > + ... + + <service android:name=".RecommendationsService" + android:enabled="true" android:exported="true"/> + </application> +</manifest> +</pre> + +<h2 id="build">Build Recommendations</h2> + +<p>Once it starts running, your service 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 style and are marked with a specific category.</p> + +<p>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:</p> + +<pre> +public class RecommendationsService extends IntentService { + + ... + + public Notification buildRecommendation(Context context, Movie movie) + throws IOException { + + if (mNotificationManager == null) { + mNotificationManager = (NotificationManager) + mContext.getSystemService(Context.NOTIFICATION_SERVICE); + } + + Bundle extras = new Bundle(); + if (mBackgroundUri != movie.getBackgroundUri()) { + extras.putString(EXTRA_BACKGROUND_IMAGE_URL, movie.getBackgroundUri()); + } + + // build the recommendation as a Notification object + Notification notification = new NotificationCompat.BigPictureStyle( + new NotificationCompat.Builder(context) + .setContentTitle(movie.getTitle()) + .setContentText(movie.getDescription()) + .setPriority(movie.getPriority()) + .setOngoing(true) + .setCategory("recommendation") + .setLargeIcon(movie.getImage()) + .setSmallIcon(movie.getSmallIcon()) + .setContentIntent(buildPendingIntent(movie.getId())) + .setExtras(extras)) + .build(); + + // post the recommendation to the NotificationManager + mNotificationManager.notify(movie.getId(), 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; + } +} +</pre> + + +<h3 id="run-service">Run Recommendations Service</h3> + +<p>Your app's recommendation service must run periodically in order to create current + recommendations. In order to run your service, you should 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:</p> + +<pre> +public class BootupReceiver extends BroadcastReceiver { + private static final String TAG = "BootupActivity"; + + private static final long INITIAL_DELAY = 5000; + + @Override + public void onReceive(Context context, Intent intent) { + 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); + + alarmManager.setInexactRepeating(AlarmManager.ELAPSED_REALTIME_WAKEUP, + INITIAL_DELAY, + AlarmManager.INTERVAL_HALF_DAY, + alarmIntent); + } +} +</pre> + +<p>In order for the {@link android.content.BroadcastReceiver} class to execute after a TV + device starts up, you must register this class in your app manifest and attach an intent filter + in order for the device boot process to complete. This sample code demonstrates how to add this + configuration to the manifest:</p> + +<pre> +<manifest ... > + <application ... > + <receiver android:name=".BootupReceiver" android:enabled="true" + android:exported="false"> + <intent-filter> + <action android:name="android.intent.action.BOOT_COMPLETED"/> + </intent-filter> + </receiver> + </application> +</manifest> +</pre> + +<p class="important"> + <strong>Important:</strong> Receiving a boot completed notification requires that your app + request the {@link android.Manifest.permission#RECEIVE_BOOT_COMPLETED} permission. + For more information, see {@link android.content.Intent#ACTION_BOOT_COMPLETED}. +</p> |