Notification Channels

Android O introduces notification channels to provide a unified system to help users manage notifications. When you target Android O, you must implement one or more notification channels to display notifications to your users. If you don't target Android O, your apps behave the same as they do on Android 7.0 when running on Android O devices.

You can create a notification channel for each distinct type of notification you need to send. You can also create notification channels to reflect choices made by users of your app. For example, you might setup separate notification channels for each conversation group created by a user in a messaging app.

Users can now manage most of the settings associated with notifications using a consistent system UI. All notifications posted to a notification channel behave the same. When a user modifies the behavior for any of the following characteristics, it applies to the notification channel:

• Importance
• Sound
• Lights
• Vibration
• Show on lockscreen
• Override do not disturb

Users can visit Settings, or long press a notification to change these behaviors, or even block a notification channel at any time. You can't programmatically modify the behavior of a notification channel once it's created and submitted to the notification manager; the user is in charge of those settings.

Notification priority and importance

Android O deprecates the ability to set the priority levels of individual notifications. Instead, you can now set a recommended importance level when creating a notification channel. The importance level you assign to a notification channel applies to all notification messages that you post to it. You can configure a channel with one of five importance levels that configure the amount a channel can interrupt a user, ranging from IMPORTANCE_NONE(0) to IMPORTANCE_HIGH(4). The default importance level is 3 which displays everywhere, makes noise, but doesn't visually intrude on the user. Once you create a notification channel, only the system can modify its importance.

Creating a notification channel

To create a notification channel:

1. Construct a notification channel object with an ID that's unique within your package.
2. Configure the notification channel object with any desired initial settings such as an alert sound, as well as an optional description visible to the user.
3. Submit the notification channel object to the notification manager.

Attempting to create an existing notification channel with its original values performs no operation, so it's safe to perform the above sequence of steps when starting an app. The following code sample demonstrates creating a notification channel with a low importance level, and a custom vibration pattern.

NotificationManager mNotificationManager =
        (NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE);
// The id of the channel.
String id = "my_channel_01";
// The user-visible name of the channel.
CharSequence name = getString(R.string.channel_name);
// The user-visible description of the channel.
String description = getString(R.string.channel_description);
int importance = NotificationManager.IMPORTANCE_LOW;
NotificationChannel mChannel = new NotificationChannel(id, name, importance);
// Configure the notification channel.
mChannel.setDescription(description);
mChannel.enableLights(true);
// Sets the notification light color for notifications posted to this
// channel, if the device supports this feature.
mChannel.setLightColor(Color.RED);
mChannel.enableVibration(true);
mChannel.setVibrationPattern(new long[]{100, 200, 300, 400, 500, 400, 300, 200, 400});
mNotificationManager.createNotificationChannel(mChannel);

You can also create multiple notification channels in a single operation by calling createNotificationChannels().

Creating a notification channel Group

If your app supports multiple user accounts, you can create a notification channel group for each account. Notification channel groups allow you to manage multiple notification channels with identical names within a single app. For example, a social networking app might include support for personal, as well as business user accounts. In this scenario, each user account might require multiple notification channels with identical functions and names.

• A personal user account including 2 notification channels:
  • Notifications of new comments on your posts.
  • Notifications recommending posts by your contacts.
• A business user account including 2 notification channels:
  • Notifications of new comments on your posts.
  • Notifications recommending posts by your contacts.

Organizing the notification channels associated with each user account in this example into dedicated groups ensures that users can easily distinguish between them in Settings. Each notification channel group requires an ID that must be unique within your package, as well as a user-visible name. The following snippet demonstrates how to create a notification channel group.

// The id of the group.
String group = "my_group_01";
// The user-visible name of the group.
CharSequence name = getString(R.string.group_name);;
NotificationManager mNotificationManager =
        (NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE);
mNotificationManager.createNotificationChannelGroup(new NotificationChannelGroup(group, name));

Once you've created a new group you can call setGroup() to associate a new channel with the group. You can only modify the association between notification channel and group before you submit the channel to the notification manager.

Creating a notification

To create a notification, you call Notification.Builder.build(), which returns a Notification object containing your specifications. To issue the notification, you pass the Notification object to the system by calling notify().

Required notification contents

A Notification object must contain the following:

• A small icon, set by setSmallIcon()
• A title, set by setContentTitle()
• Detail text, set by setContentText()
• A valid notification channel ID, set by setChannelId()

If you target Android O and post a notification without specifying a valid notifications channel, the notification fails to post and the system logs an error.

Note: You can turn on a new setting in Android O to display an on-screen warning that appears as a toast when an app targeting Android O attempts to post without a notification channel. To turn on the setting for a development device running Android O, navigate to Settings > Developer options and toggle Show notification channel warnings to on.

Posting a notification to a channel

The following snippet illustrates posting a simple notification to a notification channel. Notice that the code associates the notification with a notification channel using the channel's ID.

mNotificationManager = (NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE);
// Sets an ID for the notification, so it can be updated.
int notifyID = 1;
// The id of the channel.
String CHANNEL_ID = "my_channel_01";
// Create a notification and set the notification channel.
Notification notification = new Notification.Builder(MainActivity.this)
        .setContentTitle("New Message")
        .setContentText("You've received new messages.")
        .setSmallIcon(R.drawable.ic_notify_status)
        .setChannelId(CHANNEL_ID)
        .build();
// Issue the notification.
mNotificationManager.notify(id, notification);

Reading notification channel settings

Users can modify the settings for notification channels, including behaviors such as vibration and alert sound. You can call the following two methods to discover the settings a user has applied to a notification channel:

• To retrieve a single notification channel, you can call getNotificationChannel().
• To retrieve all notification channels belonging to your app, you can call getNotificationChannels().

Updating notification channel settings

Once you create a notification channel, the user is in charge of its settings and behavior. You can call createNotificationChannel() again to rename an existing notification channel, or update its description. The following sample code describes how you can redirect a user to the settings for a notification channel by creating an intent to start an activity. In this case, the intent requires extended data including the ID of the notification channel and the package name of your app.

Intent intent = new Intent(Settings.ACTION_CHANNEL_NOTIFICATION_SETTINGS);
intent.putExtra(Settings.EXTRA_CHANNEL_ID, mChannel.getId());
intent.putExtra(Settings.EXTRA_APP_PACKAGE, getPackageName());
startActivity(intent);

Deleting a notification channel

You can delete notification channels by calling deleteNotificationChannel(). Notification settings displays the number of deleted channels, as a spam prevention mechanism. You can clear test channels on development devices: either by reinstalling the app, or by clearing the data associated with your copy of the app. The following sample code demonstrates how to delete a notification channel.

NotificationManager mNotificationManager =
        (NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE);
// The id of the channel.
String id = "my_channel_01";
NotificationChannel mChannel = mNotificationManager.getNotificationChannel(id);
mNotificationManager.deleteNotificationChannel(mChannel);