1page.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 24notifications with this class, the system takes care of displaying 25notifications properly, whether they appear on a handheld or wearable. 26</p> 27 28<p class="note"><strong>Note:</strong> 29Notifications using {@link android.widget.RemoteViews} are stripped of custom 30layouts 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> 32that 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> 40compile "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 44the support library:</p> 45 46<pre style="clear:right"> 47import android.support.v4.app.NotificationCompat; 48import android.support.v4.app.NotificationManagerCompat; 49import 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 55support library</a> allows you to create notifications using the latest notification features 56such as action buttons and large icons, while remaining compatible with Android 1.6 (API level 574) 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 61passing it to {@link android.support.v4.app.NotificationManagerCompat#notify notify()}. For example: 62</p> 63 64<pre> 65int notificationId = 001; 66// Build intent for notification content 67Intent viewIntent = new Intent(this, ViewEventActivity.class); 68viewIntent.putExtra(EXTRA_EVENT_ID, eventId); 69PendingIntent viewPendingIntent = 70 PendingIntent.getActivity(this, 0, viewIntent, 0); 71 72NotificationCompat.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 80NotificationManagerCompat notificationManager = 81 NotificationManagerCompat.from(this); 82 83// Build the notification and issues it with notification manager. 84notificationManager.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} 89specified by the {@link android.support.v4.app.NotificationCompat.Builder#setContentIntent 90setContentIntent()} method by touching the notification. When this 91notification appears on an Android wearable, the user can swipe the notification to the left to 92reveal 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 102setContentIntent()}, you can add other actions by passing a {@link android.app.PendingIntent} to 103the {@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 106action 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 110Intent mapIntent = new Intent(Intent.ACTION_VIEW); 111Uri geoUri = Uri.parse("geo:0,0?q=" + Uri.encode(location)); 112mapIntent.setData(geoUri); 113PendingIntent mapPendingIntent = 114 PendingIntent.getActivity(this, 0, mapIntent, 0); 115 116NotificationCompat.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 127additional button attached to the notification. On a wearable, the action appears as 128a large button when the user swipes the notification to the left. When the user taps the action, 129the 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> 141If you want the actions available on the wearable to be different from those on the handheld, 142then use {@link android.support.v4.app.NotificationCompat.WearableExtender#addAction WearableExtender.addAction()}. 143Once 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()}. 145That 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 150Intent actionIntent = new Intent(this, ActionActivity.class); 151PendingIntent actionPendingIntent = 152 PendingIntent.getActivity(this, 0, actionIntent, 153 PendingIntent.FLAG_UPDATE_CURRENT); 154 155// Create the action 156NotificationCompat.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 162Notification 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 176to your notification by adding one of the "big view" styles to your notification. On a 177handheld device, users can see the big view content by expanding the notification. On 178a wearable device, the big view content is visible by default.</p> 179 180<p>To add the extended content to your notification, call {@link 181android.support.v4.app.NotificationCompat.Builder#setStyle setStyle()} on the {@link 182android.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, 188in order to include the complete event description (which includes more text than can fit 189into the space provided for {@link android.support.v4.app.NotificationCompat.Builder#setContentText 190setContentText()}).</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. 195BigTextStyle bigStyle = new NotificationCompat.BigTextStyle(); 196bigStyle.bigText(eventDescription); 197 198NotificationCompat.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()} 213method. However, these icons appear as large background images on a wearable and do not look 214good as they are scaled up to fit the wearable screen. To add a wearable-specific background image 215to a notification, see <a href="#AddWearableFeatures">Add Wearable Features For a Notification</a>. 216For more information about designing notifications with large images, see the 217<a href="{@docRoot}design/wear/index.html">Design Principles of Android 218Wear</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 223pages 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 225specify 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> 241For example, the following code calls the 242{@link android.support.v4.app.NotificationCompat.WearableExtender#setHintHideIcon setHintHideIcon()} 243method to remove the app icon from the notification card. 244</p> 245 246<pre> 247// Create a WearableExtender to add functionality for wearables 248NotificationCompat.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 255Notification 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()} 265and {@link android.support.v4.app.NotificationCompat.WearableExtender#setBackground setBackground()} 266methods 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()} 271should have a resolution of 400x400 for non-scrolling backgrounds and 640x400 for backgrounds 272that support parallax scrolling. Place these bitmap images in the <code>res/drawable-nodpi</code> 273directory of your handheld app. Place other non-bitmap resources for wearable notifications, such 274as those used with the 275{@link android.support.v4.app.NotificationCompat.WearableExtender#setContentIcon setContentIcon()} 276method, 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 279method for the option. This example calls the 280{@link android.support.v4.app.NotificationCompat.WearableExtender#getHintHideIcon()} method to 281get whether or not this notification hides the icon: 282<pre> 283NotificationCompat.WearableExtender wearableExtender = 284 new NotificationCompat.WearableExtender(notif); 285boolean 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 296NotificationManagerCompat notificationManager = 297 NotificationManagerCompat.from(mContext); 298 299// Issue the notification with notification manager. 300notificationManager.notify(notificationId, notif); 301</pre> 302 303<p>If you use the framework's {@link android.app.NotificationManager}, some 304features from {@link android.support.v4.app.NotificationCompat.WearableExtender} 305do not work, so make sure to use {@link android.support.v4.app.NotificationCompat}. 306</p> 307 308<pre> 309NotificationCompat.WearableExtender wearableExtender = 310 new NotificationCompat.WearableExtender(notif); 311boolean hintHideIcon = wearableExtender.getHintHideIcon(); 312 </pre> 313 314<p>The {@link android.support.v4.app.NotificationCompat.WearableExtender} APIs allow you to add 315additional pages to notifications, stack notifications, and more. Continue to the following lessons 316to learn about these features. 317</p> 318
