Building a Notification

This lesson explains how to create and issue a notification.

The examples in this class are based on the NotificationCompat.Builder class. NotificationCompat.Builder is in the Support Library. You should use NotificationCompat and its subclasses, particularly NotificationCompat.Builder, to provide the best notification support for a wide range of platforms.

Create a Notification Builder

When creating a notification, specify the UI content and actions with a NotificationCompat.Builder object. At bare minimum, a Builder object must include the following:

• A small icon, set by setSmallIcon()
• A title, set by setContentTitle()
• Detail text, set by setContentText()

For example:

NotificationCompat.Builder mBuilder =
    new NotificationCompat.Builder(this)
    .setSmallIcon(R.drawable.notification_icon)
    .setContentTitle("My notification")
    .setContentText("Hello World!");

Define the Notification's Action

Although actions are optional, you should add at least one action to your notification. An action takes users directly from the notification to an Activity in your application, where they can look at the event that caused the notification or do further work. Inside a notification, the action itself is defined by a PendingIntent containing an Intent that starts an Activity in your application.

How you construct the PendingIntent depends on what type of Activity you're starting. When you start an Activity from a notification, you must preserve the user's expected navigation experience. In the snippet below, clicking the notification opens a new activity that effectively extends the behavior of the notification. In this case there is no need to create an artificial back stack (see Preserving Navigation when Starting an Activity for more information):

Intent resultIntent = new Intent(this, ResultActivity.class);
...
// Because clicking the notification opens a new ("special") activity, there's
// no need to create an artificial back stack.
PendingIntent resultPendingIntent =
    PendingIntent.getActivity(
    this,
    0,
    resultIntent,
    PendingIntent.FLAG_UPDATE_CURRENT
);

Set the Notification's Click Behavior

To associate the PendingIntent created in the previous step with a gesture, call the appropriate method of NotificationCompat.Builder. For example, to start an activity when the user clicks the notification text in the notification drawer, add the PendingIntent by calling setContentIntent(). For example:

PendingIntent resultPendingIntent;
...
mBuilder.setContentIntent(resultPendingIntent);

Issue the Notification

To issue the notification:

• Get an instance of NotificationManager.
• Use the notify() method to issue the notification. When you call notify(), specify a notification ID. You can use this ID to update the notification later on. This is described in more detail in Managing Notifications.
• Call build(), which returns a Notification object containing your specifications.

For example:

NotificationCompat.Builder mBuilder;
...
// Sets an ID for the notification
int mNotificationId = 001;
// Gets an instance of the NotificationManager service
NotificationManager mNotifyMgr = 
        (NotificationManager) getSystemService(NOTIFICATION_SERVICE);
// Builds the notification and issues it.
mNotifyMgr.notify(mNotificationId, mBuilder.build());