Ionic Framework 4 is almost here. Preview the beta docs and try it out now! Try Ionic 4 Beta

Local Notifications

Improve this doc

This plugin allows you to display local notifications on the device

Repo: https://github.com/katzer/cordova-plugin-local-notifications

Installation

  1. Install the Cordova and Ionic Native plugins:
    $ ionic cordova plugin add cordova-plugin-local-notification
    $ npm install --save @ionic-native/local-notifications
    
  2. Add this plugin to your app's module

Supported platforms

Usage

import { LocalNotifications } from '@ionic-native/local-notifications';


constructor(private localNotifications: LocalNotifications) { }

...


// Schedule a single notification
this.localNotifications.schedule({
  id: 1,
  text: 'Single ILocalNotification',
  sound: isAndroid? 'file://sound.mp3': 'file://beep.caf',
  data: { secret: key }
});


// Schedule multiple notifications
this.localNotifications.schedule([{
   id: 1,
   text: 'Multi ILocalNotification 1',
   sound: isAndroid ? 'file://sound.mp3': 'file://beep.caf',
   data: { secret:key }
  },{
   id: 2,
   title: 'Local ILocalNotification Example',
   text: 'Multi ILocalNotification 2',
   icon: 'http://example.com/icon.png'
}]);


// Schedule delayed notification
this.localNotifications.schedule({
   text: 'Delayed ILocalNotification',
   trigger: {at: new Date(new Date().getTime() + 3600)},
   led: 'FF0000',
   sound: null
});

Instance Members

schedule(options)

Schedules a single or multiple notifications

Param Type Details
options Notification|Array.<ILocalNotification>

optional

update(options)

Updates a previously scheduled notification. Must include the id in the options parameter.

Param Type Details
options ILocalNotification

optional

clear(notificationId)

Clears single or multiple notifications

Param Type Details
notificationId any

A single notification id, or an array of notification ids.

Returns: Promise<any> Returns a promise when the notification had been cleared

clearAll()

Clears all notifications

Returns: Promise<any> Returns a promise when all notifications have cleared

cancel(notificationId)

Cancels single or multiple notifications

Param Type Details
notificationId any

A single notification id, or an array of notification ids.

Returns: Promise<any> Returns a promise when the notification is canceled

cancelAll()

Cancels all notifications

Returns: Promise<any> Returns a promise when all notifications are canceled

isPresent(notificationId)

Checks presence of a notification

Param Type Details
notificationId number

Returns: Promise<boolean>

isScheduled(notificationId)

Checks is a notification is scheduled

Param Type Details
notificationId number

Returns: Promise<boolean>

isTriggered(notificationId)

Checks if a notification is triggered

Param Type Details
notificationId number

Returns: Promise<boolean>

getIds()

Get all the notification ids

Returns: Promise<Array<number>>

getTriggeredIds()

Get the ids of triggered notifications

Returns: Promise<Array<number>>

getScheduledIds()

Get the ids of scheduled notifications

Returns: Promise<Array<number>> Returns a promise

get(notificationId)

Get a notification object

Param Type Details
notificationId any

The id of the notification to get

Returns: Promise<ILocalNotification>

getScheduled(notificationId)

Get a scheduled notification object

Param Type Details
notificationId any

The id of the notification to get

Returns: Promise<ILocalNotification>

getTriggered(notificationId)

Get a triggered notification object

Param Type Details
notificationId

The id of the notification to get

Returns: Promise<ILocalNotification>

getAll()

Get all notification objects

Returns: Promise<Array<ILocalNotification>>

getAllScheduled()

Get all scheduled notification objects

Returns: Promise<Array<ILocalNotification>>

getAllTriggered()

Get all triggered notification objects

Returns: Promise<Array<ILocalNotification>>

requestPermission()

Request permission to show notifications if not already granted.

Returns: Promise<boolean>

hasPermission()

Informs if the app has the permission to show notifications.

Returns: Promise<boolean>

addActions(groupId, actions)

Adds a group of actions

Param Type Details
groupId

The id of the action group

actions

The actions of this group

Returns: Promise<any>

removeActions(groupId)

Removes a group of actions

Param Type Details
groupId

The id of the action group

Returns: Promise<any>

hasActions(groupId)

Checks if a group of actions is defined

Param Type Details
groupId

The id of the action group

Returns: Promise<boolean> Whether the group is defined

getDefaults()

Gets the (platform specific) default settings.

Returns: Promise<any> An object with all default settings

setDefaults()

Overwrites the (platform specific) default settings.

Returns: Promise<any>

on(eventName)

Sets a callback for a specific event

Param Type Details
eventName string

The name of the event. Available events: schedule, trigger, click, update, clear, clearall, cancel, cancelall. Custom event names are possible for actions

Returns: Observable

fireEvent(args)

Not an official interface, however its possible to manually fire events.

Param Type Details
args

Optional arguments

fireQueuedEvents()

Fire queued events once the device is ready and all listeners are registered.

Returns: Promise<any>

ILocalNotification

Param Type Details
id number

A unique identifier required to clear, cancel, update or retrieve the local notification in the future Default: 0

(optional)
title string

First row of the notification Default: Empty string (iOS) or the app name (Android)

(optional)
text string | string[]

Second row of the notification Default: Empty string

(optional)
badge number

The number currently set as the badge of the app icon in Springboard (iOS) or at the right-hand side of the local notification (Android) Default: 0 (which means don't show a number)

(optional)
sound string

Uri of the file containing the sound to play when an alert is displayed Default: res://platform_default

(optional)
data any

Arbitrary data, objects will be encoded to JSON string Default: null

(optional)
icon string

ANDROID ONLY Uri of the icon that is shown in the ticker and notification Default: res://icon

(optional)
smallIcon string

ANDROID ONLY Uri of the resource (only res://) to use in the notification layouts. Different classes of devices may return different sizes Default: res://ic_popup_reminder

(optional)
color string

ANDROID ONLY RGB value for the background color of the smallIcon. Default: Androids COLOR_DEFAULT, which will vary based on Android version.

(optional)
vibrate boolean

ANDROID ONLY Use the default notification vibrate.

(optional)
led { color: string; on: number; off: number } | any[] | boolean | string

ANDROID ONLY Define the blinking of the LED on the device. If set to true, the LED will blink in the default color with timings for on and off set to 1000 ms. If set to a string, the LED will blink in this ARGB value with timings for on and off set to 1000 ms. If set to an array, the value of the key 0 will be used as the color, the value of the key 1 will be used as the 'on' timing, the value of the key 2 will be used as the 'off' timing

(optional)
priority number

Notification priority. Integers between -2 and 2, whereas -2 is minimum and 2 is maximum priority

(optional)
silent boolean

Is a silent notification

(optional)
launch boolean

Specifies whether the a click on the notification causes the app to launch in the foreground

(optional)
wakeup boolean

ANDROID ONLY Wakeup the device. (default is true)

(optional)
timeoutAfter number |

ANDROID ONLY Specifies a duration in milliseconds after which this notification should be canceled, if it is not already canceled.

(optional)
false
actions string | ILocalNotificationAction[]

Actions id or actions

(optional)
trigger ILocalNotificationTrigger

When to trigger the notification

(optional)
attachments string[]

A list of image attachments

(optional)
clock boolean | string

ANDROID ONLY If and how the notification shall show the when date. Possbile values: boolean: true equals 'clock', false disable a watch/counter 'clock': Show the when date in the content view 'chronometer': Show a stopwatch

(optional)
progressBar ILocalNotificationProgressBar | boolean

Shows a progress bar Setting a boolean is a shortcut for {enabled: true/false} respectively

(optional)
group string

ANDROID ONLY If multiple notifications have the same group your app can present them as a single group.

(optional)
groupSummary boolean

ANDROID ONLY If set to 'true' this notification could use 'summary' to summarize the contents of the whole group

(optional)
summary string

ANDROID ONLY Summary of the whole notification group. Should be used in conjuntion with 'groupSummary' set to true

(optional)
number number

ANDROID ONLY Sets the number of items this notification represents.

(optional)
sticky boolean

ANDROID ONLY Set whether this is an "ongoing" notification. Ongoing notifications cannot be dismissed by the user, so your application or service must take care of canceling them.

(optional)
autoClear boolean

ANDROID ONLY Make this notification automatically dismissed when the user touches it.

(optional)
lockscreen boolean

ANDROID ONLY If set to true the notification will be show in its entirety on all lockscreens. If set to false it will not be revealed on a secure lockscreen.

(optional)
defaults number

ANDROID ONLY Set the default notification options that will be used. The value should be one or more of the following fields combined with bitwise-or: DEFAULT_SOUND, DEFAULT_VIBRATE, DEFAULT_LIGHTS.

(optional)
channel string

ANDROID ONLY Specifies the channel the notification should be delivered on.

(optional)
mediaSession string

ANDROID ONLY Set the token for the media session

(optional)
foreground boolean

Make this notification show when app in foreground.

(optional)

API

Native

General