Google Git
Sign in
android / platform / frameworks / base / 42bb44dbf5bffc5d3fcf89eacfd5c561dbe8095c / . / docs / html / guide / topics / ui / notifiers / notifications.jd
blob: 976115e019bd8236a1ca6574a2df6ba824e9c66a [file] [log] [blame]
page.title=Notifications
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#Design">Design Considerations</a></li>
<li><a href="#CreateNotification">Creating a Notification</a>
<ol>
<li><a href="#Required">Required notification contents</a></li>
<li><a href="#Optional">Optional notification contents and settings</a></li>
<li><a href="#Actions">Notification actions</a></li>
<li><a href="#Priority">Notification priority</a></li>
<li><a href="#SimpleNotification">Creating a simple notification</a></li>
<li><a href="#ApplyStyle">Applying an expanded layout to a notification</a></li>
<li><a href="#Compatibility">Handling compatibility</a></li>
</ol>
</li>
<li><a href="#Managing">Managing Notifications</a>
<ol>
<li><a href="#Updating">Updating notifications</a></li>
<li><a href="#Removing">Removing notifications</a></li>
</ol>
</li>
<li><a href="#NotificationResponse">Preserving Navigation when Starting an Activity</a>
<ol>
<li><a href="#DirectEntry">Setting up a regular activity PendingIntent</a></li>
<li><a href="#ExtendedNotification">Setting up a special activity PendingIntent</a></li>
</ol>
</li>
<li><a href="#Progress">Displaying Progress in a Notification</a>
<ol>
<li><a href="#FixedProgress">Displaying a fixed-duration progress indicator</a></li>
<li><a href="#ActivityIndicator">Displaying a continuing activity indicator</a></li>
</ol>
</li>
<li><a href="#metadata">Notification Metadata</a></li>
<li><a href="#Heads-up">Heads-up Notifications</a></li>
<li><a href="#lockscreenNotification">Lock Screen Notifications</a></li>
<ol>
<li><a href="#visibility">Setting Visibility</a></li>
<li><a href="#controllingMedia">Controlling Media Playback on the Lock Screen</a></li>
</ol>
<li><a href="#CustomNotification">Custom Notification Layouts</a></li>
</ol>
<h2>Key classes</h2>
<ol>
<li>{@link android.app.NotificationManager}</li>
<li>{@link android.support.v4.app.NotificationCompat}</li>
</ol>
<h2>Videos</h2>
<ol>
<li>
<a href="http://www.youtube.com/watch?v=Yc8YrVc47TI&feature=player_detailpage#t=1672s">
Notifications in 4.1</a>
</li>
</ol>
<h2>See also</h2>
<ol>
<li>
<a href="{@docRoot}design/patterns/notifications.html">Android Design: Notifications</a>
</li>
</ol>
</div>
</div>
<p>
A notification is a message you can display to the user outside of your application's
normal UI. When you tell the system to issue a notification, it first appears as an icon in the
<strong>notification area</strong>. To see the details of the notification, the user opens the
<strong>notification drawer</strong>. Both the notification area and the notification drawer
are system-controlled areas that the user can view at any time.
</p>
<img
id="figure1"
src="{@docRoot}images/ui/notifications/notification_area.png"
height="" alt="" />
<p class="img-caption">
<strong>Figure 1.</strong> Notifications in the notification area.
</p>
<img id="figure2" src="{@docRoot}images/ui/notifications/notification_drawer.png"
width="280px" alt="" />
<p class="img-caption">
<strong>Figure 2.</strong> Notifications in the notification drawer.
</p>
<p class="note"><strong>Note:</strong> Except where noted, this guide refers to the
{@link android.support.v4.app.NotificationCompat.Builder NotificationCompat.Builder} class
in the version 4 <a href="{@docRoot}tools/support-library/index.html">Support Library</a>.
The class {@link android.app.Notification.Builder Notification.Builder} was added in Android
3.0 (API level 11).</p>
<h2 id="Design">Design Considerations</h2>
<p>Notifications, as an important part of the Android user interface, have their own design guidelines.
The material design changes introduced in Android 5.0 (API level 21) are of particular
importance, and you should review the <a href="{@docRoot}training/material/index.html">Material Design</a>
training for more information. To learn how to design notifications and their interactions, read the
<a href="{@docRoot}design/patterns/notifications.html">Notifications</a> design guide.</p>
<h2 id="CreateNotification">Creating a Notification</h2>
<p>You specify the UI information and actions for a notification in a
{@link android.support.v4.app.NotificationCompat.Builder NotificationCompat.Builder} object.
To create the notification itself, you call
{@link android.support.v4.app.NotificationCompat.Builder#build NotificationCompat.Builder.build()},
which returns a {@link android.app.Notification} object containing your specifications. To issue the
notification, you pass the {@link android.app.Notification} object to the system by calling
{@link android.app.NotificationManager#notify NotificationManager.notify()}.</p>
<h3 id="Required">Required notification contents</h3>
<p>
A {@link android.app.Notification} object <em>must</em> contain the following:
</p>
<ul>
<li>
A small icon, set by
{@link android.support.v4.app.NotificationCompat.Builder#setSmallIcon setSmallIcon()}
</li>
<li>
A title, set by
{@link android.support.v4.app.NotificationCompat.Builder#setContentTitle setContentTitle()}
</li>
<li>
Detail text, set by
{@link android.support.v4.app.NotificationCompat.Builder#setContentText setContentText()}
</li>
</ul>
<h3 id="Optional">Optional notification contents and settings</h3>
<p>
All other notification settings and contents are optional. To learn more about them,
see the reference documentation for {@link android.support.v4.app.NotificationCompat.Builder}.
</p>
<!-- ------------------------------------------------------------------------------------------ -->
<h3 id="Actions">Notification actions</h3>
<p>
Although they're optional, you should add at least one action to your notification.
An action allows users to go directly from the notification to an
{@link android.app.Activity} in your application, where they can look at one or more events
or do further work.
</p>
<p>
A notification can provide multiple actions. You should always define the action that's
triggered when the user clicks the notification; usually this action opens an
{@link android.app.Activity} in your application. You can also add buttons to the notification
that perform additional actions such as snoozing an alarm or responding immediately to a text
message; this feature is available as of Android 4.1. If you use additional action buttons, you
must also make their functionality available in an {@link android.app.Activity} in your app; see
the section <a href="#Compatibility">Handling compatibility</a> for more details.
</p>
<p>
Inside a {@link android.app.Notification}, the action itself is defined by a
{@link android.app.PendingIntent} containing an
{@link android.content.Intent} that starts
an {@link android.app.Activity} in your application. To associate the
{@link android.app.PendingIntent} with a gesture, call the appropriate method of
{@link android.support.v4.app.NotificationCompat.Builder}. For example, if you want to start
{@link android.app.Activity} when the user clicks the notification text in
the notification drawer, you add the {@link android.app.PendingIntent} by calling
{@link android.support.v4.app.NotificationCompat.Builder#setContentIntent setContentIntent()}.
</p>
<p>
Starting an {@link android.app.Activity} when the user clicks the notification is the most
common action scenario. You can also start an {@link android.app.Activity} when the user
dismisses a notification. In Android 4.1 and later, you can start an
{@link android.app.Activity} from an action button. To learn more, read the reference guide for
{@link android.support.v4.app.NotificationCompat.Builder}.
</p>
<!-- ------------------------------------------------------------------------------------------ -->
<h3 id="Priority">Notification priority</h3>
<p>
If you wish, you can set the priority of a notification. The priority acts
as a hint to the device UI about how the notification should be displayed.
To set a notification's priority, call {@link
android.support.v4.app.NotificationCompat.Builder#setPriority(int)
NotificationCompat.Builder.setPriority()} and pass in one of the {@link
android.support.v4.app.NotificationCompat} priority constants. There are
five priority levels, ranging from {@link
android.support.v4.app.NotificationCompat#PRIORITY_MIN} (-2) to {@link
android.support.v4.app.NotificationCompat#PRIORITY_MAX} (2); if not set, the
priority defaults to {@link
android.support.v4.app.NotificationCompat#PRIORITY_DEFAULT} (0).
</p>
<p> For information about setting an appropriate priority level, see "Correctly
set and manage notification priority" in the <a
href="{@docRoot}design/patterns/notifications.html">Notifications</a> Design
guide.
</p>
<!-- ------------------------------------------------------------------------------------------ -->
<h3 id="SimpleNotification">Creating a simple notification</h3>
<p>
The following snippet illustrates a simple notification that specifies an activity to open when
the user clicks the notification. Notice that the code creates a
{@link android.support.v4.app.TaskStackBuilder} object and uses it to create the
{@link android.app.PendingIntent} for the action. This pattern is explained in more detail
in the section <a href="#NotificationResponse">
Preserving Navigation when Starting an Activity</a>:
</p>
<pre>
NotificationCompat.Builder mBuilder =
new NotificationCompat.Builder(this)
.setSmallIcon(R.drawable.notification_icon)
.setContentTitle("My notification")
.setContentText("Hello World!");
// Creates an explicit intent for an Activity in your app
Intent resultIntent = new Intent(this, ResultActivity.class);
// The stack builder object will contain an artificial back stack for the
// started Activity.
// This ensures that navigating backward from the Activity leads out of
// your application to the Home screen.
TaskStackBuilder stackBuilder = TaskStackBuilder.create(this);
// Adds the back stack for the Intent (but not the Intent itself)
stackBuilder.addParentStack(ResultActivity.class);
// Adds the Intent that starts the Activity to the top of the stack
stackBuilder.addNextIntent(resultIntent);
PendingIntent resultPendingIntent =
stackBuilder.getPendingIntent(
0,
PendingIntent.FLAG_UPDATE_CURRENT
);
mBuilder.setContentIntent(resultPendingIntent);
NotificationManager mNotificationManager =
(NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE);
// mId allows you to update the notification later on.
mNotificationManager.notify(mId, mBuilder.build());
</pre>
<p>That's it. Your user has now been notified.</p>
<!-- ------------------------------------------------------------------------------------------ -->
<h3 id="ApplyStyle">Applying an expanded layout to a notification</h3>
<p>
To have a notification appear in an expanded view, first create a
{@link android.support.v4.app.NotificationCompat.Builder} object with the normal view options
you want. Next, call {@link android.support.v4.app.NotificationCompat.Builder#setStyle
Builder.setStyle()} with an expanded layout object as its argument.
</p>
<p>
Remember that expanded notifications are not available on platforms prior to Android 4.1. To
learn how to handle notifications for Android 4.1 and for earlier platforms, read the
section <a href="#Compatibility">Handling compatibility</a>.
</p>
<p>
For example, the following code snippet demonstrates how to alter the notification created
in the previous snippet to use the expanded layout:
</p>
<pre>
NotificationCompat.Builder mBuilder = new NotificationCompat.Builder(this)
.setSmallIcon(R.drawable.notification_icon)
.setContentTitle("Event tracker")
.setContentText("Events received")
NotificationCompat.InboxStyle inboxStyle =
new NotificationCompat.InboxStyle();
String[] events = new String[6];
// Sets a title for the Inbox in expanded layout
inboxStyle.setBigContentTitle("Event tracker details:");
...
// Moves events into the expanded layout
for (int i=0; i &lt; events.length; i++) {
inboxStyle.addLine(events[i]);
}
// Moves the expanded layout object into the notification object.
mBuilder.setStyle(inBoxStyle);
...
// Issue the notification here.
</pre>
<h3 id="Compatibility">Handling compatibility</h3>
<p>
Not all notification features are available for a particular version, even though
the methods to set them are in the support library class
{@link android.support.v4.app.NotificationCompat.Builder NotificationCompat.Builder}.
For example, action buttons, which depend on expanded notifications, only appear on Android
4.1 and higher, because expanded notifications themselves are only available on
Android 4.1 and higher.
</p>
<p>
To ensure the best compatibility, create notifications with
{@link android.support.v4.app.NotificationCompat NotificationCompat} and its subclasses,
particularly {@link android.support.v4.app.NotificationCompat.Builder
NotificationCompat.Builder}. In addition, follow this process when you implement a notification:
</p>
<ol>
<li>
Provide all of the notification's functionality to all users, regardless of the version
they're using. To do this, verify that all of the functionality is available from an
{@link android.app.Activity} in your app. You may want to add a new
{@link android.app.Activity} to do this.
<p>
For example, if you want to use
{@link android.support.v4.app.NotificationCompat.Builder#addAction addAction()} to
provide a control that stops and starts media playback, first implement this
control in an {@link android.app.Activity} in your app.
</p>
</li>
<li>
Ensure that all users can get to the functionality in the {@link android.app.Activity},
by having it start when users click the notification. To do this,
create a {@link android.app.PendingIntent}
for the {@link android.app.Activity}. Call
{@link android.support.v4.app.NotificationCompat.Builder#setContentIntent
setContentIntent()} to add the {@link android.app.PendingIntent} to the notification.
</li>
<li>
Now add the expanded notification features you want to use to the notification. Remember
that any functionality you add also has to be available in the {@link android.app.Activity}
that starts when users click the notification.
</li>
</ol>
<!-- ------------------------------------------------------------------------------------------ -->
<!-- ------------------------------------------------------------------------------------------ -->
<h2 id="Managing">Managing Notifications</h2>
<p>
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.
</p>
<p>
For example, Gmail notifies the user that new emails have arrived by increasing its count of
unread messages and by adding a summary of each email to the notification. This is called
"stacking" the notification; it's described in more detail in the
<a href="{@docRoot}design/patterns/notifications.html">Notifications</a> Design guide.
</p>
<p class="note">
<strong>Note:</strong> This Gmail feature requires the "inbox" expanded layout, which is
part of the expanded notification feature available starting in Android 4.1.
</p>
<p>
The following section describes how to update notifications and also how to remove them.
</p>
<h3 id="Updating">Updating notifications</h3>
<p>
To set up a notification so it can be updated, issue it with a notification ID by
calling {@link android.app.NotificationManager#notify(int, android.app.Notification) NotificationManager.notify()}.
To update this notification once you've issued
it, update or create a {@link android.support.v4.app.NotificationCompat.Builder} object,
build a {@link android.app.Notification} object from it, and issue the
{@link android.app.Notification} with the same ID you used previously. If
the previous notification is still visible, the system updates it from the contents of
the {@link android.app.Notification} object. If the previous notification has been dismissed, a
new notification is created instead.
</p>
<p>
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:
</p>
<pre>
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());
...
</pre>
<!-- ------------------------------------------------------------------------------------------ -->
<h3 id="Removing">Removing notifications</h3>
<p>
Notifications remain visible until one of the following happens:
</p>
<ul>
<li>
The user dismisses the notification either individually or by using "Clear All" (if
the notification can be cleared).
</li>
<li>
The user clicks the notification, and you called
{@link android.support.v4.app.NotificationCompat.Builder#setAutoCancel setAutoCancel()} when
you created the notification.
</li>
<li>
You call {@link android.app.NotificationManager#cancel(int) cancel()} for a specific
notification ID. This method also deletes ongoing notifications.
</li>
<li>
You call {@link android.app.NotificationManager#cancelAll() cancelAll()}, which removes
all of the notifications you previously issued.
</li>
</ul>
<!-- ------------------------------------------------------------------------------------------ -->
<!-- ------------------------------------------------------------------------------------------ -->
<h2 id="NotificationResponse">Preserving Navigation when Starting an Activity</h2>
<p>
When you start an {@link android.app.Activity} from a notification, you must preserve the
user's expected navigation experience. Clicking <i>Back</i> should take the user back through
the application's normal work flow to the Home screen, and clicking <i>Recents</i> should show
the {@link android.app.Activity} as a separate task. To preserve the navigation experience, you
should start the {@link android.app.Activity} in a fresh task. How you set up the
{@link android.app.PendingIntent} to give you a fresh task depends on the nature of the
{@link android.app.Activity} you're starting. There are two general situations:
</p>
<dl>
<dt>
Regular activity
</dt>
<dd>
You're starting an {@link android.app.Activity} that's part of the application's normal
workflow. In this situation, set up the {@link android.app.PendingIntent} to
start a fresh task, and provide the {@link android.app.PendingIntent} with a back stack
that reproduces the application's normal <i>Back</i> behavior.
<p>
Notifications from the Gmail app demonstrate this. When you click a notification for
a single email message, you see the message itself. Touching <b>Back</b> takes you
backwards through Gmail to the Home screen, just as if you had entered Gmail from the
Home screen rather than entering it from a notification.
</p>
<p>
This happens regardless of the application you were in when you touched the
notification. For example, if you're in Gmail composing a message, and you click a
notification for a single email, you go immediately to that email. Touching <i>Back</i>
takes you to the inbox and then the Home screen, rather than taking you to the
message you were composing.
</p>
</dd>
<dt>
Special activity
</dt>
<dd>
The user only sees this {@link android.app.Activity} if it's started from a notification.
In a sense, the {@link android.app.Activity} extends the notification by providing
information that would be hard to display in the notification itself. For this situation,
set up the {@link android.app.PendingIntent} to start in a fresh task. There's no need to
create a back stack, though, because the started {@link android.app.Activity} isn't part of
the application's activity flow. Clicking <i>Back</i> will still take the user to the
Home screen.
</dd>
</dl>
<!-- ------------------------------------------------------------------------------------------ -->
<h3 id="DirectEntry">Setting up a regular activity PendingIntent</h3>
<p>
To set up a {@link android.app.PendingIntent} that starts a direct entry
{@link android.app.Activity}, follow these steps:
</p>
<ol>
<li>
Define your application's {@link android.app.Activity} hierarchy in the manifest.
<ol style="list-style-type: lower-alpha;">
<li>
Add support for Android 4.0.3 and earlier. To do this, specify the parent of the
{@link android.app.Activity} you're starting by adding a
<code><a href="{@docRoot}guide/topics/manifest/meta-data-element.html">&lt;meta-data&gt;</a></code>
element as the child of the
<code><a href="{@docRoot}guide/topics/manifest/activity-element.html">&lt;activity&gt;</a></code>.
<p>
For this element, set
<code><a href="{@docRoot}guide/topics/manifest/meta-data-element.html#nm">android:name</a>="android.support.PARENT_ACTIVITY"</code>.
Set
<code><a href="{@docRoot}guide/topics/manifest/meta-data-element.html#val">android:value</a>="&lt;parent_activity_name&gt;"</code>
where <code>&lt;parent_activity_name&gt;</code> is the value of
<code><a href="{@docRoot}guide/topics/manifest/meta-data-element.html#nm">android:name</a></code>
for the parent
<code><a href="{@docRoot}guide/topics/manifest/activity-element.html">&lt;activity&gt;</a></code>
element. See the following XML for an example.
</p>
</li>
<li>
Also add support for Android 4.1 and later. To do this, add the
<code><a href="{@docRoot}guide/topics/manifest/activity-element.html#parent">android:parentActivityName</a></code>
attribute to the
<code><a href="{@docRoot}guide/topics/manifest/activity-element.html">&lt;activity&gt;</a></code>
element of the {@link android.app.Activity} you're starting.
</li>
</ol>
<p>
The final XML should look like this:
</p>
<pre>
&lt;activity
android:name=".MainActivity"
android:label="&#64;string/app_name" &gt;
&lt;intent-filter&gt;
&lt;action android:name="android.intent.action.MAIN" /&gt;
&lt;category android:name="android.intent.category.LAUNCHER" /&gt;
&lt;/intent-filter&gt;
&lt;/activity&gt;
&lt;activity
android:name=".ResultActivity"
android:parentActivityName=".MainActivity"&gt;
&lt;meta-data
android:name="android.support.PARENT_ACTIVITY"
android:value=".MainActivity"/&gt;
&lt;/activity&gt;
</pre>
</li>
<li>
Create a back stack based on the {@link android.content.Intent} that starts the
{@link android.app.Activity}:
<ol style="list-style-type: lower-alpha;">
<li>
Create the {@link android.content.Intent} to start the {@link android.app.Activity}.
</li>
<li>
Create a stack builder by calling {@link android.app.TaskStackBuilder#create
TaskStackBuilder.create()}.
</li>
<li>
Add the back stack to the stack builder by calling
{@link android.support.v4.app.TaskStackBuilder#addParentStack addParentStack()}.
For each {@link android.app.Activity} in the hierarchy you've defined in the
manifest, the back stack contains an {@link android.content.Intent} object that
starts the {@link android.app.Activity}. This method also adds flags that start the
stack in a fresh task.
<p class="note">
<strong>Note:</strong> Although the argument to
{@link android.support.v4.app.TaskStackBuilder#addParentStack addParentStack()}
is a reference to the started {@link android.app.Activity}, the method call
doesn't add the {@link android.content.Intent} that starts the
{@link android.app.Activity}. Instead, that's taken care of in the next step.
</p>
</li>
<li>
Add the {@link android.content.Intent} that starts the {@link android.app.Activity}
from the notification, by calling
{@link android.support.v4.app.TaskStackBuilder#addNextIntent addNextIntent()}.
Pass the {@link android.content.Intent} you created in the first step as the
argument to
{@link android.support.v4.app.TaskStackBuilder#addNextIntent addNextIntent()}.
</li>
<li>
If you need to, add arguments to {@link android.content.Intent} objects on the
stack by calling {@link android.support.v4.app.TaskStackBuilder#editIntentAt
TaskStackBuilder.editIntentAt()}. This is sometimes necessary to ensure that the
target {@link android.app.Activity} displays meaningful data when the user navigates
to it using <i>Back</i>.
</li>
<li>
Get a {@link android.app.PendingIntent} for this back stack by calling
{@link android.support.v4.app.TaskStackBuilder#getPendingIntent getPendingIntent()}.
You can then use this {@link android.app.PendingIntent} as the argument to
{@link android.support.v4.app.NotificationCompat.Builder#setContentIntent
setContentIntent()}.
</li>
</ol>
</li>
</ol>
<p>
The following code snippet demonstrates the process:
</p>
<pre>
...
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());
</pre>
<!-- ------------------------------------------------------------------------------------------ -->
<h3 id="ExtendedNotification">Setting up a special activity PendingIntent</h3>
<p>
The following section describes how to set up a special activity
{@link android.app.PendingIntent}.
</p>
<p>
A special {@link android.app.Activity} doesn't need a back stack, so you don't have to
define its {@link android.app.Activity} hierarchy in the manifest, and you don't have
to call
{@link android.support.v4.app.TaskStackBuilder#addParentStack addParentStack()} to build a
back stack. Instead, use the manifest to set up the {@link android.app.Activity} task options,
and create the {@link android.app.PendingIntent} by calling
{@link android.app.PendingIntent#getActivity getActivity()}:
</p>
<ol>
<li>
In your manifest, add the following attributes to the
<code><a href="{@docRoot}guide/topics/manifest/activity-element.html">&lt;activity&gt;</a></code>
element for the {@link android.app.Activity}
<dl>
<dt>
<code><a href="{@docRoot}guide/topics/manifest/activity-element.html#nm">android:name</a>="<i>activityclass</i>"</code>
</dt>
<dd>
The activity's fully-qualified class name.
</dd>
<dt>
<code><a href="{@docRoot}guide/topics/manifest/activity-element.html#aff">android:taskAffinity</a>=""</code>
</dt>
<dd>
Combined with the
{@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK FLAG_ACTIVITY_NEW_TASK} flag
that you set in code, this ensures that this {@link android.app.Activity} doesn't
go into the application's default task. Any existing tasks that have the
application's default affinity are not affected.
</dd>
<dt>
<code><a href="{@docRoot}guide/topics/manifest/activity-element.html#exclude">android:excludeFromRecents</a>="true"</code>
</dt>
<dd>
Excludes the new task from <i>Recents</i>, so that the user can't accidentally
navigate back to it.
</dd>
</dl>
<p>
This snippet shows the element:
</p>
<pre>
&lt;activity
android:name=".ResultActivity"
...
android:launchMode="singleTask"
android:taskAffinity=""
android:excludeFromRecents="true"&gt;
&lt;/activity&gt;
...
</pre>
</li>
<li>
Build and issue the notification:
<ol style="list-style-type: lower-alpha;">
<li>
Create an {@link android.content.Intent} that starts the
{@link android.app.Activity}.
</li>
<li>
Set the {@link android.app.Activity} to start in a new, empty task by calling
{@link android.content.Intent#setFlags setFlags()} with the flags
{@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK FLAG_ACTIVITY_NEW_TASK}
and
{@link android.content.Intent#FLAG_ACTIVITY_CLEAR_TASK FLAG_ACTIVITY_CLEAR_TASK}.
</li>
<li>
Set any other options you need for the {@link android.content.Intent}.
</li>
<li>
Create a {@link android.app.PendingIntent} from the {@link android.content.Intent}
by calling {@link android.app.PendingIntent#getActivity getActivity()}.
You can then use this {@link android.app.PendingIntent} as the argument to
{@link android.support.v4.app.NotificationCompat.Builder#setContentIntent
setContentIntent()}.
</li>
</ol>
<p>
The following code snippet demonstrates the process:
</p>
<pre>
// Instantiate a Builder object.
NotificationCompat.Builder builder = new NotificationCompat.Builder(this);
// Creates an Intent for the Activity
Intent notifyIntent =
new Intent(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 notifyPendingIntent =
PendingIntent.getActivity(
this,
0,
notifyIntent,
PendingIntent.FLAG_UPDATE_CURRENT
);
// Puts the PendingIntent into the notification builder
builder.setContentIntent(notifyPendingIntent);
// 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());
</pre>
</li>
</ol>
<!-- ------------------------------------------------------------------------------------------ -->
<!-- ------------------------------------------------------------------------------------------ -->
<h2 id="Progress">Displaying Progress in a Notification</h2>
<p>
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).
</p>
<p>
Progress indicators are displayed with the platform's implementation of the
{@link android.widget.ProgressBar} class.
</p>
<p>
To use a progress indicator on platforms starting with Android 4.0, call
{@link android.support.v4.app.NotificationCompat.Builder#setProgress setProgress()}. For
previous versions, you must create your own custom notification layout that
includes a {@link android.widget.ProgressBar} view.
</p>
<p>
The following sections describe how to display progress in a notification using
{@link android.support.v4.app.NotificationCompat.Builder#setProgress setProgress()}.
</p>
<!-- ------------------------------------------------------------------------------------------ -->
<h3 id="FixedProgress">Displaying a fixed-duration progress indicator</h3>
<p>
To display a determinate progress bar, add the bar to your notification by calling
{@link android.support.v4.app.NotificationCompat.Builder#setProgress
setProgress(max, progress, false)} and then issue the notification. As your operation proceeds,
increment <code>progress</code>, and update the notification. At the end of the operation,
<code>progress</code> should equal <code>max</code>. A common way to call
{@link android.support.v4.app.NotificationCompat.Builder#setProgress setProgress()}
is to set <code>max</code> to 100 and then increment <code>progress</code> as a
"percent complete" value for the operation.
</p>
<p>
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, call
{@link android.support.v4.app.NotificationCompat.Builder#setProgress
setProgress(0, 0, false)}. For example:
</p>
<pre>
...
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() {
&#64;Override
public void run() {
int incr;
// Do the "lengthy" operation 20 times
for (incr = 0; incr &lt;= 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(0, 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();
</pre>
<!-- ------------------------------------------------------------------------------------------ -->
<h3 id="ActivityIndicator">Displaying a continuing activity indicator</h3>
<p>
To display an indeterminate activity indicator, add it to your notification with
{@link android.support.v4.app.NotificationCompat.Builder#setProgress setProgress(0, 0, true)}
(the first two arguments are ignored), and issue the notification. The result is an indicator
that has the same style as a progress bar, except that its animation is ongoing.
</p>
<p>
Issue the notification at the beginning of the operation. The animation will run until you
modify your notification. When the operation is done, call
{@link android.support.v4.app.NotificationCompat.Builder#setProgress 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.
</p>
<p>
To see how activity indicators work, refer to the preceding snippet. Locate the following lines:
</p>
<pre>
// 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(0, mBuilder.build());
</pre>
<p>
Replace the lines you've found with the following lines:
</p>
<pre>
// Sets an activity indicator for an operation of indeterminate length
mBuilder.setProgress(0, 0, true);
// Issues the notification
mNotifyManager.notify(0, mBuilder.build());
</pre>
<h2 id="metadata">Notification Metadata</h2>
<p>Notifications may be sorted according to metadata that you assign with the
following {@link android.support.v4.app.NotificationCompat.Builder} methods:</p>
<ul>
<li>{@link android.support.v4.app.NotificationCompat.Builder#setCategory(java.lang.String) setCategory()}
tells the system how to handle your app notifications when the device is in Priority mode
(for example, if your notification represents an incoming call, instant message, or alarm).</li>
<li>{@link android.support.v4.app.NotificationCompat.Builder#setPriority(int) setPriority()} causes
notifications with the priority field set to {@code PRIORITY_MAX} or {@code PRIORITY_HIGH} to
appear in a small floating window if the notification also has sound or vibration.</li>
<li>{@link android.support.v4.app.NotificationCompat.Builder#addPerson(java.lang.String) addPerson()}
allows you to add a list of people to a notification. Your app can use this to signal to the
system that it should group together notifications from the specified people, or rank notifications
from these people as being more important.</li>
</ul>
<div class="figure" style="width:230px">
<img src="{@docRoot}images/ui/notifications/heads-up.png"
alt="" width="" height="" id="figure3" />
<p class="img-caption">
<strong>Figure 3.</strong> Fullscreen activity showing a heads-up notification
</p>
</div>
<h2 id="Heads-up">Heads-up Notifications</h2>
<p>With Android 5.0 (API level 21), notifications can appear in a small floating window
(also called a <em>heads-up notification</em>) when the device is active
(that is, the device is unlocked and its screen is on). These notifications
appear similar to the compact form of your notification, except that the
heads-up notification also shows action buttons. Users can act on, or dismiss,
a heads-up notification without leaving the current app.</p>
<p>Examples of conditions that may trigger heads-up notifications include:</p>
<ul>
<li>The user's activity is in fullscreen mode (the app uses
{@link android.app.Notification#fullScreenIntent}), or</li>
<li>The notification has high priority and uses ringtones or
vibrations</li>
</ul>
<h2 id="lockscreenNotification">Lock Screen Notifications</h2>
<p>With the release of Android 5.0 (API level 21), notifications may now appear on the lock
screen. Your app can use this functionality to provide media playback controls and other common
actions. Users can choose via Settings whether to display notifications on the lock screen, and
you can designate whether a notification from your app is visible on the lock screen.</p>
<h3 id="visibility">Setting Visibility</h3>
<p>Your app can control the level of detail visible in notifications displayed on a secure
lock screen. You call {@link android.support.v4.app.NotificationCompat.Builder#setVisibility(int) setVisibility()}
and specify one of the following values:</p>
<ul>
<li>{@link android.support.v4.app.NotificationCompat#VISIBILITY_PUBLIC} shows the notification's
full content.</li>
<li>{@link android.support.v4.app.NotificationCompat#VISIBILITY_SECRET} doesn't show any part of
this notification on the lock screen.</li>
<li>{@link android.support.v4.app.NotificationCompat#VISIBILITY_PRIVATE} shows basic information,
such as the notification's icon and the content title, but hides the notification's full content.</li>
</ul>
<p>When {@link android.support.v4.app.NotificationCompat#VISIBILITY_PRIVATE} is set, you can also
provide an alternate version of the notification content which hides certain details. For example,
an SMS app might display a notification that shows <em>You have 3 new text messages</em>, but hides the
message contents and senders. To provide this alternative notification, first create the replacement
notification using {@link android.support.v4.app.NotificationCompat.Builder}. When you create the
private notification object, attach the replacement notification to it through the
{@link android.support.v4.app.NotificationCompat.Builder#setPublicVersion(android.app.Notification) setPublicVersion()}
method.</p>
<h3 id="controllingMedia">Controlling Media Playback on the Lock Screen</h3>
<p>In Android 5.0 (API level 21) the lock screen no longer displays media controls
based on the {@link android.media.RemoteControlClient}, which is now deprecated. Instead, use the
{@link android.app.Notification.MediaStyle} template with the
{@link android.app.Notification.Builder#addAction(android.app.Notification.Action) addAction()}
method, which converts actions into clickable icons.</p>
<p class="note"><strong>Note:</strong> The template and the {@link android.app.Notification.Builder#addAction(android.app.Notification.Action) addAction()}
method are not included in the support library, so these features run in Android 5.0 and higher
only.</p>
<p>To display media playback controls on the lock screen in Android 5.0, set the visibility
to {@link android.support.v4.app.NotificationCompat#VISIBILITY_PUBLIC}, as described above. Then add
the actions and set the {@link android.app.Notification.MediaStyle} template, as described in the
following sample code:</p>
<pre>
Notification notification = new Notification.Builder(context)
// Show controls on lock screen even when user hides sensitive content.
.setVisibility(Notification.VISIBILITY_PUBLIC)
.setSmallIcon(R.drawable.ic_stat_player)
// Add media control buttons that invoke intents in your media service
.addAction(R.drawable.ic_prev, "Previous", prevPendingIntent) // #0
.addAction(R.drawable.ic_pause, "Pause", pausePendingIntent) // #1
.addAction(R.drawable.ic_next, "Next", nextPendingIntent) // #2
// Apply the media style template
.setStyle(new Notification.MediaStyle()
.setShowActionsInCompactView(1 /* #1: pause button */)
.setMediaSession(mMediaSession.getSessionToken())
.setContentTitle("Wonderful music")
.setContentText("My Awesome Band")
.setLargeIcon(albumArtBitmap)
.build();
</pre>
<p class="note"><strong>Note:</strong> The deprecation of {@link android.media.RemoteControlClient}
has further implications for controlling media. See
<a href="{@docRoot}about/versions/android-5.0.html#MediaPlaybackControl">Media Playback Control</a>
for more information about the new APIs for managing the media session and controlling playback.</p>
<!-- ------------------------------------------------------------------------------------------ -->
<h2 id="CustomNotification">Custom Notification Layouts</h2>
<p>
The notifications framework allows you to define a custom notification layout, which
defines the notification's appearance in a {@link android.widget.RemoteViews} object.
Custom layout notifications are similar to normal notifications, but they're based on a
{@link android.widget.RemoteViews} defined in a XML layout file.
</p>
<p>
The height available for a custom notification layout depends on the notification view. Normal
view layouts are limited to 64 dp, and expanded view layouts are limited to 256 dp.
</p>
<p>
To define a custom notification layout, start by instantiating a
{@link android.widget.RemoteViews} object that inflates an XML layout file. Then,
instead of calling methods such as
{@link android.support.v4.app.NotificationCompat.Builder#setContentTitle setContentTitle()},
call {@link android.support.v4.app.NotificationCompat.Builder#setContent setContent()}. To set
content details in the custom notification, use the methods in
{@link android.widget.RemoteViews} to set the values of the view's children:
</p>
<ol>
<li>
Create an XML layout for the notification in a separate file. You can use any file name
you wish, but you must use the extension <code>.xml</code>
</li>
<li>
In your app, use {@link android.widget.RemoteViews} methods to define your notification's
icons and text. Put this {@link android.widget.RemoteViews} object into your
{@link android.support.v4.app.NotificationCompat.Builder} by calling
{@link android.support.v4.app.NotificationCompat.Builder#setContent setContent()}. Avoid
setting a background {@link android.graphics.drawable.Drawable} on your
{@link android.widget.RemoteViews} object, because your text color may become unreadable.
</li>
</ol>
<p>
The {@link android.widget.RemoteViews} class also includes methods that you can use to easily
add a {@link android.widget.Chronometer} or {@link android.widget.ProgressBar}
to your notification's layout. For more information about creating custom layouts for your
notification, refer to the {@link android.widget.RemoteViews} reference documentation.
</p>
<p class="caution">
<strong>Caution:</strong> When you use a custom notification layout, take special care to
ensure that your custom layout works with different device orientations and resolutions. While
this advice applies to all View layouts, it's especially important for notifications because
the space in the notification drawer is very restricted. Don't make your custom layout too
complex, and be sure to test it in various configurations.
</p>
<!-- ------------------------------------------------------------------------------------------ -->
<h4>Using style resources for custom notification text</h4>
<p>
Always use style resources for the text of a custom notification. The background color of the
notification can vary across different devices and versions, and using style resources
helps you account for this. Starting in Android 2.3, the system defined a style for the
standard notification layout text. If you use the same style in applications that target Android
2.3 or higher, you'll ensure that your text is visible against the display background.
</p>