1 page.title=Creating a Notification 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="#Import">Import the Necessary Classes</a></li> 11 <li><a href="#NotificationBuilder">Create Notifications with the Notification Builder</a></li> 12 <li><a href="#ActionButtons">Add Action Buttons</a></li> 13 <li><a href="#SpecifyWearableOnlyActions">Specify Wearable-only Actions</a></li> 14 <li><a href="#BigView">Add a Big View</a></li> 15 <li><a href="#AddWearableFeatures">Add Wearable Features for a Notification</a></li> 16 <li><a href="#Deliver">Deliver the Notification</a></li> 17 </ol> 18 19 </div> 20 </div> 21 22 <p>To build handheld notifications that are also sent to wearables, use 23 {@link android.support.v4.app.NotificationCompat.Builder}. When you build 24 notifications with this class, the system takes care of displaying 25 notifications properly, whether they appear on a handheld or wearable. 26 </p> 27 28 <p class="note"><strong>Note:</strong> 29 Notifications using {@link android.widget.RemoteViews} are stripped of custom 30 layouts and the wearable only displays the text and icons. However, you can create 31 <a href="{@docRoot}training/wearables/apps/layouts.html#CustomNotifications">create custom notifications</a> 32 that use custom card layouts by creating a wearable app that runs on the wearable device.</p> 33 </div> 34 35 <h2 id="Import">Import the necessary classes</h2> 36 37 <p>To import the necessary packages, add this line to your <code>build.gradle</code>file:</p> 38 39 <pre> 40 compile "com.android.support:support-v4:20.0.+" 41 </pre> 42 43 <p>Now that your project has access to the necessary packages, import the necessary classes from 44 the support library:</p> 45 46 <pre style="clear:right"> 47 import android.support.v4.app.NotificationCompat; 48 import android.support.v4.app.NotificationManagerCompat; 49 import android.support.v4.app.NotificationCompat.WearableExtender; 50 </pre> 51 52 <h2 id="NotificationBuilder">Create Notifications with the Notification Builder</h2> 53 54 <p>The <a href="http://developer.android.com/tools/support-library/features.html#v4">v4 55 support library</a> allows you to create notifications using the latest notification features 56 such as action buttons and large icons, while remaining compatible with Android 1.6 (API level 57 4) and higher.</p> 58 59 <p>To create a notification with the support library, you create an instance of 60 {@link android.support.v4.app.NotificationCompat.Builder} and issue the notification by 61 passing it to {@link android.support.v4.app.NotificationManagerCompat#notify notify()}. For example: 62 </p> 63 64 <pre> 65 int notificationId = 001; 66 // Build intent for notification content 67 Intent viewIntent = new Intent(this, ViewEventActivity.class); 68 viewIntent.putExtra(EXTRA_EVENT_ID, eventId); 69 PendingIntent viewPendingIntent = 70 PendingIntent.getActivity(this, 0, viewIntent, 0); 71 72 NotificationCompat.Builder notificationBuilder = 73 new NotificationCompat.Builder(this) 74 .setSmallIcon(R.drawable.ic_event) 75 .setContentTitle(eventTitle) 76 .setContentText(eventLocation) 77 .setContentIntent(viewPendingIntent); 78 79 // Get an instance of the NotificationManager service 80 NotificationManagerCompat notificationManager = 81 NotificationManagerCompat.from(this); 82 83 // Build the notification and issues it with notification manager. 84 notificationManager.notify(notificationId, notificationBuilder.build()); 85 </pre> 86 87 <p>When this notification appears on a handheld device, the user can invoke the 88 {@link android.app.PendingIntent} 89 specified by the {@link android.support.v4.app.NotificationCompat.Builder#setContentIntent 90 setContentIntent()} method by touching the notification. When this 91 notification appears on an Android wearable, the user can swipe the notification to the left to 92 reveal the <strong>Open</strong> action, which invokes the intent on the handheld device.</p> 93 94 95 <img src="{@docRoot}wear/images/circle_email_action.png" height="200" 96 style="float:right;clear:right;margin:0 0 20px 60px" /> 97 98 <h2 id="ActionButtons">Add Action Buttons</h2> 99 100 <p>In addition to the primary content action defined by 101 {@link android.support.v4.app.NotificationCompat.Builder#setContentIntent 102 setContentIntent()}, you can add other actions by passing a {@link android.app.PendingIntent} to 103 the {@link android.support.v4.app.NotificationCompat.Builder#addAction addAction()} method.</p> 104 105 <p>For example, the following code shows the same type of notification from above, but adds an 106 action to view the event location on a map.</p> 107 108 <pre style="clear:right"> 109 // Build an intent for an action to view a map 110 Intent mapIntent = new Intent(Intent.ACTION_VIEW); 111 Uri geoUri = Uri.parse("geo:0,0?q=" + Uri.encode(location)); 112 mapIntent.setData(geoUri); 113 PendingIntent mapPendingIntent = 114 PendingIntent.getActivity(this, 0, mapIntent, 0); 115 116 NotificationCompat.Builder notificationBuilder = 117 new NotificationCompat.Builder(this) 118 .setSmallIcon(R.drawable.ic_event) 119 .setContentTitle(eventTitle) 120 .setContentText(eventLocation) 121 .setContentIntent(viewPendingIntent) 122 <b>.addAction(R.drawable.ic_map, 123 getString(R.string.map), mapPendingIntent);</b> 124 </pre> 125 126 <p>On a handheld, the action appears as an 127 additional button attached to the notification. On a wearable, the action appears as 128 a large button when the user swipes the notification to the left. When the user taps the action, 129 the associated intent is invoked on the handheld.</p> 130 131 <p class="note"><strong>Tip:</strong> If your notifications include a "Reply" action 132 (such as for a messaging app), you can enhance the behavior by enabling 133 voice input replies directly from the Android wearable. For more information, read 134 <a href="{@docRoot}training/wearables/notifications/voice-input.html">Receiving Voice Input from 135 a Notification</a>. 136 </p> 137 138 <h2 id="SpecifyWearableOnlyActions">Specify Wearable-only Actions</h2> 139 140 <p> 141 If you want the actions available on the wearable to be different from those on the handheld, 142 then use {@link android.support.v4.app.NotificationCompat.WearableExtender#addAction WearableExtender.addAction()}. 143 Once you add an action with this method, the wearable does not display any other actions added with 144 {@link android.support.v4.app.NotificationCompat.Builder#addAction NotificationCompat.Builder.addAction()}. 145 That is, only the actions added with {@link android.support.v4.app.NotificationCompat.WearableExtender#addAction WearableExtender.addAction()} appear on the wearable and they do not appear on the handheld. 146 </p> 147 148 <pre> 149 // Create an intent for the reply action 150 Intent actionIntent = new Intent(this, ActionActivity.class); 151 PendingIntent actionPendingIntent = 152 PendingIntent.getActivity(this, 0, actionIntent, 153 PendingIntent.FLAG_UPDATE_CURRENT); 154 155 // Create the action 156 NotificationCompat.Action action = 157 new NotificationCompat.Action.Builder(R.drawable.ic_action, 158 getString(R.string.label), actionPendingIntent) 159 .build(); 160 161 // Build the notification and add the action via WearableExtender 162 Notification notification = 163 new NotificationCompat.Builder(mContext) 164 .setSmallIcon(R.drawable.ic_message) 165 .setContentTitle(getString(R.string.title)) 166 .setContentText(getString(R.string.content)) 167 .extend(new WearableExtender().addAction(action)) 168 .build(); 169 </pre> 170 <h2 id="BigView">Add a Big View</h2> 171 172 <img src="{@docRoot}wear/images/06_images.png" height="200" 173 style="float:right;margin:0 0 20px 40px" /> 174 175 <p>You can insert extended text content 176 to your notification by adding one of the "big view" styles to your notification. On a 177 handheld device, users can see the big view content by expanding the notification. On 178 a wearable device, the big view content is visible by default.</p> 179 180 <p>To add the extended content to your notification, call {@link 181 android.support.v4.app.NotificationCompat.Builder#setStyle setStyle()} on the {@link 182 android.support.v4.app.NotificationCompat.Builder} object, passing it an instance of either 183 {@link android.support.v4.app.NotificationCompat.BigTextStyle BigTextStyle} or 184 {@link android.support.v4.app.NotificationCompat.InboxStyle InboxStyle}.</p> 185 186 <p>For example, the following code adds an instance of 187 {@link android.support.v4.app.NotificationCompat.BigTextStyle} to the event notification, 188 in order to include the complete event description (which includes more text than can fit 189 into the space provided for {@link android.support.v4.app.NotificationCompat.Builder#setContentText 190 setContentText()}).</p> 191 192 <pre style="clear:right"> 193 // Specify the 'big view' content to display the long 194 // event description that may not fit the normal content text. 195 BigTextStyle bigStyle = new NotificationCompat.BigTextStyle(); 196 bigStyle.bigText(eventDescription); 197 198 NotificationCompat.Builder notificationBuilder = 199 new NotificationCompat.Builder(this) 200 .setSmallIcon(R.drawable.ic_event) 201 .setLargeIcon(BitmapFactory.decodeResource( 202 getResources(), R.drawable.notif_background)) 203 .setContentTitle(eventTitle) 204 .setContentText(eventLocation) 205 .setContentIntent(viewPendingIntent) 206 .addAction(R.drawable.ic_map, 207 getString(R.string.map), mapPendingIntent) 208 <b>.setStyle(bigStyle);</b> 209 </pre> 210 211 <p>Notice that you can add a large icon image to any notification using the 212 {@link android.support.v4.app.NotificationCompat.Builder#setLargeIcon setLargeIcon()} 213 method. However, these icons appear as large background images on a wearable and do not look 214 good as they are scaled up to fit the wearable screen. To add a wearable-specific background image 215 to a notification, see <a href="#AddWearableFeatures">Add Wearable Features For a Notification</a>. 216 For more information about designing notifications with large images, see the 217 <a href="{@docRoot}design/wear/index.html">Design Principles of Android 218 Wear</a>.</p> 219 220 <h2 id="AddWearableFeatures">Add Wearable Features For a Notification</h2> 221 222 <p>If you ever need to add wearable-specific options to a notification, such as specifying additional 223 pages of content or letting users dictate a text response with voice input, you can use the 224 {@link android.support.v4.app.NotificationCompat.WearableExtender} class to 225 specify the options. To use this API:</p> 226 227 <ol> 228 <li>Create an instance of a {@link android.support.v4.app.NotificationCompat.WearableExtender WearableExtender}, 229 setting the wearable-specific options for the notication.</li> 230 <li>Create an instance of 231 {@link android.support.v4.app.NotificationCompat.Builder}, setting the 232 desired properties for your notification as described earlier in this lesson.</li> 233 <li>Call {@link android.support.v4.app.NotificationCompat.Builder#extend extend()} on 234 the notification and pass in the 235 {@link android.support.v4.app.NotificationCompat.WearableExtender WearableExtender}. This applies 236 the wearable options to the notification.</li> 237 <li>Call {@link android.support.v4.app.NotificationCompat.Builder#build} to build the notification.</li> 238 </ol> 239 240 <p> 241 For example, the following code calls the 242 {@link android.support.v4.app.NotificationCompat.WearableExtender#setHintHideIcon setHintHideIcon()} 243 method to remove the app icon from the notification card. 244 </p> 245 246 <pre> 247 // Create a WearableExtender to add functionality for wearables 248 NotificationCompat.WearableExtender wearableExtender = 249 new NotificationCompat.WearableExtender() 250 .setHintHideIcon(true) 251 .setBackground(mBitmap); 252 253 // Create a NotificationCompat.Builder to build a standard notification 254 // then extend it with the WearableExtender 255 Notification notif = new NotificationCompat.Builder(mContext) 256 .setContentTitle("New mail from " + sender) 257 .setContentText(subject) 258 .setSmallIcon(R.drawable.new_mail); 259 .extend(wearableExtender) 260 .build(); 261 </pre> 262 263 <p>The 264 {@link android.support.v4.app.NotificationCompat.WearableExtender#setHintHideIcon setHintHideIcon()} 265 and {@link android.support.v4.app.NotificationCompat.WearableExtender#setBackground setBackground()} 266 methods are just two examples of new notification features available with 267 {@link android.support.v4.app.NotificationCompat.WearableExtender}.</p> 268 269 <p class="note"><strong>Note:</strong> The bitmap that you use with 270 {@link android.support.v4.app.NotificationCompat.WearableExtender#setBackground setBackground()} 271 should have a resolution of 400x400 for non-scrolling backgrounds and 640x400 for backgrounds 272 that support parallax scrolling. Place these bitmap images in the <code>res/drawable-nodpi</code> 273 directory of your handheld app. Place other non-bitmap resources for wearable notifications, such 274 as those used with the 275 {@link android.support.v4.app.NotificationCompat.WearableExtender#setContentIcon setContentIcon()} 276 method, in the <code>res/drawable-hdpi</code> directory of your handheld app.</p> 277 278 <p>If you ever need to read wearable-specific options at a later time, use the corresponding get 279 method for the option. This example calls the 280 {@link android.support.v4.app.NotificationCompat.WearableExtender#getHintHideIcon()} method to 281 get whether or not this notification hides the icon: 282 <pre> 283 NotificationCompat.WearableExtender wearableExtender = 284 new NotificationCompat.WearableExtender(notif); 285 boolean hintHideIcon = wearableExtender.getHintHideIcon(); 286 </pre> 287 288 289 <h2 id="Deliver">Deliver the Notification</h2> 290 <p>When you want to deliver your notifications, always use the 291 {@link android.support.v4.app.NotificationManagerCompat} API instead of 292 {@link android.app.NotificationManager}:</p> 293 294 <pre> 295 // Get an instance of the NotificationManager service 296 NotificationManagerCompat notificationManager = 297 NotificationManagerCompat.from(mContext); 298 299 // Issue the notification with notification manager. 300 notificationManager.notify(notificationId, notif); 301 </pre> 302 303 <p>If you use the framework's {@link android.app.NotificationManager}, some 304 features from {@link android.support.v4.app.NotificationCompat.WearableExtender} 305 do not work, so make sure to use {@link android.support.v4.app.NotificationCompat}. 306 </p> 307 308 <pre> 309 NotificationCompat.WearableExtender wearableExtender = 310 new NotificationCompat.WearableExtender(notif); 311 boolean hintHideIcon = wearableExtender.getHintHideIcon(); 312 </pre> 313 314 <p>The {@link android.support.v4.app.NotificationCompat.WearableExtender} APIs allow you to add 315 additional pages to notifications, stack notifications, and more. Continue to the following lessons 316 to learn about these features. 317 </p> 318
