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