1 page.title=Design for Notifications 2 page.tags="notifications","design","L" 3 @jd:body 4 5 <style> 6 .col-5, .col-6, .col-7 { 7 margin-left:0px; 8 } 9 </style> 10 11 <p>The notification system allows users to keep informed about relevant and timely 12 events in your app, such as new chat messages from a friend or a calendar event. 13 Think of notifications as a news channel that alerts the user to important events as 14 they happen or a log that chronicles events while the user is not paying attention - 15 and one that is synced as appropriate across all their Android devices.</p> 16 17 <h4 id="New"><strong>New in L</strong></h4> 18 19 <p>In L, notifications receive an important structural visual and functional update:</p> 20 21 <ul> 22 <li> Visual changes to notifications as part of material design</li> 23 <li> Notifications are now available on the device lockscreen, yet sensitive content can still 24 be hidden behind it</li> 25 <li> A new presentation format called Heads-up for receiving high priority notifications while 26 using the device</li> 27 <li> Cloud-synced notifications - act on a notification on your Android tablet and it is also 28 dismissed on your phone.</li> 29 <li> And starting now (in Android 4.4W, API Level 20, the platform release for Android Wear), 30 your notifications will bridge to Android Wear devices. You can extend the functionality of 31 notifications on Wear in two different ways. First, you can add speech input and canned responses 32 to Actions on Wear, allowing users to complete tasks from their wrists. Second, you can write 33 Wear apps that hook into your notifications to go even further in terms of creating interactive 34 experiences for users.</li> 35 </ul> 36 37 <h2 id="Anatomy">Anatomy of a notification</h2> 38 39 <p>This section goes over basic parts of a notification and how they can 40 appear on different types of devices.</p> 41 42 <h3 id="BaseLayout">Base Layout</h3> 43 44 <p>At a minimum, all notifications consist of a base layout, including:</p> 45 46 <ul> 47 <li> The notification's <strong>icon</strong>, symbolizing the originating app, and also 48 potentially the kind of notification if the app has several substantially different sorts of 49 notifications it can post</li> 50 <li> A notification <strong>title</strong> and additional <strong>text</strong></li> 51 <li> A <strong>timestamp</strong></li> 52 </ul> 53 54 <p>Notifications created with <code>Notification.Builder</code> for versions of Android earlier 55 than L will look and work the same in L, with only minor stylistic changes that the system handles 56 for you.</p> 57 58 59 <img style="margin:20px 0 0 0" src="{@docRoot}preview/images/notifications/basic_combo.png" 60 alt="" width="700px" /> 61 62 63 <div style="clear:both;margin-top:20px"> 64 <p class="img-caption"> 65 Base layout of a handheld notification and the same notification on Wear, 66 with a user photo and a notification icon 67 </p> 68 </div> 69 </div> 70 71 <h3 id="ExpandedLayouts">Expanded layouts</h3> 72 73 74 <p>You have the option to provide more details on notifications. You can use this to show the first 75 few lines of a message or show a larger image preview. This provides the user with additional 76 context, and - in some cases - may allow the user to read a message in its entirety. The user can 77 pinch-zoom or perform a single-finger glide in order to toggle between compact and expanded layouts. 78 For single event notifications, Android provides three expanded layout templates (text, inbox, and 79 image) for you to re-use in your application. The following images show you how they look on 80 handhelds and wearables.</p> 81 82 <img style="margin-top:30px" src="{@docRoot}preview/images/notifications/expandedtext_combo.png" 83 alt="" width="700px" height;="284px" /> 84 <img style="margin-top:30px" src="{@docRoot}preview/images/notifications/stack_combo.png" 85 alt="" width="700px" height;="284px" /> 86 <img style="margin-top:30px" src="{@docRoot}preview/images/notifications/ExpandedImage.png" 87 alt="" width="311px" height;="450px" /> 88 89 <h3 id="actions" style="clear:both; margin-top:40px">Actions</h3> 90 91 <p>Android has supported optional actions that are displayed at the bottom of the notification, as 92 far back as Jelly Bean. With actions, users can handle the most common tasks for a particular 93 notification from within the notification shade without having to open the originating application. 94 This speeds up interaction and, in conjunction with "swipe-to-dismiss", helps users to streamline 95 their notification triaging experience.</p> 96 97 98 <img src="{@docRoot}preview/images/notifications/action_combo.png" 99 alt="" width="700px" /> 100 101 102 103 <p style="clear:both">Be judicious with how many actions you include with a notification. The more 104 actions you include, the more cognitive complexity you create. Limit yourself to the fewest number 105 of actions possible by only including the most imminently important and meaningful ones.</p> 106 107 <p>Good candidates for actions on notifications are actions that:</p> 108 109 <ul> 110 <li> Are essential, frequent and typical for the content type you're displaying 111 <li> Allow the user to accomplish tasks quickly 112 </ul> 113 114 <p>Avoid actions that are:</p> 115 116 <ul> 117 <li> Ambiguous 118 <li> Duplicative of the default action of the notification (such as "Read" or "Open") 119 </ul> 120 121 122 123 <p>You can specify a maximum of three actions, each consisting of an action icon and an action name. 124 Adding actions to a simple base layout will make the notification expandable, even if the 125 notification doesn't have an expanded layout. Since actions are only shown for expanded 126 notifications and are otherwise hidden, you must make sure that any action a user can invoke from 127 a notification is available from within the associated application as well.</p> 128 129 <h2 id="notifications_on_android_wear">Notifications on Android Wear</h2> 130 131 <p>Additionally, notifications and their actions are bridged over to Wear devices by default. 132 Developers have control to control which notifications from bridging from the phone to the watch 133 and vice versa. And developers can control which actions bridge as well. If your app includes 134 actions that can't be accomplished with a single tap, either hide these actions on your Wear 135 notification or consider hooking them up to a Wear app to allow the user to finish the action on 136 their watch.</p> 137 138 <h4>Bridging notifications</h4> 139 140 <p><strong>Notifications that should be bridged</strong></p> 141 142 <ul> 143 <li> New instant messages</li> 144 </ul> 145 146 <img src="{@docRoot}preview/images/notifications/WearBasic.png" width="156px" height="156px" 147 alt="" /> 148 149 <p><strong>Don't bridge</strong></p> 150 151 <ul> 152 <li> If a podcasting app has new episodes available for download, 153 keep this notification on the phone.</li> 154 </ul> 155 156 157 158 <h4 style="clear:both">Bridging actions</h4></p> 159 160 <p><strong>Actions to bridge</strong></p> 161 162 <ul> 163 <li> Single tap actions such as +1, Like, Heart</li> 164 </ul> 165 166 <p><strong>Actions not to bridge</strong></p> 167 168 <ul> 169 <li> Actions that map to features that aren't possible on the watch</li> 170 </ul> 171 172 173 174 <p><b>Unique actions to define for Wear</b></p> 175 176 <ul> 177 <li> Quick lists of canned responses such as "Be right back"</li> 178 <li> Open on phone</li> 179 <li> A "Comment" or "Reply" action that brings up the speech input screen</li> 180 <li> Actions that can launch Wear-specific apps</li> 181 </ul> 182 183 <img src="{@docRoot}preview/images/notifications/ReplyAction.png" width="156px" height="156px" 184 alt="" /> 185 186 187 </div> 188 189 190 191 <h2 style="clear:left">Heads-up Notification</h2> 192 <div class="figure" style="width:311px"> 193 <img src="{@docRoot}preview/images/notifications/Headsup.png" 194 alt="" width="311px" /> 195 <p class="img-caption"> 196 Example of a Heads-up notification (incoming phone call, high priority) coming in on top of an 197 immersive app 198 </p> 199 </div> 200 201 <p>When notifications with priority set to High (see right) arrives, it is presented to users for a 202 short period of time on the device with an expanded layout with its actions exposed.</p> 203 <p> After this period of time, it retreats back to the Notification shade. If a notification is 204 flagged as High or Max or a full-screen takeover, it gets a HUN in L.</p> 205 206 <p><b>Good examples of Heads-up notifications</b></p> 207 208 <ul> 209 <li> Incoming phone call when using device</li> 210 <li> Alarm when using device</li> 211 <li> New SMS message</li> 212 <li> Low battery</li> 213 </ul> 214 215 <h2 style="clear:both" id="guidelines">Guidelines</h2> 216 217 218 <h3 id="MakeItPersonal">Make it personal</h3> 219 220 <p>For notifications of items sent by another person (such as a message or status update), include 221 that person's image using setLargeIcon. Also attach information about the person to the 222 notification's metadata (see EXTRA_PEOPLE).</p> 223 224 <p>Your notification's main icon will still be shown, so the user can associate it with the icon 225 visible in the status bar.</p> 226 227 228 <img src="{@docRoot}preview/images/notifications/Triggered.png" 229 alt="" width="311px"/> 230 <p style="margin-top:10px" class="img-caption"> 231 Notification that shows the person who triggered it and the content they are sending you 232 </p> 233 234 235 <h3 id="navigate_to_the_right_place">Navigate to the right place</h3> 236 237 <p>When the user touches the body of a notification (outside of the action buttons), open your app 238 to the place where the user can view and act upon the data referenced in the notification. In most 239 cases this will be the detail view of a single data item such as a message, but it might also be a 240 summary view if the notification is stacked (see <em>Stacked notifications</em> below) and 241 references multiple items. If in any of those cases the user is taken to a hierarchy level below 242 your app's top-level, insert navigation into your app's back stack to allow them to navigate to 243 your app's top level using the system back button. For more information, see the chapter on 244 <em>System-to-app navigation</em> in the <a href="/design/patterns/navigation.html">Navigation</a> 245 design pattern.</p> 246 247 <h3 id="correctly_set_and_manage_notification_priority">Correctly set and manage notification 248 priority</h3> 249 250 <p>Starting with Jelly Bean, Android supported a priority flag for notifications. It allows you to 251 influence where your notification will appear in comparison to other notifications and help to make 252 sure that users always see their most important notifications first. You can choose from the 253 following priority levels when posting a notification:</p> 254 <table> 255 <tr> 256 <td class="tab0"> 257 <p><strong>Priority</strong></p> 258 </td> 259 <td class="tab0"> 260 <p><strong>Use</strong></p> 261 </td> 262 </tr> 263 <tr> 264 <td class="tab1"> 265 <p><code>MAX</code></p> 266 </td> 267 <td class="tab1"> 268 <p>Use for critical and urgent notifications that alert the user to a condition that is 269 time-critical or needs to be resolved before they can continue with a particular task.</p> 270 </td> 271 </tr> 272 <tr> 273 <td class="tab1"> 274 <p><code>HIGH</code></p> 275 </td> 276 <td class="tab1"> 277 <p>Use high priority notifications primarily for important communication, such as message or chat 278 events with content that is particularly interesting for the user. High priority notifications will get the Heads-Up Notification display starting in L.</p> 279 </td> 280 </tr> 281 <tr> 282 <td class="tab1"> 283 <p><code>DEFAULT</code></p> 284 </td> 285 <td class="tab1"> 286 <p>The default priority. Keep all notifications that don't fall into any of the other categories at 287 this priority level.</p> 288 </td> 289 </tr> 290 <tr> 291 <td class="tab1"> 292 <p><code>LOW</code></p> 293 </td> 294 <td class="tab1"> 295 <p>Use for notifications that you still want the user to be informed about, but that rate low in 296 urgency. LOW notifications will tend to show up at the bottom of the list, which makes them a good 297 choice for things like pubic/undirected social updates: the user has asked to be notified about 298 them, but they should never take precedence over urgent or direct communication.</p> 299 </td> 300 </tr> 301 <tr> 302 <td class="tab1"> 303 <p><code>MIN</code></p> 304 </td> 305 <td class="tab1"> 306 <p>Contextual/background information (e.g. weather information, contextual location information). 307 Minimum priority notifications will not show in the status bar. The user will only discover them 308 when they expand the notification shade.</p> 309 </td> 310 </tr> 311 </table> 312 313 314 <h4 id="how_to_choose_an_appropriate_priority"><strong>How to choose an appropriate 315 priority</strong></h4> 316 317 <p>Default, High, and Max priority are interruptive priority levels and risk interrupting the user 318 from what they are doing. This should not be taken lightly, so these levels should be reserved 319 for notifications that:</p> 320 321 <ul> 322 <li> Involve another person</li> 323 <li> Are time-sensitive</li> 324 <li> Might immediately change the user's behavior in the real world</li> 325 </ul> 326 327 <p>Notifications set to <code>LOW</code> and <code>MIN</code> can still be very valuable for the 328 user. Many if not most notifications just don't need to command the user's immediate attention, or 329 vibrate the user's wrist, yet contain information that they will find valuable when they choose to 330 look for notifications. Criteria for <code>LOW</code> and <code>MIN</code> priority notifications:</p> 331 332 <ul> 333 <li> Don't involve other people</li> 334 <li> Aren't time sensitive</li> 335 <li> Is content the user might be interested in but could choose to browse at their leisure</li> 336 </ul> 337 338 339 <img src="{@docRoot}preview/images/notifications/notifications_pattern_priority.png" 340 alt="" width="700"/> 341 342 343 <h3 style="clear:both" id="set_a_notification_category">Set a notification category</h3> 344 345 <p>If your notification falls into one of the predefined categories (see below), assign it 346 accordingly. Aspects of the system UI such as the notification shade (or any other notification 347 listener) may use this information to make ranking and filtering decisions.</p> 348 <table> 349 <tr> 350 <td> 351 <p><code>Notification.CATEGORY_CALL</code></p> 352 </td> 353 <td> 354 <p>Incoming call (voice or video) or similar synchronous communication request</p> 355 </td> 356 </tr> 357 <tr> 358 <td> 359 <p><code>Notification.CATEGORY_MESSAGE</code></p> 360 </td> 361 <td> 362 <p>Incoming direct message (SMS, instant message, etc.)</p> 363 </td> 364 </tr> 365 <tr> 366 <td> 367 <p><code>Notification.CATEGORY_EMAIL</code></p> 368 </td> 369 <td> 370 <p>Asynchronous bulk message (email)</p> 371 </td> 372 </tr> 373 <tr> 374 <td> 375 <p><code>Notification.CATEGORY_EVENT</code></p> 376 </td> 377 <td> 378 <p>Calendar event</p> 379 </td> 380 </tr> 381 <tr> 382 <td> 383 <p><code>Notification.CATEGORY_PROMO</code></p> 384 </td> 385 <td> 386 <p>Promotion or advertisement</p> 387 </td> 388 </tr> 389 <tr> 390 <td> 391 <p><code>Notification.CATEGORY_ALARM</code></p> 392 </td> 393 <td> 394 <p>Alarm or timer</p> 395 </td> 396 </tr> 397 <tr> 398 <td> 399 <p><code>Notification.CATEGORY_PROGRESS</code></p> 400 </td> 401 <td> 402 <p>Progress of a long-running background operation</p> 403 </td> 404 </tr> 405 <tr> 406 <td> 407 <p><code>Notification.CATEGORY_SOCIAL</code></p> 408 </td> 409 <td> 410 <p>Social network or sharing update</p> 411 </td> 412 </tr> 413 <tr> 414 <td> 415 <p><code>Notification.CATEGORY_ERROR</code></p> 416 </td> 417 <td> 418 <p>Error in background operation or authentication status</p> 419 </td> 420 </tr> 421 <tr> 422 <td> 423 <p><code>Notification.CATEGORY_TRANSPORT</code></p> 424 </td> 425 <td> 426 <p>Media transport control for playback</p> 427 </td> 428 </tr> 429 <tr> 430 <td> 431 <p><code>Notification.CATEGORY_SYSTEM</code></p> 432 </td> 433 <td> 434 <p>System or device status update. Reserved for system use.</p> 435 </td> 436 </tr> 437 <tr> 438 <td> 439 <p><code>Notification.CATEGORY_SERVICE</code></p> 440 </td> 441 <td> 442 <p>Indication of running background service</p> 443 </td> 444 </tr> 445 <tr> 446 <td> 447 <p><code>Notification.CATEGORY_RECOMMENDATION</code></p> 448 </td> 449 <td> 450 <p>A specific, timely recommendation for a single thing. For example, a news app might want to 451 recommend a news story it believes the user will want to read next.</p> 452 </td> 453 </tr> 454 <tr> 455 <td> 456 <p><code>Notification.CATEGORY_STATUS</code></p> 457 </td> 458 <td> 459 <p>Ongoing information about device or contextual status</p> 460 </td> 461 </tr> 462 </table> 463 464 <h3 id="summarize_your_notifications">Summarize your notifications</h3> 465 466 <p>If your app creates a notification while another of the same type is still pending, avoid 467 creating an altogether new notification object. Instead, turn it into a summary notification for 468 the app.</p> 469 470 <p>A summary notification builds a summary description and allows the user to understand how many 471 notifications of a particular kind are pending.</p> 472 473 <div class="col-6"> 474 475 <p><strong>Don't</strong></p> 476 <img src="{@docRoot}preview/images/notifications/Summarise_Dont.png" 477 alt="" width="311px" /> 478 </div> 479 480 <div> 481 <p><strong>Do</strong></p> 482 483 <img src="{@docRoot}preview/images/notifications/Summarise_Do.png" 484 alt="" width="311px"/> 485 </div> 486 487 <p style="clear:left; padding-top:30px; padding-bottom:20px">You can provide more detail about the individual notifications that make up a 488 summary by using the expanded digest layout. This allows users to gain a better sense of which 489 notifications are pending and if they are interesting enough to be read in detail within the 490 associated app.</p> 491 <div class="col-6"> 492 <img src="{@docRoot}preview/images/notifications/Stack.png" style="margin-bottom:20px" 493 alt="" width="311px" /> 494 <p class="img-caption"> 495 Expanded and contracted notification that is a summary (using InboxStyle) 496 </p> 497 </div> 498 499 <h3 style="clear:both" id="make_notifications_optional">Make notifications optional</h3> 500 501 <p>Users should always be in control of notifications. Allow the user to disable your app's 502 notifications or change their alert properties, such as alert sound and whether to use vibration, 503 by adding a notification settings item to your application settings.</p> 504 505 <h3 id="use_distinct_icons">Use distinct icons</h3> 506 <p>By glancing at the notification area, the user should be able to discern what kinds of 507 notifications are currently pending.</p> 508 509 <div class="figure"> 510 <img src="{@docRoot}preview/images/notifications/ProductIcons.png" 511 alt="" width="420" /> 512 </div> 513 514 <div><p><strong>Do</strong></p> 515 <p>Look at the notification icons Android apps already provide and create notification icons for 516 your app that are sufficiently distinct in appearance.</p> 517 518 <p><strong>Do</strong></p> 519 <p>Use the proper <a href="/design/style/iconography.html#notification">notification icon 520 style</a> for small icons, and the Material Light 521 <a href="/design/style/iconography.html#action-bar">action bar icon style</a> for your action 522 icons. Do not place any additional alpha (dimming or fading) into your small icons and action 523 icons; they can have anti-aliased edges, but because L uses these icons as masks (that is, only 524 the alpha channel is used), the image should generally be drawn at full opacity.</p> 525 <p ><strong>Do</strong></p> 526 <p >Keep your icons visually simple and avoid excessive detail that is hard to discern.</p> 527 528 </div> 529 <p style="clear:both"><strong>Don't</strong></p> 530 531 <p>Use color to distinguish your app from others. Notification icons should only be a white-on-transparent background image.</p> 532 533 534 <h3 id="pulse_the_notification_led_appropriately">Pulse the notification LED appropriately</h3> 535 536 <p>Many Android devices contain a notification LED, which is used to keep the user informed about 537 events while the screen is off. Notifications with a priority level of MAX, HIGH, or DEFAULT should 538 cause the LED to glow, while those with lower priority (<code>LOW</code> and <code>MIN</code>) should not.</p> 539 540 <p>The user's control over notifications should extend to the LED. When you use DEFAULT_LIGHTS, the 541 LED will glow with a white color. Your notifications shouldn't use a different color unless the 542 user has explicitly customized it.</p> 543 544 <h2 id="building_notifications_that_users_care_about">Building notifications that users care about</h2> 545 546 <p>To create an app that users love, it is important to design your notifications carefully. 547 Notifications embody your app's voice, and contribute to your app's personality. Unwanted or 548 unimportant notifications can annoy the user or make them resent how much attention the app wants 549 from them, so use notifications judiciously.</p> 550 551 <h3 id="when_to_display_a_notification">When to display a notification</h3> 552 553 <p>To create an application that people enjoy using, it's important to recognize that the user's 554 attention and focus is a resource that must be protected. While Android's notification system has 555 been designed to minimize the impact of notifications on the user's attention, it is nonetheless 556 still important to be aware of the fact that notifications are interrupting the user's task flow. 557 As you plan your notifications, ask yourself if they are important enough to warrant an interruption. If you are unsure, allow the user to opt into a notification using your apps notification settings or adjust 558 the notifications priority flag to <code>LOW</code> or <code>MIN</code> to avoid distracting the user while they are doing 559 something else.</p> 560 561 <img src="{@docRoot}preview/images/notifications/TimeSensitive.png" 562 alt="" width="311px" /> 563 <p style="margin-top:10px" class="img-caption"> 564 Time sensitive notification examples 565 </p> 566 567 <p>While well behaved apps generally only speak when spoken to, there are some limited cases where an app actually should interrupt the user with an unprompted notification.</p> 568 569 <p>Notifications should be used primarily for <strong>time sensitive events</strong>, and especially 570 if these synchronous events <strong>involve other people</strong>. For instance, an incoming chat 571 is a real time and synchronous form of communication: there is another user actively waiting on you 572 to respond. Calendar events are another good example of when to use a notification and grab the 573 user's attention, because the event is imminent, and calendar events often involve other people.</p> 574 575 <h3 style="clear:both" id="when_not_to_display_a_notification">When not to display a notification</h3> 576 577 <div class="figure" style="margin-top:60px"> 578 <img src="{@docRoot}preview/images/notifications/AntiSample1.png" 579 alt="" width="311px" /> 580 </div> 581 582 <p>There are however many other cases where notifications should not be used:</p> 583 584 <ul> 585 <li> Avoid notifying the user of information that is not directed specifically at them, or 586 information that is not truly time sensitive. For instance the asynchronous and undirected updates 587 flowing through a social network generally do not warrant a real time interruption. For the users 588 that do care about them, allow them to opt-in.</li> 589 <li> Don't create a notification if the relevant new information is currently on screen. Instead, 590 use the UI of the application itself to notify the user of new information directly in context. 591 For instance, a chat application should not create system notifications while the user is actively chatting with another user.</li> 592 <li> Don't interrupt the user for low level technical operations, like saving or syncing information, or updating an application, if it is possible for the system to simply take care of itself without involving the user.</li> 593 <li> Don't interrupt the user to inform them of an error if it is possible for the application to recover from the error on its own without the user taking any action.</li> 594 <li> Don't create notifications that have no true notification content and merely advertise your 595 app. A notification should provide useful, timely, new information and should not be used to 596 merely launch an app.</li> 597 <li> Don't create superfluous notifications just to get your brand in front of users. 598 Such notifications will only frustrate and likely alienate your audience. The best way to provide 599 the user with a small amount of updated information and to keep them engaged with your 600 application is to develop a widget that they can choose to place on their home screen.</li> 601 </ul> 602 603 <h2 style="clear:left" id="interacting_with_notifications">Interacting With Notifications</h2> 604 605 <p>Notifications are indicated by icons in the status bar and can be accessed by opening the 606 notification drawer.</p> 607 608 <p>Touching a notification opens the associated app to detailed content matching the notification. 609 Swiping left or right on a notification removes it from the list.</p> 610 611 <h3 id="ongoing_notifications">Ongoing notifications</h3> 612 <div class="figure" style="width:311px"> 613 <img src="{@docRoot}preview/images/notifications/MusicPlayback.png" 614 alt="" width="311px" /> 615 <p class="img-caption"> 616 Ongoing notification due to music playback 617 </p> 618 </div> 619 <p>Ongoing notifications keep users informed about an ongoing process in the background. 620 For example, music players announce the currently playing track in the notification system and 621 continue to do so until the user stops the playback. They can also be used to show the user 622 feedback for longer tasks like downloading a file, or encoding a video. Ongoing notifications 623 cannot be manually removed from the notification drawer.</p> 624 625 <p>The L lockscreen doesn't show transport controls for RCC (RemoteControlClient)s anymore. But the 626 lockscreen <em>does</em> show notifications, so each app's playback notification is now the primary 627 way for users to control playback from a locked state. This gives apps more control over which 628 buttons to show and in what way, while providing a consistent experience for the user whether on 629 the lockscreen or unlocked.</p> 630 631 <h3 style="clear:both" id="dialogs_and_toasts_are_for_feedback_not_notification">Dialogs 632 and toasts are for feedback not notifications</h3> 633 634 <p>Your app should not create a dialog or toast if it is not currently on screen. Dialogs and Toasts 635 should only be displayed as the immediate response to the user taking an action inside of your app. 636 For further guidance on the use of dialogs and toasts, refer to 637 <a href="/design/patterns/confirming-acknowledging.html">Confirming & Acknowledging</a>.</p> 638 639 <h3>Ranking and Ordering</h3> 640 641 <p>Notifications are "news" and so they are essentially shown in reverse-chronological order, with 642 special consideration given to the app's stated notification priority.</p> 643 644 <p>In L, notifications are now a key part of the lockscreen, and are featured prominently every 645 time the device display comes on. Because space on the lockscreen is tight, it is more important 646 than ever to identify the most urgent or relevant notifications.</p> 647 648 <p>Therefore, L has a more sophisticated sorting algorithm for notifications, taking into account:</p> 649 650 <ul> 651 <li> The timestamp and application's stated priority, as before.</li> 652 <li> Whether the notification has recently disturbed the user with sound or vibration. (That is, 653 if the phone just made noise, and the user wants to know "what just happened?" the lockscreen 654 should answer that at a glance.)</li> 655 <li> Any people that are attached to the notification using <code>EXTRA_PEOPLE</code>, and in 656 particular whether those are starred contacts.</li> 657 </ul> 658 659 <p>To best take advantage of this sorting, developers should focus on the user experience they want 660 to create rather than aiming for any particular spot on the list.</p> 661 662 <img src="{@docRoot}preview/images/notifications/AntiSample3.png" 663 alt="" width="700px" /> 664 665 <p class="img-caption" style="margin-top:10px">Gmail notifications are default priority, so they 666 normally sort below messages from an instant messaging app like Hangouts, but Gmail will get a 667 temporary bump when new messages come in. 668 </p> 669 670 671 <h3>On the lockscreen</h3> 672 673 <p>Starting in L, notifications are visible on the lockscreen, and so we must consider the user's 674 privacy. Notifications often contain sensitive information, and we must take care when showing it to 675 anyone who picks up the device and turns on the display.</p> 676 677 <ul> 678 <li> For devices without a secure lockscreen, a simple slide gesture unlocks the whole device. 679 Therefore, Android will always show the complete contents of all notifications on insecure lockscreens.</li> 680 <li> When a device has a secure lockscreen (PIN, pattern, or password), however, it divides the 681 interface into two spheres: "public", the things that are displayed atop a secure lockscreen and 682 can therefore be seen by anyone; and "private", the world behind that lockscreen, which can only 683 be accessed by supplying the correct authentication.</li> 684 </ul> 685 686 <h3>The user decides what shows on the secure lockscreen</h3> 687 <div class="figure" style="width:311px"> 688 <img src="{@docRoot}preview/images/notifications/LockScreen.png" 689 alt="" width="311px" /> 690 <p class="img-caption"> 691 Notifications on the lockscreen followed by the Pattern Unlock when the user attempts to unlock the phone. 692 </p> 693 </div> 694 695 <p>When setting up a secure lockscreen, the user can choose to conceal sensitive details from atop the secure lockscreen. In this case the SystemUI considers the notification's <em>visibility level</em> to figure out what can safely be shown.</p> 696 <p> To control the visibility level, call 697 <code>Notification.Builder.setVisibility()</code> and specify one of these values:</p> 698 699 <ul> 700 <li><code>Notification.VISIBILITY_PUBLIC</code>. Shows the notification's full content. 701 This is the system default if visibility is left unspecified.</li> 702 <li><code>Notification.VISIBILITY_PRIVATE</code>. The lockscreen will reveal basic information about the existence of this notification, including its icon and the name of the app that posted it. The rest of the notification's details, however, are not displayed. 703 <ul> 704 <li> If you want to provide a different public version of your notification for the system to display on a secure lockscreen, supply a replacement Notification object in the <code>Notification.publicVersion</code> field. 705 <li> This is an app's opportunity to create a redacted version of the content that is still useful but does not reveal personal information. 706 <li> <strong>Example: </strong>An SMS app whose notifications include the text of the SMS and the sender's name and contact icon. This notification should be <code>VISIBILITY_PRIVATE</code>, but the <code>publicVersion</code> could still contain useful information like "3 new messages" without any other identifying details. 707 </ul> 708 </li> 709 <li><code>Notification.VISIBILITY_SECRET</code>. Shows only the most minimal information, excluding even the notification's icon.</li> 710 </ul>