# Titanium.Android.Notification

UI notifications that can be sent while the application is in the background.

Availability
1.5

# Overview

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:

# Android 5.0 Changes

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.

# Examples

# Simple Notification Example

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 Titanium.Android.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 Titanium.Android.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_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);

# Bundled Notifications Example

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
    })
);

# Properties

# audioStreamType

Availability
1.5
audioStreamType :Number

The audio stream type to use when playing the sound.

Specify one of the STREAM constants from Titanium.Android.


# category

Availability
3.6.0
category :String

Sets the notification's category.

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.


# channelId

Availability
7.0.0
channelId :String

The channel id specified for the notification.


# color

Availability
7.0.0
color :String

Accent color used behind icon.

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.


# contentIntent

Availability
1.5

The PendingIntent to execute when the expanded status entry is clicked.


# contentText

Availability
1.5
contentText :String

Description text of the notification.


# contentTitle

Availability
1.5
contentTitle :String

Title of the notification.


# contentView

Availability
1.5

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 Titanium.Android.RemoteViews methods to update the displayed notification.


# defaults

Availability
1.5
defaults :Number

Specifies which values should be taken from the defaults.

Specify the bitwise OR of the desired values: DEFAULT_LIGHTS, DEFAULT_SOUND, and DEFAULT_VIBRATE. Use DEFAULT_ALL to specify that all values should be taken from the defaults.


# deleteIntent

Availability
1.5

The PendingIntent to execute when the status entry is deleted by the user with the "Clear All Notifications" button.


# groupKey

Availability
6.2.0
groupKey :String

The group key that the notification will belong to.


# groupSummary

Availability
6.2.0
groupSummary :Boolean

Specifies if this is a group summary notification.


# icon

Availability
1.5
icon :Number | String

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 R object:

icon: Ti.App.Android.R.drawable.my_icon,

See R for more information on accessing Android resources by ID.


# largeIcon

Availability
4.2.0
largeIcon :Number | String

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 R object:

icon: Ti.App.Android.R.drawable.my_large_icon,

See R for more information on accessing Android resources by ID.


# ledARGB

Availability
1.5
ledARGB :Number

The color for the LED to blink.


# ledOffMS

Availability
1.5
ledOffMS :Number

The number of milliseconds for the LED to be off while it's flashing.


# ledOnMS

Availability
1.5
ledOnMS :Number

The number of milliseconds for the LED to be on while it's flashing.


# number

Availability
1.5
number :Number

The number of events that this notification represents.


# priority

Availability
3.6.0
priority :Number

Sets the priority of the notification.

This property only works for devices running Android 4.1 (API 16) and greater.

Default: undefined but behaves as Titanium.Android.PRIORITY_DEFAULT


# sound

Availability
1.5
sound :String

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 (resRawDirectory) or the external storage directory (externalStorageDirectory).

Note that this sound property is ignored on Android 8.0 and above. On these OS versions, you must use the sound property and that sound will play for any notification posted under that channel. Also, you will still need to set this notification's sound property for OS versions older than Android 8.0 too, meaning that the sound URL needs to be set in both places.

To play a raw resource file, place the audio file in the platform/android/res/raw folder and reference it as:

notification.sound = Ti.Filesystem.resRawDirectory + 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

Availability
5.4.0

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.


# tickerText

Availability
1.5
tickerText :String

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.


# visibility

Availability
3.6.0
visibility :Number

Allows user to conceal private information of the notification on the lockscreen.

This property only works on devices running Android 5.0 (API 21) and greater.

Default: undefined but behaves as Titanium.Android.VISIBILITY_PUBLIC


# wakeLock

Availability
6.2.0
wakeLock :wakeLockOptions

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.

<ti:app>
    <android>
        <manifest>
            <uses-permission android:name="android.permission.WAKE_LOCK" />
        </manifest>
    </android>
</ti:app>

Default: 0


# when

Availability
1.5
when :Date | Number

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.

# Methods

# addAction

Availability
6.2.0
addAction(icon, title, intent) void

Add an action button to the notification

Up to three actions buttons can be added, additional buttons will be ignored.

Parameters

Name Type Description
icon Number | String

Icon of the action button as URL or resource ID

title String

Title of the action button

intent Titanium.Android.PendingIntent

Intent of the action button

Returns

Type
void

# setLatestEventInfo

Availability
1.5
setLatestEventInfo(contentTitle, contentText, contentIntent) void

Sets the latest event info using the built-in notification view for this notification.

Parameters

Name Type Description
contentTitle String

Title to display when the notification is expanded.

contentText String

Text to display when the notification is expanded.

contentIntent Titanium.Android.PendingIntent

Intent to launch when the user clicks on the notification.

Returns

Type
void

# setProgress

Availability
6.1.0
setProgress(max, progress, indeterminate) void

Set the progress this notification represents.

Parameters

Name Type Description
max Number

Defines the maximum value the progress can take.

progress Number

Defines the progress value, between 0 and max.

indeterminate Boolean

Allows to enable the indeterminate mode.

Returns

Type
void