1 page.title=Building a Notification 2 parent.title=Notifying the User 3 parent.link=index.html 4 5 trainingnavtop=true 6 next.title=Preserving Navigation when Starting an Activity 7 next.link=navigation.html 8 9 @jd:body 10 11 <div id="tb-wrapper"> 12 <div id="tb"> 13 14 <!-- table of contents --> 15 <h2>This lesson teaches you to</h2> 16 <ol> 17 <li><a href="#builder">Create a Notification Builder</a></li> 18 <li><a href="#action">Define the Notification's Action</a></li> 19 <li><a href="#click">Set the Notification's Click Behavior</a></li> 20 <li><a href="#notify">Issue the Notification</a></li> 21 </ol> 22 23 <!-- other docs (NOT javadocs) --> 24 <h2>You should also read</h2> 25 26 <ul> 27 <li> 28 <a href="{@docRoot}guide/topics/ui/notifiers/notifications.html">Notifications</a> API Guide 29 </li> 30 <li> 31 <a href="{@docRoot}guide/components/intents-filters.html"> 32 Intents and Intent Filters 33 </a> 34 </li> 35 <li> 36 <a href="{@docRoot}design/patterns/notifications.html">Notifications</a> Design Guide 37 </li> 38 </ul> 39 40 41 </div> 42 </div> 43 44 45 <p>This lesson explains how to create and issue a notification.</p> 46 47 <p>The examples in this class are based on the 48 {@link android.support.v4.app.NotificationCompat.Builder} class. 49 {@link android.support.v4.app.NotificationCompat.Builder} 50 is in the <a href="{@docRoot}">Support Library</a>. You should use 51 {@link android.support.v4.app.NotificationCompat} and its subclasses, 52 particularly {@link android.support.v4.app.NotificationCompat.Builder}, to 53 provide the best notification support for a wide range of platforms. </p> 54 55 <h2 id="builder">Create a Notification Builder</h2> 56 57 <p>When creating a notification, specify the UI content and actions with a 58 {@link android.support.v4.app.NotificationCompat.Builder} object. At bare minimum, 59 a {@link android.support.v4.app.NotificationCompat.Builder Builder} 60 object must include the following:</p> 61 62 <ul> 63 <li> 64 A small icon, set by 65 {@link android.support.v4.app.NotificationCompat.Builder#setSmallIcon setSmallIcon()} 66 </li> 67 <li> 68 A title, set by 69 {@link android.support.v4.app.NotificationCompat.Builder#setContentTitle setContentTitle()} 70 </li> 71 <li> 72 Detail text, set by 73 {@link android.support.v4.app.NotificationCompat.Builder#setContentText setContentText()} 74 </li> 75 </ul> 76 <p> For example: </p> 77 <pre> 78 NotificationCompat.Builder mBuilder = 79 new NotificationCompat.Builder(this) 80 .setSmallIcon(R.drawable.notification_icon) 81 .setContentTitle("My notification") 82 .setContentText("Hello World!"); 83 </pre> 84 85 <h2 id="action">Define the Notification's Action</h2> 86 87 88 <p>Although actions are optional, you should add at least one action to your 89 notification. An action takes users directly from the notification to an 90 {@link android.app.Activity} in your application, where they can look at the 91 event that caused the notification or do further work. Inside a notification, the action itself is 92 defined by a {@link android.app.PendingIntent} containing an {@link 93 android.content.Intent} that starts an {@link android.app.Activity} in your 94 application.</p> 95 96 <p>How you construct the {@link android.app.PendingIntent} depends on what type 97 of {@link android.app.Activity} you're starting. When you start an {@link 98 android.app.Activity} from a notification, you must preserve the user's expected 99 navigation experience. In the snippet below, clicking the notification opens a 100 new activity that effectively extends the behavior of the notification. In this 101 case there is no need to create an artificial back stack (see 102 <a href="navigation.html">Preserving Navigation when Starting an Activity</a> for 103 more information):</p> 104 105 <pre>Intent resultIntent = new Intent(this, ResultActivity.class); 106 ... 107 // Because clicking the notification opens a new ("special") activity, there's 108 // no need to create an artificial back stack. 109 PendingIntent resultPendingIntent = 110 PendingIntent.getActivity( 111 this, 112 0, 113 resultIntent, 114 PendingIntent.FLAG_UPDATE_CURRENT 115 ); 116 </pre> 117 118 <h2 id="click">Set the Notification's Click Behavior</h2> 119 120 <p> 121 To associate the {@link android.app.PendingIntent} created in the previous 122 step with a gesture, call the appropriate method of {@link 123 android.support.v4.app.NotificationCompat.Builder}. For example, to start an 124 activity when the user clicks the notification text in the notification drawer, 125 add the {@link android.app.PendingIntent} by calling {@link 126 android.support.v4.app.NotificationCompat.Builder#setContentIntent 127 setContentIntent()}. For example:</p> 128 129 <pre>PendingIntent resultPendingIntent; 130 ... 131 mBuilder.setContentIntent(resultPendingIntent);</pre> 132 133 <h2 id="notify">Issue the Notification</h2> 134 135 <p>To issue the notification:</p> 136 <ul> 137 <li>Get an instance of {@link android.app.NotificationManager}.</li> 138 139 <li>Use the {@link android.app.NotificationManager#notify notify()} method to issue the 140 notification. When you call {@link android.app.NotificationManager#notify notify()}, specify a notification ID. 141 You can use this ID to update the notification later on. This is described in more detail in 142 <a href="managing.html">Managing Notifications</a>.</li> 143 144 <li>Call {@link 145 android.support.v4.app.NotificationCompat.Builder#build() build()}, which 146 returns a {@link android.app.Notification} object containing your 147 specifications.</li> 148 149 <p>For example:</p> 150 151 <pre> 152 NotificationCompat.Builder mBuilder; 153 ... 154 // Sets an ID for the notification 155 int mNotificationId = 001; 156 // Gets an instance of the NotificationManager service 157 NotificationManager mNotifyMgr = 158 (NotificationManager) getSystemService(NOTIFICATION_SERVICE); 159 // Builds the notification and issues it. 160 mNotifyMgr.notify(mNotificationId, mBuilder.build()); 161 </pre> 162 163
