# Titanium.Android.Notification

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

- Source: https://titaniumsdk.com/docs/sdk/13.0.0/Titanium.Android.Notification
- Titanium SDK version: 13.0.0
- Kind: proxy
- Platforms: Android
- Since: Titanium SDK 1.5
- Extends: Titanium.Proxy
- Inheritance: Titanium.Proxy

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](https://titaniumsdk.com/docs/sdk/Titanium.UI.Notification.md).

To create a notification, use the [Titanium.Android.createNotification](https://titaniumsdk.com/docs/sdk/Titanium.Android.md#createNotification) method.

Pass the Notification object to the methods of the [Titanium.Android.NotificationManager](https://titaniumsdk.com/docs/sdk/Titanium.Android.NotificationManager.md) class
to send or cancel notifications.

For examples of using Notifications, see [Android Notifications](#!/guide/Android_Notifications).

Further Reading:

  * [Android Developers: Notifications](https://developer.android.com/design/patterns/notifications.html)

#### 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.

## Example: 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 [Intent](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 [Notification.sound](Titanium.Android.Notification.sound).

``` js
// 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);
```

## Example: Bundled Notifications Example

The following example shows how to create bundled notifications.

``` js
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

- Type: Number
- Platforms: Android

The audio stream type to use when playing the sound.

Specify one of the `STREAM` constants from [Titanium.Android](https://titaniumsdk.com/docs/sdk/Titanium.Android.md).

Accepts: `Titanium.Android.STREAM_ALARM`, `Titanium.Android.STREAM_DEFAULT`, `Titanium.Android.STREAM_MUSIC`, `Titanium.Android.STREAM_NOTIFICATION`, `Titanium.Android.STREAM_RING`, `Titanium.Android.STREAM_SYSTEM`, `Titanium.Android.STREAM_VOICE_CALL`

### category

- Type: String
- Platforms: Android
- Since: Titanium SDK 3.6.0

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.

Accepts: `Titanium.Android.CATEGORY_ALARM`, `Titanium.Android.CATEGORY_ALTERNATIVE`, `Titanium.Android.CATEGORY_BROWSABLE`, `Titanium.Android.CATEGORY_CALL`, `Titanium.Android.CATEGORY_DEFAULT`, `Titanium.Android.CATEGORY_DEVELOPMENT_PREFERENCE`, `Titanium.Android.CATEGORY_EMAIL`, `Titanium.Android.CATEGORY_EMBED`, `Titanium.Android.CATEGORY_ERROR`, `Titanium.Android.CATEGORY_EVENT`, `Titanium.Android.CATEGORY_FRAMEWORK_INSTRUMENTATION_TEST`, `Titanium.Android.CATEGORY_HOME`, `Titanium.Android.CATEGORY_INFO`, `Titanium.Android.CATEGORY_LAUNCHER`, `Titanium.Android.CATEGORY_MESSAGE`, `Titanium.Android.CATEGORY_MONKEY`, `Titanium.Android.CATEGORY_OPENABLE`, `Titanium.Android.CATEGORY_PREFERENCE`, `Titanium.Android.CATEGORY_PROGRESS`, `Titanium.Android.CATEGORY_PROMO`, `Titanium.Android.CATEGORY_RECOMMENDATION`, `Titanium.Android.CATEGORY_SAMPLE_CODE`, `Titanium.Android.CATEGORY_SELECTED_ALTERNATIVE`, `Titanium.Android.CATEGORY_SERVICE`, `Titanium.Android.CATEGORY_SOCIAL`, `Titanium.Android.CATEGORY_STATUS`, `Titanium.Android.CATEGORY_TAB`, `Titanium.Android.CATEGORY_TEST`, `Titanium.Android.CATEGORY_TRANSPORT`, `Titanium.Android.CATEGORY_UNIT_TEST`

### channelId

- Type: String
- Platforms: Android
- Since: Titanium SDK 7.0.0
- Requires: Android 8.0+

The channel id specified for the notification.

### color

- Type: String
- Platforms: Android
- Since: Titanium SDK 7.0.0

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](https://titaniumsdk.com/docs/sdk/Titanium.UI.md).

See Android Reference for the [color](https://developer.android.com/reference/android/app/Notification.html#color) property.

### contentIntent

- Type: Titanium.Android.PendingIntent
- Platforms: Android

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

### contentText

- Type: String
- Platforms: Android

Description text of the notification.

### contentTitle

- Type: String
- Platforms: Android

Title of the notification.

### contentView

- Type: Titanium.Android.RemoteViews
- Platforms: Android
- Permission: write-only

Custom layout to display in the notification.

Calling [setLatestEventInfo](https://titaniumsdk.com/docs/sdk/Titanium.Android.Notification.md#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](https://titaniumsdk.com/docs/sdk/Titanium.Android.RemoteViews.md) methods to update the displayed
notification.

### defaults

- Type: Number
- Platforms: Android

Specifies which values should be taken from the defaults.

Specify the bitwise OR of the desired values:
[Titanium.Android.DEFAULT_LIGHTS](https://titaniumsdk.com/docs/sdk/Titanium.Android.md#DEFAULT_LIGHTS), [Titanium.Android.DEFAULT_SOUND](https://titaniumsdk.com/docs/sdk/Titanium.Android.md#DEFAULT_SOUND), and
[Titanium.Android.DEFAULT_VIBRATE](https://titaniumsdk.com/docs/sdk/Titanium.Android.md#DEFAULT_VIBRATE). Use [Titanium.Android.DEFAULT_ALL](https://titaniumsdk.com/docs/sdk/Titanium.Android.md#DEFAULT_ALL) to specify
that all values should be taken from the defaults.

Accepts: `Titanium.Android.DEFAULT_ALL`, `Titanium.Android.DEFAULT_LIGHTS`, `Titanium.Android.DEFAULT_SOUND`, `Titanium.Android.DEFAULT_VIBRATE`

### deleteIntent

- Type: Titanium.Android.PendingIntent
- Platforms: Android

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

### flags

- Type: Number
- Platforms: Android
- Default: `<Titanium.Android.FLAG_AUTO_CANCEL>`

Set of flags for the notification.

Accepts: `Titanium.Android.FLAG_AUTO_CANCEL`, `Titanium.Android.FLAG_INSISTENT`, `Titanium.Android.FLAG_NO_CLEAR`, `Titanium.Android.FLAG_ONGOING_EVENT`, `Titanium.Android.FLAG_ONLY_ALERT_ONCE`, `Titanium.Android.FLAG_SHOW_LIGHTS`

### groupKey

- Type: String
- Platforms: Android
- Since: Titanium SDK 6.2.0
- Requires: Android 5.1+

The group key that the notification will belong to.

### groupSummary

- Type: Boolean
- Platforms: Android
- Since: Titanium SDK 6.2.0
- Requires: Android 5.1+

Specifies if this is a group summary notification.

### icon

- Type: Number | String
- Platforms: Android

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](https://titaniumsdk.com/docs/sdk/Titanium.App.Android.md#R)
object:

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

See [Titanium.App.Android.R](https://titaniumsdk.com/docs/sdk/Titanium.App.Android.md#R) for more information on accessing
Android resources by ID.

### largeIcon

- Type: Number | String
- Platforms: Android
- Since: Titanium SDK 4.2.0

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](https://titaniumsdk.com/docs/sdk/Titanium.App.Android.md#R)
object:

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

See [Titanium.App.Android.R](https://titaniumsdk.com/docs/sdk/Titanium.App.Android.md#R) for more information on accessing
Android resources by ID.

### ledARGB

- Type: Number
- Platforms: Android

The color for the LED to blink.

### ledOffMS

- Type: Number
- Platforms: Android

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

### ledOnMS

- Type: Number
- Platforms: Android

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

### number

- Type: Number
- Platforms: Android

The number of events that this notification represents.

### priority

- Type: Number
- Platforms: Android
- Since: Titanium SDK 3.6.0
- Default: `undefined but behaves as Titanium.Android.PRIORITY_DEFAULT`

Sets the priority of the notification.

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

Accepts: `Titanium.Android.PRIORITY_DEFAULT`, `Titanium.Android.PRIORITY_HIGH`, `Titanium.Android.PRIORITY_LOW`, `Titanium.Android.PRIORITY_MAX`, `Titanium.Android.PRIORITY_MIN`

### sound

- Type: String
- Platforms: Android
- Requires: Android ≤7.1

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](https://titaniumsdk.com/docs/sdk/Titanium.Filesystem.md#resRawDirectory)) or the
external storage directory
([Filesystem.externalStorageDirectory](https://titaniumsdk.com/docs/sdk/Titanium.Filesystem.md#externalStorageDirectory)).

Note that this sound property is ignored on Android 8.0 and above. On these OS versions,
you must use the [NotificationChannel.sound](https://titaniumsdk.com/docs/sdk/Titanium.Android.NotificationChannel.md#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:

``` js
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:

``` js
// 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:

``` js
var sound = getOrCopyAudioFile();
if (sound) {
    notification.sound = sound;
}
```

### style

- Type: Titanium.Android.BigTextStyle | Titanium.Android.BigPictureStyle
- Platforms: Android
- Since: Titanium SDK 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

- Type: String
- Platforms: Android

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

- Type: Number
- Platforms: Android
- Since: Titanium SDK 3.6.0
- Default: `undefined but behaves as Titanium.Android.VISIBILITY_PUBLIC`

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.

Accepts: `Titanium.Android.VISIBILITY_PRIVATE`, `Titanium.Android.VISIBILITY_PUBLIC`, `Titanium.Android.VISIBILITY_SECRET`

### wakeLock

- Type: wakeLockOptions
- Platforms: Android
- Since: Titanium SDK 6.2.0
- Default: `0`

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.

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

### when

- Type: Date | Number
- Platforms: Android

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

- Platforms: Android
- Since: Titanium SDK 6.2.0

Add an action button to the notification

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

Parameters:

- `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

### setLatestEventInfo

- Platforms: Android

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

Parameters:

- `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.

### setProgress

- Platforms: Android
- Since: Titanium SDK 6.1.0

Set the progress this notification represents.

Parameters:

- `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.

## Inherited members

7 members are inherited. Each is documented on the type that declares it.

- [Titanium.Proxy](https://titaniumsdk.com/docs/sdk/13.0.0/Titanium.Proxy.md): `addEventListener`, `apiName`, `applyProperties`, `bubbleParent`, `fireEvent`, `lifecycleContainer`, `removeEventListener`

---

- This corpus documents Titanium SDK 13.4.1. Anything here that does not name a version describes 13.4.1.
- Titanium is maintained by TiDev. The Appcelerator toolchain is retired: there is no `appc` CLI, no Appcelerator Studio and no hosted build service. The supported CLI is `titanium` on npm, invoked as `ti`.