NotificationAndroid

Android Only

The interface for Android specific options which are applied to a notification.


To learn more about Android notifications, view the Android documentation for full examples and usage.

Properties

actions

An array of AndroidAction interfaces.

actions?: AndroidAction[];

Adds quick actions to a notification. Quick Actions enable users to interact with your application directly from the notification body, providing an overall greater user experience.

View the Quick Actions documentation for more information.

asForegroundService

When set to true this notification will be shown as a foreground service.

asForegroundService?: undefined | false | true;

The application can only display one foreground service notification at once. If a foreground service notification is already running and a new notification with this flag set to true is provided, the service will stop the existing service and start a new one.

Ensure a foreground service runner function has been provided to registerForegroundService. Without one, the notification will not be displayed.

View the Foreground Service documentation for more information.

Defaults to false.

autoCancel

Setting this flag will make it so the notification is automatically canceled when the user presses it in the panel.

autoCancel?: undefined | false | true;

By default when the user taps a notification it is automatically removed from the notification panel. Setting this to false will keep the notification in the panel.

If false, the notification will persist in the notification panel after being pressed. It will remain there until the user removes it (e.g. swipes away) or is cancelled via cancelNotification.

Defaults to true.

badgeCount

Overrides the current number of active notifications shown on the device.

badgeCount?: undefined | number;

If no number is provided, the system displays the current number of active notifications.

badgeIconType

Android Only

Sets the type of badge used when the notification is being displayed in badge mode.

badgeIconType?: AndroidBadgeIconType;

View the Badges documentation for more information and usage examples.

Defaults to AndroidBadgeIconType.LARGE.

category

Assigns the notification to a category. Use the one which best describes the notification.

category?: AndroidCategory;

The category may be used by the device for ranking and filtering. It has no visual or behavioural impact.

channelId

Specifies the AndroidChannel which the notification will be delivered on.

channelId?: undefined | string;

On Android 8.0 (API 26) the channel ID is required. Providing a invalid channel ID will throw an error. View the Channels & Groups documentation for more information and usage examples.

chronometerDirection

If showChronometer is true, the direction of the chronometer can be changed to count down instead of up.

chronometerDirection?:  | ;

Has no effect if showChronometer is false.

Defaults to up.

circularLargeIcon

Whether the large icon should be circular.

circularLargeIcon?: undefined | false | true;

If true, the large icon will be rounded in the shape of a circle.

Defaults to false.

color

Set an custom accent color for the notification. If not provided, the default notification system color will be used.

color?: AndroidColor | string;

The color can be a predefined system AndroidColor or hexadecimal.

View the Color documentation for more information.

colorized

When asForegroundService is true, the notification will use the provided color property to set a background color on the notification. This property has no effect when asForegroundService is false.

colorized?: undefined | false | true;

This should only be used for high priority ongoing tasks like navigation, an ongoing call, or other similarly high-priority events for the user.

View the Foreground Service documentation for more information.

Defaults to false.

defaults

Android Only

For devices without notification channel support, this property sets the default behaviour for a notification.

defaults?: AndroidDefaults[];

On API Level >= 26, this has no effect.

See AndroidDefaults for more information.

flags

Set any additional flags

flags?: AndroidFlags[];

fullScreenAction

The fullScreenAction property allows you to show a custom UI in full screen when the notification is displayed.

fullScreenAction?: NotificationFullScreenAction;

View the FullScreenAction documentation to learn more.

groupAlertBehavior

Sets the group alert behavior for this notification. Use this method to mute this notification if alerts for this notification's group should be handled by a different notification. This is only applicable for notifications that belong to a groupId. This must be called on all notifications you want to mute. For example, if you want only the summary of your group to make noise, all children in the group should have the group alert behavior AndroidGroupAlertBehavior.SUMMARY.

groupAlertBehavior?: AndroidGroupAlertBehavior;

View the Android Grouping & Sorting guide documentation to learn more.

groupId

Set this notification to be part of a group of notifications sharing the same key. Grouped notifications may display in a cluster or stack on devices which support such rendering.

groupId?: undefined | string;

On some devices, the system may automatically group notifications.

View the Android Grouping & Sorting guide documentation to learn more.

groupSummary

Whether this notification should be a group summary.

groupSummary?: undefined | false | true;

If true, Set this notification to be the group summary for a group of notifications. Grouped notifications may display in a cluster or stack on devices which support such rendering. Requires a groupId key to be set.

Defaults to false.

importance

Android Only

Set a notification importance for devices without channel support.

importance?: AndroidImportance;

Devices using Android API Level < 26 have no channel support, meaning incoming notifications won't be assigned an importance level from the channel. If your application supports devices without channel support, set this property to directly assign an importance level to the incoming notification.

Defaults to AndroidImportance.DEFAULT.

View the Appearance documentation to learn more.

inputHistory

The local user input history for this notification.

inputHistory?: string[];

Input history is shown on supported devices below the main notification body. History of the users input with the notification should be shown when receiving action input by updating the existing notification. It is recommended to clear the history when it is no longer relevant (e.g. someone has responded to the users input).

largeIcon

A local file path using the 'require()' method or a remote http to the picture to display.

largeIcon?: string | number | object;

Sets a large icon on the notification.

View the Android Appearance documentation to learn more about this property.

lightUpScreen

When set to true the screen will light up when the notification is displayed.

lightUpScreen?: undefined | false | true;

Defaults to false.

lights

Sets the color and frequency of the light pattern. This only has effect on supported devices.

lights?: [AndroidColor | string, number, number];

The option takes an array containing a hexadecimal color value or predefined AndroidColor, along with the number of milliseconds to show the light, and the number of milliseconds to turn off the light. The light frequency pattern is repeated.

View the Lights documentation for more information.

localOnly

Sets whether the notification will only appear on the local device.

localOnly?: undefined | false | true;

Users who have connected devices which support notifications (such as a smart watch) will receive an alert for the notification on that device. If set to true, the notification will only alert on the main device.

Defaults to false.

loopSound

Set whether the sound should loop, by default, the sound will only play once.

loopSound?: undefined | false | true;

This property is useful if you have an ongoing notification.

ongoing

Set whether this is an on-going notification.

ongoing?: undefined | false | true;

Setting this value to true changes the default behaviour of a notification:

  • Ongoing notifications are sorted above the regular notifications in the notification panel.
  • Ongoing notifications do not have an 'X' close button, and are not affected by the "Clear all" button.

View the Ongoing documentation for more information.

onlyAlertOnce

Notifications with the same id will only show a single instance at any one time on your device, however will still alert the user (for example, by making a sound).

onlyAlertOnce?: undefined | false | true;

If this flag is set to true, notifications with the same id will only alert the user once whilst the notification is visible.

This property is commonly used when frequently updating a notification (such as updating the progress bar).

pressAction

By default notifications have no behaviour when a user presses them. The pressAction property allows you to set what happens when a user presses the notification.

pressAction?: NotificationPressAction;

View the Interaction documentation to learn more.

progress

A notification can show current progress of a task. The progress state can either be fixed or indeterminate (unknown).

progress?: AndroidProgress;

View the Progress Indicators documentation to learn more.

showChronometer

Shows a counting timer on the notification, useful for on-going notifications such as a phone call.

showChronometer?: undefined | false | true;

If no timestamp is provided, a counter will display on the notification starting from 00:00. If a timestamp is provided, the number of hours/minutes/seconds since that have elapsed since that value will be shown instead.

Defaults to false.

View the Timers documentation to learn more.

showTimestamp

Sets whether the timestamp provided is shown in the notification.

showTimestamp?: undefined | false | true;

Setting this field is useful for notifications which are more informative with a timestamp, such as an E-Mail.

If no timestamp is set, this field has no effect.

View the Timestamps documentation to learn more.

smallIcon

The small icon to show in the heads-up notification.

smallIcon?: undefined | string;

View the Icons documentation to learn more.

smallIconLevel

An additional level parameter for when the icon is an instance of a Android LevelListDrawable.

smallIconLevel?: undefined | number;

sortKey

Set a sort key that orders this notification among other notifications from the same package. This can be useful if an external sort was already applied and an app would like to preserve this. Notifications will be sorted lexicographically using this value, although providing different priorities in addition to providing sort key may cause this value to be ignored.

sortKey?: undefined | string;

If a groupId has been set, the sort key can also be used to order members of a notification group.

View the Android Grouping & Sorting documentation to learn more.

sound

Android Only

Overrides the sound the notification is displayed with.

sound?: undefined | string;

The default value is to play no sound. To play the default system sound use 'default'.

This setting has no behaviour on Android after API level version 26, instead you can set the sound on the notification channels.

View the Sound documentation for more information.

style

Styled notifications provide users with more informative content and additional functionality.

style?: AndroidBigPictureStyle | AndroidBigTextStyle | AndroidInboxStyle | AndroidMessagingStyle;

Android supports different styles, however only one can be used with a notification.

View the Styles documentation to learn more view usage examples.

tag

Sets a tag on the notification.

tag?: undefined | string;

Tags can be used to query groups notifications by the tag value. Setting a tag has no impact on the notification itself.

ticker

Text that summarizes this notification for accessibility services. As of the Android L release, this text is no longer shown on screen, but it is still useful to accessibility services (where it serves as an audible announcement of the notification's appearance).

ticker?: undefined | string;

Ticker text does not show in the notification.

timeoutAfter

Sets the time in milliseconds at which the notification should be automatically cancelled once displayed, if it is not already cancelled.

timeoutAfter?: undefined | number;

timestamp

The timestamp in milliseconds for this notification. Notifications in the panel are sorted by this time.

timestamp?: undefined | number;

The timestamp can be used with other properties to change the behaviour of a notification:

  • Use with showTimestamp to show the timestamp to the users.
  • Use with showChronometer to create a on-going timer.

View the Timers documentation to learn more.

vibrationPattern

Sets the vibration pattern the notification uses when displayed. Must be an even amount of numbers.

vibrationPattern?: number[];

View the Vibration documentation to learn more.

visibility

Sets the visibility for this notification. This may be used for apps which show user sensitive information (e.g. a banking app).

visibility?: AndroidVisibility;

Defaults to AndroidVisibility.PRIVATE.

View the Visibility documentation to learn more.


Copyright 2020 - 2021 © Invertase Limited

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License and code samples are licensed under the Apache 2.0 License.

All product names, logos, and brands are property of their respective owners. All company, product and service names used in this website are for identification purposes only. Use of these names, logos, and brands does not imply endorsement.