THIS LESSON TEACHES YOU TO

1. Create a Notification Builder
2. Define the Notification's Action
3. Set the Notification's Click Behavior
4. Issue the Notification

YOU SHOULD ALSO READ

• Notifications API Guide
• Intents and Intent Filters
• Notifications Design Guide

Part of designing a notification is preserving the user's expected navigation experience. For a detailed discussion of this topic, see the Notifications API guide. There are two general situations:

Regular activity

You're starting an Activity that's part of the application's normal workflow.

Special activity

The user only sees this Activity if it's started from a notification. In a sense, the Activity extends the notification by providing information that would be hard to display in the notification itself.

Set Up a Regular Activity PendingIntent

To set up a PendingIntent that starts a direct entry Activity, follow these steps:

1. Define your application's Activity hierarchy in the manifest. The final XML should look like this:

   <activity
       android:name=".MainActivity"
       android:label="@string/app_name" >
       <intent-filter>
           <action android:name="android.intent.action.MAIN" />
           <category android:name="android.intent.category.LAUNCHER" />
       </intent-filter>
   </activity>
   <activity
       android:name=".ResultActivity"
       android:parentActivityName=".MainActivity">
       <meta-data
           android:name="android.support.PARENT_ACTIVITY"
           android:value=".MainActivity"/>
   </activity>

2. Create a back stack based on the Intent that starts the Activity. For example:

   int id = 1;
   ...
   Intent resultIntent = new Intent(this, ResultActivity.class);
   TaskStackBuilder stackBuilder = TaskStackBuilder.create(this);
   // Adds the back stack
   stackBuilder.addParentStack(ResultActivity.class);
   // Adds the Intent to the top of the stack
   stackBuilder.addNextIntent(resultIntent);
   // Gets a PendingIntent containing the entire back stack
   PendingIntent resultPendingIntent =
           stackBuilder.getPendingIntent(0, PendingIntent.FLAG_UPDATE_CURRENT);
   ...
   NotificationCompat.Builder builder = new NotificationCompat.Builder(this);
   builder.setContentIntent(resultPendingIntent);
   NotificationManager mNotificationManager =
       (NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE);
   mNotificationManager.notify(id, builder.build());

   Set Up a Special Activity PendingIntent

   ---

   A special Activity doesn't need a back stack, so you don't have to define its Activity hierarchy in the manifest, and you don't have to call addParentStack() to build a back stack. Instead, use the manifest to set up the Activity task options, and create the PendingIntent by calling getActivity():

   1. In your manifest, add the following attributes to the <activity> element for the Activity:

      android:name="activityclass"

      The activity's fully-qualified class name.

      android:taskAffinity=""

      Combined with the FLAG_ACTIVITY_NEW_TASK flag that you set in code, this ensures that this Activitydoesn't go into the application's default task. Any existing tasks that have the application's default affinity are not affected.

      android:excludeFromRecents="true"

      Excludes the new task from Recents, so that the user can't accidentally navigate back to it.

      This snippet shows the element:

      <activity
          android:name=".ResultActivity"
      ...
          android:launchMode="singleTask"
          android:taskAffinity=""
          android:excludeFromRecents="true">
      </activity>
      ...

   2. Build and issue the notification:
      1. Create an Intent that starts the Activity.
      2. Set the Activity to start in a new, empty task by calling setFlags() with the flagsFLAG_ACTIVITY_NEW_TASK and FLAG_ACTIVITY_CLEAR_TASK.
      3. Set any other options you need for the Intent.
      4. Create a PendingIntent from the Intent by calling getActivity(). You can then use this PendingIntentas the argument to setContentIntent().

      The following code snippet demonstrates the process:

      // Instantiate a Builder object.
      NotificationCompat.Builder builder = new NotificationCompat.Builder(this);
      // Creates an Intent for the Activity
      Intent notifyIntent =
              new Intent(new ComponentName(this, ResultActivity.class));
      // Sets the Activity to start in a new, empty task
      notifyIntent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK | 
              Intent.FLAG_ACTIVITY_CLEAR_TASK);
      // Creates the PendingIntent
      PendingIntent notifyIntent =
              PendingIntent.getActivity(
              this,
              0,
              notifyIntent,
              PendingIntent.FLAG_UPDATE_CURRENT
      );
      
      // Puts the PendingIntent into the notification builder
      builder.setContentIntent(notifyIntent);
      // Notifications are issued by sending them to the
      // NotificationManager system service.
      NotificationManager mNotificationManager =
          (NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE);
      // Builds an anonymous Notification object from the builder, and
      // passes it to the NotificationManager
      mNotificationManager.notify(id, builder.build());

When you need to issue a notification multiple times for the same type of event, you should avoid making a completely new notification. Instead, you should consider updating a previous notification, either by changing some of its values or by adding to it, or both.

The following section describes how to update notifications and also how to remove them.

Modify a Notification

To set up a notification so it can be updated, issue it with a notification ID by calling NotificationManager.notify(ID, notification). To update this notification once you've issued it, update or create a NotificationCompat.Builder object, build aNotification object from it, and issue the Notification with the same ID you used previously.

The following snippet demonstrates a notification that is updated to reflect the number of events that have occurred. It stacks the notification, showing a summary:

mNotificationManager =
        (NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE);
// Sets an ID for the notification, so it can be updated
int notifyID = 1;
mNotifyBuilder = new NotificationCompat.Builder(this)
    .setContentTitle("New Message")
    .setContentText("You've received new messages.")
    .setSmallIcon(R.drawable.ic_notify_status)
numMessages = 0;
// Start of a loop that processes data and then notifies the user
...
    mNotifyBuilder.setContentText(currentText)
        .setNumber(++numMessages);
    // Because the ID remains unchanged, the existing notification is
    // updated.
    mNotificationManager.notify(
            notifyID,
            mNotifyBuilder.build());
...

Remove Notifications

Notifications remain visible until one of the following happens:

• The user dismisses the notification either individually or by using "Clear All" (if the notification can be cleared).
• The user touches the notification, and you called setAutoCancel() when you created the notification.
• You call cancel() for a specific notification ID. This method also deletes ongoing notifications.
• You call cancelAll(), which removes all of the notifications you previously issued.

Notifications in the notification drawer appear in two main visual styles, normal view and big view. The big view of a notification only appears when the notification is expanded. This happens when the notification is at the top of the drawer, or the user clicks the notification.

Big views were introduced in Android 4.1, and they're not supported on older devices. This lesson describes how to incorporate big view notifications into your app while still providing full functionality via the normal view. See theNotifications API guide for more discussion of big views.

Here is an example of a normal view:

Figure 1. Normal view notification.

Here is an example of a big view:

Figure 2. Big view notification.

In the sample application shown in this lesson, both the normal view and the big view give users access to same functionality:

• The ability to snooze or dismiss the notification.
• A way to view the reminder text the user set as part of the timer.

The normal view provides these features through a new activity that launches when the user clicks the notification. Keep this in mind as you design your notifications—first provide the functionality in the normal view, since this is how many users will interact with the notification.

Set Up the Notification to Launch a New Activity

The sample application uses an IntentService subclass (PingService) to construct and issue the notification.

In this snippet, the IntentService method onHandleIntent() specifies the new activity that will be launched if the user clicks the notification itself. The method setContentIntent() defines a pending intent that should be fired when the user clicks the notification, thereby launching the activity.

Intent resultIntent = new Intent(this, ResultActivity.class);
resultIntent.putExtra(CommonConstants.EXTRA_MESSAGE, msg);
resultIntent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK | 
        Intent.FLAG_ACTIVITY_CLEAR_TASK);
     
// Because clicking the notification launches 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
);

// This sets the pending intent that should be fired when the user clicks the
// notification. Clicking the notification launches a new activity.
builder.setContentIntent(resultPendingIntent);

Construct the Big View

This snippet shows how to set up the buttons that will appear in the big view:

// Sets up the Snooze and Dismiss action buttons that will appear in the
// big view of the notification.
Intent dismissIntent = new Intent(this, PingService.class);
dismissIntent.setAction(CommonConstants.ACTION_DISMISS);
PendingIntent piDismiss = PendingIntent.getService(this, 0, dismissIntent, 0);

Intent snoozeIntent = new Intent(this, PingService.class);
snoozeIntent.setAction(CommonConstants.ACTION_SNOOZE);
PendingIntent piSnooze = PendingIntent.getService(this, 0, snoozeIntent, 0);

This snippet shows how to construct the Builder object. It sets the style for the big view to be "big text," and sets its content to be the reminder message. It uses addAction() to add the Snooze and Dismiss buttons (and their associated pending intents) that will appear in the notification's big view:

// Constructs the Builder object.
NotificationCompat.Builder builder =
        new NotificationCompat.Builder(this)
        .setSmallIcon(R.drawable.ic_stat_notification)
        .setContentTitle(getString(R.string.notification))
        .setContentText(getString(R.string.ping))
        .setDefaults(Notification.DEFAULT_ALL) // requires VIBRATE permission
        /*
         * Sets the big view "big text" style and supplies the
         * text (the user's reminder message) that will be displayed
         * in the detail area of the expanded notification.
         * These calls are ignored by the support library for
         * pre-4.1 devices.
         */
        .setStyle(new NotificationCompat.BigTextStyle()
                .bigText(msg))
        .addAction (R.drawable.ic_stat_dismiss,
                getString(R.string.dismiss), piDismiss)
        .addAction (R.drawable.ic_stat_snooze,
                getString(R.string.snooze), piSnooze);

Notifications can include an animated progress indicator that shows users the status of an ongoing operation. If you can estimate how long the operation takes and how much of it is complete at any time, use the "determinate" form of the indicator (a progress bar). If you can't estimate the length of the operation, use the "indeterminate" form of the indicator (an activity indicator).

Progress indicators are displayed with the platform's implementation of the ProgressBar class.

To use a progress indicator, call setProgress(). The determinate and indeterminate forms are described in the following sections.

Display a Fixed-duration Progress Indicator

To display a determinate progress bar, add the bar to your notification by calling setProgress(max, progress, false) and then issue the notification. The third argument is a boolean that indicates whether the progress bar is indeterminate (true) or determinate (false). As your operation proceeds, increment progress, and update the notification. At the end of the operation, progress should equal max. A common way to call setProgress() is to setmax to 100 and then increment progress as a "percent complete" value for the operation.

You can either leave the progress bar showing when the operation is done, or remove it. In either case, remember to update the notification text to show that the operation is complete. To remove the progress bar, callsetProgress(0, 0, false). For example:

int id = 1;
...
mNotifyManager =
        (NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE);
mBuilder = new NotificationCompat.Builder(this);
mBuilder.setContentTitle("Picture Download")
    .setContentText("Download in progress")
    .setSmallIcon(R.drawable.ic_notification);
// Start a lengthy operation in a background thread
new Thread(
    new Runnable() {
        @Override
        public void run() {
            int incr;
            // Do the "lengthy" operation 20 times
            for (incr = 0; incr <= 100; incr+=5) {
                    // Sets the progress indicator to a max value, the
                    // current completion percentage, and "determinate"
                    // state
                    mBuilder.setProgress(100, incr, false);
                    // Displays the progress bar for the first time.
                    mNotifyManager.notify(id, mBuilder.build());
                        // Sleeps the thread, simulating an operation
                        // that takes time
                        try {
                            // Sleep for 5 seconds
                            Thread.sleep(5*1000);
                        } catch (InterruptedException e) {
                            Log.d(TAG, "sleep failure");
                        }
            }
            // When the loop is finished, updates the notification
            mBuilder.setContentText("Download complete")
            // Removes the progress bar
                    .setProgress(0,0,false);
            mNotifyManager.notify(id, mBuilder.build());
        }
    }
// Starts the thread by calling the run() method in its Runnable
).start();

The resulting notifications are shown in figure 1. On the left side is a snapshot of the notification during the operation; on the right side is a snapshot of it after the operation has finished.

Figure 1. The progress bar during and after the operation.

Display a Continuing Activity Indicator

To display a continuing (indeterminate) activity indicator, add it to your notification with setProgress(0, 0, true) and issue the notification. The first two arguments are ignored, and the third argument declares that the indicator is indeterminate. The result is an indicator that has the same style as a progress bar, except that its animation is ongoing.

Issue the notification at the beginning of the operation. The animation will run until you modify your notification. When the operation is done, call setProgress(0, 0, false) and then update the notification to remove the activity indicator. Always do this; otherwise, the animation will run even when the operation is complete. Also remember to change the notification text to indicate that the operation is complete.

To see how continuing activity indicators work, refer to the preceding snippet. Locate the following lines:

// Sets the progress indicator to a max value, the current completion
// percentage, and "determinate" state
mBuilder.setProgress(100, incr, false);
// Issues the notification
mNotifyManager.notify(id, mBuilder.build());

Replace the lines you've found with the following lines. Notice that the third parameter in the setProgress() call is set to true to indicate that the progress bar is indeterminate:

 // Sets an activity indicator for an operation of indeterminate length
mBuilder.setProgress(0, 0, true);
// Issues the notification
mNotifyManager.notify(id, mBuilder.build());

The resulting indicator is shown in figure 2:

Figure 2. An ongoing activity indicator.