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