UI notifications that can be sent while the application is in the background.
Notifications alert the user that something is happening to your application while it is in the background. Notifications appear in the notification drawer until the user clears them and on the lock screen for devices running Android 5.0 or greater. Note that the user can filter or turn notifications on and off from Settings.
For Android toast notifications (pop-up notifications sent while the application is in the foreground), see Titanium.UI.Notification.
To create a notification, use the Titanium.Android.createNotification method.
Pass the Notification object to the methods of the Titanium.Android.NotificationManager class to send or cancel notifications.
For examples of using Notifications, see Android Notifications.
Further Reading:
Starting with Android 5.0 (API 21), ticker text, defined with the tickerText property,
no longer appears in the status bar when the notification is first sent but is used as an
audible notification if accessibility services are enabled.
Notifications now appear in the lock screen. The user can customize the visibility level of
these notifications from Settings. The visibility level is based on the visibility
property set on the notification.
The following example shows how to create a notification that launches the application when the user clicks on the notification.
To have the notification launch an application when the user clicks on it,
assign the contentIntent property to an Intent object
that launches the main activity of the application by specifying the packageName
and className properties of the intent.
The packageName is the project's application ID. For Titanium applications, you
can find this in the tiapp.xml file.
The className is the name of the main activity, prefixed with the packageName.
For Titanium applications, the name of the main activity is the application name with
only the first character capitalized suffixed with Activity. You can also find the name
of the main activity in the build/android/AndroidManifest.xml file after you build your
application.
For example, if the application ID is com.appcelerator.notificationsample and the
application name is NotificationSample, the class name will be:
com.appcelerator.notificationsample.NotificationsampleActivity
The notification icon must be specified as an Android resource ID. In this case,
the icon, my_icon.png would be placed in platforms/android/res/drawable/my_icon.png.
See Titanium.App.Android.R for more information.
This example does not include a custom alert sound. For information on adding a custom alert sound, see Notification.sound.
// Intent object to launch the application
var intent = Ti.Android.createIntent({
action: Ti.Android.ACTION_MAIN,
// Substitute the correct class name for your application
className: 'com.appcelerator.notificationsample.NotificationsampleActivity',
// Substitue the correct package name for your application
packageName: 'com.appcelerator.notificationsample'
});
intent.flags |= Ti.Android.FLAG_ACTIVITY_CLEAR_TOP | Ti.Android.FLAG_ACTIVITY_NEW_TASK;
intent.addCategory(Ti.Android.CATEGORY_LAUNCHER);
// Create a PendingIntent to tie together the Activity and Intent
var pending = Titanium.Android.createPendingIntent({
intent: intent,
flags: Titanium.Android.FLAG_UPDATE_CURRENT
});
// Create the notification
var notification = Titanium.Android.createNotification({
// icon is passed as an Android resource ID -- see Ti.App.Android.R.
icon: Ti.App.Android.R.drawable.my_icon,
contentTitle: 'Something Happened',
contentText : 'Click to return to the application.',
contentIntent: pending
});
// Send the notification.
Titanium.Android.NotificationManager.notify(1, notification);
The following example shows how to create bundled notifications.
var id = 100,
groupKey = 'group_key';
for (var i = 3; i > 0; i--) {
Ti.Android.NotificationManager.notify(id++,
Ti.Android.createNotification({
icon: Ti.Android.R.drawable.ic_dialog_info,
contentTitle: 'NOTIFICATION #' + i,
contentText : 'Lorem ipsum dolor sit amet, facer eruditi omittantur cu pri, nibh nonumy putant eam eu.'
groupKey: groupKey
})
);
}
Ti.Android.NotificationManager.notify(id++,
Ti.Android.createNotification({
icon: Ti.Android.R.drawable.ic_dialog_info,
contentTitle: 'NOTIFICATIONS',
contentText : 'You have 3 notifications.',
groupKey: groupKey,
groupSummary: true
})
);
The name of the API that this proxy corresponds to.
The name of the API that this proxy corresponds to.
The value of this property is the fully qualified name of the API. For example, Button
returns Ti.UI.Button.
The audio stream type to use when playing the sound.
The audio stream type to use when playing the sound.
Specify one of the STREAM constants from Titanium.Android.
This API can be assigned the following constants:
Indicates if the proxy will bubble an event to its parent.
Some proxies (most commonly views) have a relationship to other proxies, often established by the add() method. For example, for a button added to a window, a click event on the button would bubble up to the window. Other common parents are table sections to their rows, table views to their sections, and scrollable views to their views. Set this property to false to disable the bubbling to the proxy's parent.
Default: true
Sets the notification's category.
Requires: Android 5.0 and later
If your notification falls into one of the predefined categories, assign it accordingly. Aspects of the system UI such as the notification shade may use this information to make ranking and filtering decisions. This property only works for devices running Android 5.0 (API 21) and greater.
This API can be assigned the following constants:
Accent color used behind icon.
Requires: Android 5.0 and later
Accent color of the circle used behind icon. The Icon will be stenciled in white on top of a cicle of the color set. For information about color values, see the "Colors" section of Titanium.UI.
See Android Reference for the color property.
The PendingIntent to execute when the expanded status entry is clicked.
The PendingIntent to execute when the expanded status entry is clicked.
Custom layout to display in the notification.
Custom layout to display in the notification.
Calling setLatestEventInfo or
setting the contentText or contentTitle properties causes the notification to use
the default notification layout, overriding any custom layout set through
contentView.
If you use a custom layout, you can use the RemoteViews methods to update the displayed notification.
Specifies which values should be taken from the defaults.
Specifies which values should be taken from the defaults.
Specify the bitwise OR of the desired values: Titanium.Android.DEFAULT_LIGHTS, Titanium.Android.DEFAULT_SOUND, and Titanium.Android.DEFAULT_VIBRATE. Use Titanium.Android.DEFAULT_ALL to specify that all values should be taken from the defaults.
This API can be assigned the following constants:
The PendingIntent to execute when the status entry is deleted by the user with the "Clear All Notifications" button.
The PendingIntent to execute when the status entry is deleted by the user with the "Clear All Notifications" button.
Set of flags for the notification.
This API can be assigned the following constants:
Default: Titanium.Android.FLAG_AUTO_CANCEL
The group key that the notification will belong to.
Requires: Android 5.1 and later
Specifies if this is a group summary notification.
Requires: Android 5.1 and later
Notification icon, specified as an Android resource ID, or a local URL to a density-specific image.
Notification icon, specified as an Android resource ID, or a local URL to a density-specific image.
If specified as a URL, the icon must be placed in one of the density-specific
folders under Resources/android/images. For example, if your icon is called
my_icon.png, you would create high- and medium-density versions of the icons
with the following paths:
Resources/android/images/res-hdpi/my_icon.png
Resources/android/images/res-mdpi/my_icon.png
To access this icon, you'd use the URL '/images/my_icon.png'.
To access the same icon using an Android resource ID, place the icon in:
platform/android/res/drawable/my_icon.png
This icon's resource ID can be referenced through the Titanium.App.Android.R object:
icon: Ti.App.Android.R.drawable.my_icon,
See Titanium.App.Android.R for more information on accessing Android resources by ID.
Add a large icon to the notification (and the ticker on some devices) specified as an Android resource ID, or a local URL to a density-specific image.
If specified as a URL, the icon must be placed in one of the density-specific
folders under Resources/android/images. For example, if your icon is called
my_large_icon.png, you would create high- and medium-density versions of the icons
with the following paths:
Resources/android/images/res-hdpi/my_large_icon.png
Resources/android/images/res-mdpi/my_large_icon.png
To access this large icon, you'd use the URL '/images/my_large_icon.png'.
To access the same large icon using an Android resource ID, place the icon in:
platform/android/res/drawable/my_large_icon.png
This large icon's resource ID can be referenced through the Titanium.App.Android.R object:
icon: Ti.App.Android.R.drawable.my_large_icon,
See Titanium.App.Android.R for more information on accessing Android resources by ID.
The number of milliseconds for the LED to be off while it's flashing.
The number of milliseconds for the LED to be off while it's flashing.
The number of milliseconds for the LED to be on while it's flashing.
The number of milliseconds for the LED to be on while it's flashing.
The Window or TabGroup whose Activity lifecycle should be triggered on the proxy.
The Window or TabGroup whose Activity lifecycle should be triggered on the proxy.
If this property is set to a Window or TabGroup, then the corresponding Activity lifecycle event callbacks will also be called on the proxy. Proxies that require the activity lifecycle will need this property set to the appropriate containing Window or TabGroup.
The number of events that this notification represents.
The number of events that this notification represents.
Sets the priority of the notification.
Requires: Android 4.1 and later
This property only works for devices running Android 4.1 (API 16) and greater.
This API can be assigned the following constants:
Default: undefined but behaves as Titanium.Android.PRIORITY_DEFAULT
A URL to the sound to play.
A URL to the sound to play.
The URL cannot refer to a file in the Resources directory, but it can refer to a file in the raw resources directory (Filesystem.resRawDirectory) or the external storage directory (Filesystem.externalStorageDirectory).
To create a raw resource, place the audio file in the platform/android/res/raw
folder and reference it as:
notification.sound = Ti.Filesystem.getResRawDirectory() + audioFileName;
To play a file from the Resources directory, first copy it to external storage. For example, you could define the following function:
// Copy resource file to SD card, and return a native path.
// Return undefined if we can't copy the file.
function getOrCopyAudioFile(resourceFilename) {
var outFile = Ti.Filesystem.getFile(Ti.Filesystem.externalStorageDirectory, 'sound', 'cricket.wav');
var outPath = outFile.nativePath;
if (! outFile.exists()) {
var outDir = Ti.Filesystem.getFile(Ti.Filesystem.externalStorageDirectory, 'sound');
if (! outDir.isDirectory()) {
if (! outDir.createDirectory()) {
Ti.API.debug("Failed to create directory.");
outDir = null;
return undefined;
}
}
outDir = null;
var inFile = Ti.Filesystem.getFile(Ti.Filesystem.resourcesDirectory, 'cricket.wav');
try {
inFile.copy(outPath);
} catch (ex) {
Ti.API.debug("Failed to copy file.");
inFile = null;
return undefined;
}
inFile = null;
}
outFile = null;
return outPath;
}
Then when creating a notification, specify the sound like this:
var sound = getOrCopyAudioFile();
if (sound) {
notification.sound = sound;
}
Style object that can apply a rich notification style.
Style object that can apply a rich notification style.
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. On platform versions that don't offer expanded notifications, styles that depend on expanded notifications have no effect.
Text to scroll across the screen when this item is added to the status bar.
Text to scroll across the screen when this item is added to the status bar.
For devices running Android 5.0 (API 21) and greater, the ticket text is no longer displayed in the status bar. However, this property is used as an audible notification if accessibility services are enabled.
Allows user to conceal private information of the notification on the lockscreen.
Requires: Android 5.0 and later
This property only works on devices running Android 5.0 (API 21) and greater.
This API can be assigned the following constants:
Default: undefined but behaves as Titanium.Android.VISIBILITY_PUBLIC
Will wake up the device for the given time (in milliseconds) when the notification is shown.
The application needs to also set the android.permission.WAKE_LOCK permission
in the Android manifest section of the tiapp.xml file.
Default: 0
The timestamp for the notification (defaults to the current time).
The timestamp for the notification (defaults to the current time).
If the timestamp is set to 0, no time is displayed in the notification window for this notification.
Add an action button to the notification
Up to three actions buttons can be added, additional buttons will be ignored.
Icon of the action button as URL or resource ID
Title of the action button
Intent of the action button
Adds the specified callback as an event listener for the named event.
Name of the event.
Callback function to invoke when the event is fired.
Applies the properties to the proxy.
Properties are supplied as a dictionary. Each key-value pair in the object is applied to the proxy such that myproxy[key] = value.
A dictionary of properties to apply.
Fires a synthesized event to any registered listeners.
Name of the event.
A dictionary of keys and values to add to the Titanium.Event object sent to the listeners.
Removes the specified callback as an event listener for the named event.
Multiple listeners can be registered for the same event, so the
callback parameter is used to determine which listener to remove.
When adding a listener, you must save a reference to the callback function in order to remove the listener later:
var listener = function() { Ti.API.info("Event listener called."); }
window.addEventListener('click', listener);
To remove the listener, pass in a reference to the callback function:
window.removeEventListener('click', listener);
Name of the event.
Callback function to remove. Must be the same function passed to addEventListener.
Sets the value of the audioStreamType property.
New value for the property.
Sets the value of the bubbleParent property.
New value for the property.
Sets the value of the category property.
New value for the property.
Sets the value of the color property.
New value for the property.
Sets the value of the contentIntent property.
New value for the property.
Sets the value of the contentText property.
New value for the property.
Sets the value of the contentTitle property.
New value for the property.
Sets the value of the contentView property.
New value for the property.
Sets the value of the defaults property.
New value for the property.
Sets the value of the deleteIntent property.
New value for the property.
Sets the value of the flags property.
New value for the property.
Sets the value of the groupKey property.
New value for the property.
Sets the value of the groupSummary property.
New value for the property.
Sets the value of the icon property.
New value for the property.
Sets the value of the largeIcon property.
New value for the property.
Sets the latest event info using the built-in notification view for this notification.
Title to display when the notification is expanded.
Text to display when the notification is expanded.
Intent to launch when the user clicks on the notification.
Sets the value of the ledARGB property.
New value for the property.
Sets the value of the ledOffMS property.
New value for the property.
Sets the value of the ledOnMS property.
New value for the property.
Sets the value of the lifecycleContainer property.
New value for the property.
Sets the value of the number property.
New value for the property.
Sets the value of the priority property.
New value for the property.
Set the progress this notification represents.
Defines the maximum value the progress can take.
Defines the progress value, between 0 and max.
Allows to enable the indeterminate mode.
Sets the value of the sound property.
New value for the property.
Sets the value of the style property.
New value for the property.
Sets the value of the tickerText property.
New value for the property.
Sets the value of the visibility property.
New value for the property.
Sets the value of the wakeLock property.
New value for the property.