1page.title=Building a Notification 2parent.title=Notifying the User 3parent.link=index.html 4 5trainingnavtop=true 6next.title=Preserving Navigation when Starting an Activity 7next.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} 50is in the <a href="{@docRoot}">Support Library</a>. You should use 51{@link android.support.v4.app.NotificationCompat} and its subclasses, 52particularly {@link android.support.v4.app.NotificationCompat.Builder}, to 53provide 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, 59a {@link android.support.v4.app.NotificationCompat.Builder Builder} 60object 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> 78NotificationCompat.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 89notification. An action takes users directly from the notification to an 90{@link android.app.Activity} in your application, where they can look at the 91event that caused the notification or do further work. Inside a notification, the action itself is 92defined by a {@link android.app.PendingIntent} containing an {@link 93android.content.Intent} that starts an {@link android.app.Activity} in your 94application.</p> 95 96<p>How you construct the {@link android.app.PendingIntent} depends on what type 97of {@link android.app.Activity} you're starting. When you start an {@link 98android.app.Activity} from a notification, you must preserve the user's expected 99navigation experience. In the snippet below, clicking the notification opens a 100new activity that effectively extends the behavior of the notification. In this 101case there is no need to create an artificial back stack (see 102<a href="navigation.html">Preserving Navigation when Starting an Activity</a> for 103more 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. 109PendingIntent 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> 121To associate the {@link android.app.PendingIntent} created in the previous 122step with a gesture, call the appropriate method of {@link 123android.support.v4.app.NotificationCompat.Builder}. For example, to start an 124activity when the user clicks the notification text in the notification drawer, 125add the {@link android.app.PendingIntent} by calling {@link 126android.support.v4.app.NotificationCompat.Builder#setContentIntent 127setContentIntent()}. For example:</p> 128 129<pre>PendingIntent resultPendingIntent; 130... 131mBuilder.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 140notification. When you call {@link android.app.NotificationManager#notify notify()}, specify a notification ID. 141You 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 145android.support.v4.app.NotificationCompat.Builder#build() build()}, which 146returns a {@link android.app.Notification} object containing your 147specifications.</li> 148 149<p>For example:</p> 150 151<pre> 152NotificationCompat.Builder mBuilder; 153... 154// Sets an ID for the notification 155int mNotificationId = 001; 156// Gets an instance of the NotificationManager service 157NotificationManager mNotifyMgr = 158 (NotificationManager) getSystemService(NOTIFICATION_SERVICE); 159// Builds the notification and issues it. 160mNotifyMgr.notify(mNotificationId, mBuilder.build()); 161</pre> 162 163