1page.title=Stacking Notifications 2page.tags=notifications 3helpoutsWidget=true 4 5@jd:body 6 7<div id="tb-wrapper"> 8<div id="tb"> 9 10<h2>This lesson teaches you to</h2> 11<ol> 12 <li><a href="#AddGroup">Add Each Notification to a Group</a></li> 13 <li><a href="#AddSummary">Add a Summary Notification</a></li> 14</ol> 15 16</div> 17</div> 18<img src="/wear/images/11_bundles_B.png" height="200" width="169" 19 style="margin:0 0 20px 20px; clear:both; float:right" alt=""> 20<img src="/wear/images/11_bundles_A.png" height="200" width="169" 21 style="margin:0 20px 20px 20px; float:right" alt=""> 22<p>When creating notifications for a handheld device, you should always aggregate similar 23notifications into a single summary notification. For example, if your app creates notifications 24for received messages, you should not show more than one notification 25on a handheld device—when more than one is message is received, use a single notification 26to provide a summary such as "2 new messages."</p> 27 28<p>However, a summary notification is less useful on an Android wearable because users 29are not able to read details from each message on the wearable (they must open your app on the 30handheld to view more information). So for the wearable device, you should 31group all the notifications together in a stack. The stack of notifications appears as a single 32card, which users can expand to view the details from each notification separately. The new 33{@link android.support.v4.app.NotificationCompat.Builder#setGroup setGroup()} method makes this 34possible while allowing you to still provide only one summary notification on the handheld device.</p> 35 36<h2 id="AddGroup" style="clear:right">Add Each Notification to a Group</h2> 37 38<p>To create a stack, call {@link android.support.v4.app.NotificationCompat.Builder#setGroup setGroup()} 39for each notification you want in the stack and specify a 40group key. Then call {@link android.support.v4.app.NotificationManagerCompat#notify(int, android.app.Notification) notify()} 41to send it to the wearable.</p> 42 43<pre style="clear:right"> 44final static String GROUP_KEY_EMAILS = "group_key_emails"; 45 46// Build the notification, setting the group appropriately 47Notification notif = new NotificationCompat.Builder(mContext) 48 .setContentTitle("New mail from " + sender1) 49 .setContentText(subject1) 50 .setSmallIcon(R.drawable.new_mail) 51 .setGroup(GROUP_KEY_EMAILS) 52 .build(); 53 54// Issue the notification 55NotificationManagerCompat notificationManager = 56 NotificationManagerCompat.from(this); 57notificationManager.notify(notificationId1, notif); 58</pre> 59 60<p>Later on, when you create another notification, specify 61the same group key. When you call 62{@link android.support.v4.app.NotificationManagerCompat#notify(int, android.app.Notification) notify()}, 63this notification appears in the same stack as the previous notification, 64instead of as a new card:</p> 65 66<pre style="clear:right"> 67Notification notif2 = new NotificationCompat.Builder(mContext) 68 .setContentTitle("New mail from " + sender2) 69 .setContentText(subject2) 70 .setSmallIcon(R.drawable.new_mail) 71 .setGroup(GROUP_KEY_EMAILS) 72 .build(); 73 74notificationManager.notify(notificationId2, notif2); 75</pre> 76 77<p>By default, notifications appear in the order in which you added them, with the most recent 78 notification visible at the top. You can order notifications in another fashion by calling 79 {@link android.support.v4.app.NotificationCompat.Builder#setSortKey setSortKey()}.</p> 80 81 82<h2 id="AddSummary">Add a Summary Notification</h2> 83 84<img src="{@docRoot}wear/images/notif_summary_framed.png" height="242" width="330" style="float:right;margin:0 0 20px 40px" alt="" /> 85 86<p>It's important that you still provide a summary notification that appears on handheld devices. 87So in addition to adding each unique notification to the same stack group, also add a summary 88notification and call {@link android.support.v4.app.NotificationCompat.Builder#setGroupSummary setGroupSummary()} 89on the summary notification.</p> 90 91<p>This notification does not appear in your stack of notifications on the wearable, but 92it appears as the only notification on the handheld device.</p> 93 94<pre style="clear:right"> 95Bitmap largeIcon = BitmapFactory.decodeResource(getResources(), 96 R.drawable.ic_large_icon); 97 98// Create an InboxStyle notification 99Notification summaryNotification = new NotificationCompat.Builder(mContext) 100 .setContentTitle("2 new messages") 101 .setSmallIcon(R.drawable.ic_small_icon) 102 .setLargeIcon(largeIcon) 103 .setStyle(new NotificationCompat.InboxStyle() 104 .addLine("Alex Faaborg Check this out") 105 .addLine("Jeff Chang Launch Party") 106 .setBigContentTitle("2 new messages") 107 .setSummaryText("johndoe@gmail.com")) 108 .setGroup(GROUP_KEY_EMAILS) 109 .setGroupSummary(true) 110 .build(); 111 112notificationManager.notify(notificationId3, summaryNotification); 113</pre> 114 115<p> 116This notification uses {@link android.support.v4.app.NotificationCompat.InboxStyle}, 117which gives you an easy way to create notifications for email or messaging apps. 118You can use this style, another one defined in {@link android.support.v4.app.NotificationCompat}, 119or no style for the summary notification. 120</p> 121 122<p class="note"><b>Tip:</b> 123To style the text like in the example screenshot, see 124<a href="{@docRoot}guide/topics/resources/string-resource.html#StylingWithHTML">Styling 125with HTML markup</a> and 126<a href="{@docRoot}guide/topics/resources/string-resource.html#StylingWithSpannables">Styling 127with Spannables</a>. 128</p> 129 130<p>Summary notifications can also affect notifications on wearables without being displayed on them. 131When creating a summary notification, you can use the 132{@link android.support.v4.app.NotificationCompat.WearableExtender} class and call 133{@link android.support.v4.app.NotificationCompat.WearableExtender#setBackground setBackground()} or 134{@link android.support.v4.app.NotificationCompat.WearableExtender#addAction addAction()} to set 135a background image or an action that applies to the entire stack on the wearable. For instance, 136to set the background for an entire stack of notifications: 137</p> 138 139<pre> 140Bitmap background = BitmapFactory.decodeResource(getResources(), 141 R.drawable.ic_background); 142 143NotificationCompat.WearableExtender wearableExtender = 144 new NotificationCompat.WearableExtender() 145 .setBackground(background); 146 147// Create an InboxStyle notification 148Notification summaryNotificationWithBackground = 149 new NotificationCompat.Builder(mContext) 150 .setContentTitle("2 new messages") 151 ... 152 .extend(wearableExtender) 153 .setGroup(GROUP_KEY_EMAILS) 154 .setGroupSummary(true) 155 .build(); 156</pre>
