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