Package detail

SAMPLE APP :point_right:

A notification is a message you display to the user outside of your app's normal UI. When you tell the system to issue a notification, it first appears as an icon in the notification area. To see the details of the notification, the user opens the notification drawer. Both the notification area and the notification drawer are system-controlled areas that the user can view at any time.

Notification components

• Header area
• Content area
• Action area

How notifications may be noticed

• Showing a status bar icon
• Appearing on the lock screen
• Playing a sound or vibrating
• Peeking onto the current screen
• Blinking the device's LED

Supported platforms

• Android 4.4+
• iOS 10+
• Windows 10

Important Notice

Please make sure that you always read the tagged README for the version you're using.

See the 0.8 branch if you cannot upgrade. Further development for v0.9-beta will happen here. The 0.9-dev and ios10 branches are obsolate and will be removed soon.

Known issues

• Support for Android Oreo is limited yet.
• v0.9 and v0.8 aren't compatible with each other (Wont fix)

Please report bugs or missing features!

Basics

The plugin creates the object cordova.plugins.notification.local and is accessible after deviceready has been fired.

cordova.plugins.notification.local.schedule({
    title: 'My first notification',
    text: 'Thats pretty easy...',
    foreground: true
});

The plugin allows to schedule multiple notifications at once.

cordova.plugins.notification.local.schedule([
    { id: 1, title: 'My first notification' },
    { id: 2, title: 'My first notification' }
]);

Properties

A notification does have a set of configurable properties. Not all of them are supported across all platforms.

For their default values see:

cordova.plugins.notification.local.getDefaults();

To change some default values:

cordova.plugins.notification.local.setDefaults({
    led: { color: '#FF00FF', on: 500, off: 500 },
    vibrate: false
});

Actions

The plugin knows two types of actions: button and input.

cordova.plugins.notification.local.schedule({
    title: 'The big survey',
    text: 'Are you a fan of RB Leipzig?',
    attachments: ['file://img/rb-leipzig.jpg'],
    actions: [
        { id: 'yes', title: 'Yes' },
        { id: 'no',  title: 'No' }
    ]
});

Input

cordova.plugins.notification.local.schedule({
    title: 'Justin Rhyss',
    text: 'Do you want to go see a movie tonight?',
    actions: [{
        id: 'reply',
        type: 'input',
        title: 'Reply',
        emptyText: 'Type message',
    }, ... ]
});

It is recommended to pre-define action groups rather then specifying them with each new notification of the same type.

cordova.plugins.notification.local.addActions('yes-no', [
    { id: 'yes', title: 'Yes' },
    { id: 'no',  title: 'No'  }
]);

Once you have defined an action group, you can reference it when scheduling notifications:

cordova.plugins.notification.local.schedule({
    title: 'Justin Rhyss',
    text: 'Do you want to go see a movie tonight?',
    actions: 'yes-no'
});

Properties

Actions do have a set of configurable properties. Not all of them are supported across all platforms.

Triggers

Notifications may trigger immediately or depend on calendar or location.

To trigger at a fix date:

cordova.plugins.notification.local.schedule({
    title: 'Design team meeting',
    text: '3:00 - 4:00 PM',
    trigger: { at: new Date(2017, 10, 27, 15) }
});

Or relative from now:

cordova.plugins.notification.local.schedule({
    title: 'Design team meeting',
    trigger: { in: 1, unit: 'hour' }
});

Repeating

Repeat relative from now:

cordova.plugins.notification.local.schedule({
    title: 'Design team meeting',
    trigger: { every: 'day', count: 5 }
});

Or trigger every time the date matches:

cordova.plugins.notification.local.schedule({
    title: 'Happy Birthday!!!',
    trigger: { every: { month: 10, day: 27, hour: 9, minute: 0 } }
});

Location based

To trigger when the user enters a region:

cordova.plugins.notification.local.schedule({
    title: 'Welcome to our office',
    trigger: {
        type: 'location',
        center: [x, y],
        radius: 15,
        notifyOnEntry: true
    }
});

Properties

The properties depend on the trigger type. Not all of them are supported across all platforms.

Progress

Notifications can include an animated progress indicator that shows users the status of an ongoing operation.

cordova.plugins.notification.local.schedule({
    title: 'Sync in progress',
    text: 'Copied 2 of 10 files',
    progressBar: { value: 20 }
});

Patterns

Split the text by line breaks if the message comes from a single person and just too long to show in a single line.

cordova.plugins.notification.local.schedule({
    title: 'The Big Meeting',
    text: '4:15 - 5:15 PM\nBig Conference Room',
    smallIcon: 'res://calendar',
    icon: 'https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcTzfXKe6Yfjr6rCtR6cMPJB8CqMAYWECDtDqH-eMnerHHuXv9egrw'
});

Summarizing

Instead of displaying multiple notifications, you can create one notification that summarizes them all.

cordova.plugins.notification.local.schedule({
    id: 15,
    title: 'Chat with Irish',
    icon: 'http://climberindonesia.com/assets/icon/ionicons-2.0.1/png/512/android-chat.png',
    text: [
        { message: 'I miss you' },
        { person: 'Irish', message: 'I miss you more!' },
        { message: 'I always miss you more by 10%' }
    ]
});

To add a new message to the existing chat:

cordova.plugins.notification.local.update({
    id: 15,
    text: [{ person: 'Irish', message: 'Bye bye' }]
});

Grouping

Your app can present multiple notifications as a single group:

• A parent notification displays a summary of its child notifications.
• The child notifications are presented without duplicate header information.

cordova.plugins.notification.local.schedule([
    { id: 0, title: 'Design team meeting', ... },
    { id: 1, summary: 'me@gmail.com', group: 'email', groupSummary: true },
    { id: 2, title: 'Please take all my money', ... group: 'email' },
    { id: 3, title: 'A question regarding this plugin', ... group: 'email' },
    { id: 4, title: 'Wellcome back home', ... group: 'email' }
]);

Permissions

Each platform may require the user to grant permissions first before the app is allowed to schedule notifications.

cordova.plugins.notification.local.hasPermission(function (granted) { ... });

If requesting via plug-in, a system dialog does pop up for the first time. Later its only possible to tweak the settings through the system settings.

cordova.plugins.notification.local.requestPermission(function (granted) { ... });

Checking the permissions is done automatically, however it's possible to skip that.

cordova.plugins.notification.local.schedule(toast, callback, scope, { skipPermission: true });

Events

The following events are supported: add, trigger, click, clear, cancel, update, clearall and cancelall.

cordova.plugins.notification.local.on(event, callback, scope);

To unsubscribe from events:

cordova.plugins.notification.local.un(event, callback, scope);

Note: You have to provide the exact same callback to cordova.plugins.notification.local.un as you provided to cordova.plugins.notification.local.on to make unsubscribing work. Hence you should define your callback as a separate function, not inline. If you want to use this inside of your callback, you also have to provide this as scope to cordova.plugins.notification.local.on.

Custom

The plugin also fires events specified by actions.

cordova.plugins.notification.local.schedule({
    title: 'Do you want to go see a movie tonight?',
    actions: [{ id: 'yes', title: 'Yes' }]
});

The name of the event is the id of the action.

cordova.plugins.notification.local.on('yes', function (notification, eopts) { ... });

Fire manually

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

cordova.plugins.notification.local.core.fireEvent(event, args);

Launch Details

Check the launchDetails to find out if the app was launched by clicking on a notification.

document.addEventListener('deviceready', function () {
    console.log(cordova.plugins.notification.local.launchDetails);
}, false);

It might be possible that the underlying framework like Ionic is not compatible with the launch process defined by cordova. With the result that the plugin fires the click event on app start before the app is able to listen for the events.

Therefore its possible to fire the queued events manually by defining a global variable.

window.skipLocalNotificationReady = true

Once the app and Ionic is ready, you can fire the queued events manually.

cordova.plugins.notification.local.fireQueuedEvents();

Methods

All methods work asynchronous and accept callback methods. See the sample app for how to use them.

Installation

The plugin can be installed via Cordova-CLI and is publicly available on NPM.

Execute from the projects root folder:

$ cordova plugin add cordova-plugin-local-notification

Or install a specific version:

$ cordova plugin add cordova-plugin-local-notification@VERSION

Or install the latest head version:

$ cordova plugin add https://github.com/katzer/cordova-plugin-local-notifications.git

Or install from local source:

$ cordova plugin add <path> --nofetch --nosave --link

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

License

This software is released under the Apache 2.0 License.

Made with :yum: from Leipzig

© 2013 appPlant GmbH

ChangeLog

Please also read the Upgrade Guide for more information.

Version 0.8.5 (22.05.2017)

• iOS 10

Version 0.8.4 (04.01.2016)

• Bug fixes
  • SyntaxError: missing ) after argument list

Version 0.8.3 (03.01.2016)

• Platform enhancements
  • Support for the Crosswalk Engine
  • Support for cordova-ios@4 and the WKWebView Engine
  • Support for cordova-windows@4 and Windows 10 without using hooks
• Enhancements
  • New color attribute for Android (Thanks to @Eusebius1920)
  • New quarter intervall for iOS & Android
  • smallIcon is optional (Android)
  • update checks for permission like schedule
  • Decreased time-frame for trigger event (iOS)
  • Force every: to be a string on iOS
• Bug fixes
  • Fixed #634 option to skip permission check
  • Fixed #588 crash when basename & extension can't be extracted (Android)
  • Fixed #732 loop between update and trigger (Android)
  • Fixed #710 crash due to >500 notifications (Android)
  • Fixed #682 crash while resuming app from notification (Android 6)
  • Fixed #612 cannot update icon or sound (Android)
  • Fixed crashing get(ID) if notification doesn't exist
  • Fixed #569 getScheduled returns two items per notification
  • Fixed #700 notifications appears on bootup

Version 0.8.2 (08.11.2015)

• Submitted to npm
• Initial support for the windows platform
• Re-add autoCancel option on Android
• Warn about unknown properties
• Fix crash on iOS 9
• Fixed webView-Problems with cordova-android 4.0
• Fix get* with single id
• Fix issue when passing data in milliseconds
• Update device plugin id
• Several other fixes

Version 0.8.1 (08.03.2015)

• Fix incompatibility with cordova version 3.5-3.0
• Fire clear instead of cancel event when clicked on repeating notifications
• Do not fire clear or cancel event when clicked on persistent notifications

Version 0.8.0 (05.03.2015)

• Support for iOS 8, Android 2 (SDK >= 7) and Android 5
  • Windows Phone 8.1 will be added soon
• New interfaces to ask for / register permissions required to schedule local notifications
  • hasPermission() and registerPermission()
  • schedule() will register the permission automatically and schedule the notification if granted.
• New interface to update already scheduled|triggered local notifications
  • update()
• New interfaces to clear the notification center
  • clear() and clearAll()
• New interfaces to query for local notifications, their properties, their IDs and their existence depend on their state
  • isPresent(), isScheduled(), isTriggered()
  • getIds(), getAllIds(), getScheduledIds(), getTriggeredIds()
  • get(), getAll(), getScheduled(), getTriggered()
• Schedule multiple local notifications at once
  • schedule( [{...},{...}] )
• Update multiple local notifications at once
  • update( [{...},{...}] )
• Clear multiple local notifications at once
  • clear( [1, 2] )
• Cancel multiple local notifications at once
  • cancel( [1, 2] )
• New URI format to specify sound and image resources
  • http(s): for remote resources (Android)
  • file: for local resources relative to the www folder
  • res: for native resources
• New events
  • schedule, update, clear, clearall and cancelall
• Enhanced event informations
  • Listener will get called with the local notification object instead of only the ID
• Multiple listener for one event
  • on(event, callback, scope)
• Unregister event listener
  • un(event, callback)
• New Android specific properties
  • led properties
  • sound and image accepts remote resources
• Callback function and scope for all interface methods
  • schedule( notification, callback, scope )
• Renamed add() to schedule()
• autoCancel property has been removed
  • Use ongoing: true for persistent local notifications on Android
• Renamed repeat intervals
  • second, minute, hour, day, week, month and year
• Renamed some local notification properties
  • date, json, message and repeat
  • Scheduling local notifications with the deprecated properties is still possible
• Kitchen Sink sample app
• Wiki