**NOTE: This is totally outdated, but it'll work fine until Katzer releases 0.9 (where my updated changes have been merged). **
** Disclaimer: This was forked from willyboy's repo, which was forked from NorthMcCormick's, which of course was forked from Katzer's. **
You can scroll below or visit any of the repos linked above to see general usage docs, but here I'll show you how to add interactive notifications to your iOS or Android app.
##How to make your notifications interactive
First, some background. Actions are little buttons the user can slide to see on a notification, and tap to have something done in the background or foreground, depending on how it's configured. On iOS you can add up to four notification actions. When notifications are shown in banner form, only two will be shown, and all four can be shown in the alert form. Of course, you can have less than four or two, or none. My implementation is such that the actions will be shown in the order you've supplied them, so that only the first two will show in banner form (by default, the behavior is a little bit different, but this was the best way I could make the order of the actions predictable). On Android, you can have up to three actions, and the banner vs. alert differences don't apply.
In iOS, notification actions are associated with a category. This category has those actions attached to it, and is part of the notification payload. Both actions and categories are identified by an identifier string (shocking, I know). Android does not associate actions with a category, or even with their own identifier. But to make the action behavior consistent across both platforms, you will still need to use both action identifiers and a category for Android notifications. This also uses less memory on Android.
To add actions to a notification, you add them and a category when you schedule it. The actions will be an array (containing action objects) passed to the 'actions' property, and the category will be a string passed to the 'category' property. You can reuse actions, perhaps if you've defined them outside of your call to schedule a notification, and pick up particular ones from that definition in your call. However, after you've passed an action with a particular identifier, you can't modify it in later notifications. If two action objects have the same identifier, the first one passed will be used, and the next will turn into the first one in the native code. The same applies to categories. That will probably be the biggest 'gotcha' with my implementation, but I think it is perfectly reasonable behavior. So please be aware.
You can allow a user to send a text response through a notification (iOS only, would love to implement this for Android as well when it is available). All you need to do to allow for this is to add a 'behavior' property to your action object with the value 'textInput'. If it's not a reply-inline action, don't include this property, or provide any other value. Additionally, you can modify the text of the 'Send' button, by adding a 'textInputSendTitle' property, which the value of what you'd like the button to say. On Android, for these actions, I recommend handling them the way Gmail handles their 'Reply' notification action (
Each action must include six properties to work properly on both iOS and Android. There are also two, totally optional, properties to set up iOS inline reply actions. All of these properties are listed below.
- identifier: (iOS & Android) A string containing the identifier of your action (read above to learn more about how this will be used)
- title: (iOS & Android) A string that will be shown on the action button itself.
- icon: (Android) A string used to locate a resource asset to be shown on the action button itself. Don't include the file extension (but it should be .png). Whatever works for you for the smallIcon property on the notification itself will be what works here, so look into that for reference.
- activationMode: (iOS) A string equal to either 'background' or 'foreground'. This property determines whether your app will be brought to the foreground (and opened, if it isn't already) when the action is tapped (for 'foreground', obviously).
- destructive: (iOS) A boolean. If true, the action button will be shown with a red background, to signifiy that destructive changes will be made if clicked. It doesn't actually change how anything functions.
- authenticationRequired: (iOS) A boolean. If true, the user will be required to enter their passcode before the action is actually performed.
- behavior: (iOS, optional) A string that should equal 'textInput' if you would like the reply-inline functionality described above.
- textInputSendTitle: (iOS, optional) A string that will appear on the 'Send' button for reply-inline actions (instead of 'Send'). This is optional if your reply specifies the 'textInput' behavior, and totally unnecessary if not. Note: You won't find this property under this name in Apple's documentation; it's set a different way internally.
###Sample
var actions = [ {
identifier: 'SIGN_IN',
title: 'Yes',
icon: 'res://ic_signin',
activationMode: 'background',
destructive: false,
authenticationRequired: true
},
{
identifier: 'MORE_SIGNIN_OPTIONS',
title: 'More Options',
icon: 'res://ic_moreoptions',
activationMode: 'foreground',
destructive: false,
authenticationRequired: false
},
{
identifier: 'PROVIDE_INPUT',
title: 'Provide Input',
icon: 'ic_input',
activationMode: 'background',
destructive: false,
authenticationRequired: false,
behavior: 'textInput',
textInputSendTitle: 'Reply'
}];
cordova.plugins.notification.local.schedule({
id: 1,
title: "Production Jour fixe",
text: "Duration 1h",
at: monday_9_am,
actions: [actions[0], actions[1]],
category: 'SIGN_IN_TO_CLASS'
});Of course, above, you can include all of the normal properties passed when scheduling a notification. Just add actions and category to get interactivity.
##Handling actions
When a user taps a notification action, you obviously want to do something. So, to know which action they've tapped, you just need to capture the 'action' event. This will give you the notification, state, and data. The action identifier (and optional reply-inline response info text) are in the data variable, an object with 'identifier' and (optional) 'responseInfoText' propertie(s). You should know all of the action identifiers (after all, you passed them), and use conditions to determine what you'll for for each actions.
###Sample
cordova.plugins.notification.local.on('action', function (notification, state, data) {
var replyMessage;
if (data.identifier === 'PROVIDE_INPUT') {
replyMessage = data.responseInfoText;
alert(replyMessage);
} else if (data.identifier === 'SIGN_IN') {
alert('You have been signed in!');
} else if (data.identifier === 'MORE_SIGNIN_OPTIONS') {
alert('(Pretend there are more signin options here, please.)');
}
});Obviously, you can do something more interesting than adding alerts.
In the case that you've shared actions amongst different notifications, but want to perform something else depending on what actual notification it was tapped from, just use the notification variable to access the payload you passed in and determine which it is. You'll need to parse this too.
##For Ionic users
If you use ngCordova, you can add this snippet to the ngCordova.plugins.localNotification module under the event listener:
$window.cordova.plugins.notification.local.on('action', function (notification, state, data) {
$timeout(function () {
$rootScope.$broadcast('$cordovaLocalNotification:action', notification, state, data);
});
});Then in your app, you can capture the event like this:
$rootScope.$on('$cordovaLocalNotification:action', function(event, notification, state, data) {
// use conditionals to choose actions to take like above, blah blah
});The essential purpose of local notifications is to enable an application to inform its users that it has something for them — for example, a message or an upcoming appointment — when the application isn’t running in the foreground.
They are scheduled by an application and delivered on the same device.
Users see notifications in the following ways:
- Displaying an alert or banner
- Badging the app’s icon
- Playing a sound
Local notifications are ideally suited for applications with time-based behaviors, such as calendar and to-do list applications. Applications that run in the background for the limited period allowed by iOS might also find local notifications useful.
For example, applications that depend on servers for messages or data can poll their servers for incoming items while running in the background; if a message is ready to view or an update is ready to download, they can then present a local notification immediately to inform their users.
- Includes iOS 9 Support, moving away from depricated and buggy Objective-C Code
- Includes iOS 9 Support, moving away from depricated and buggy Objective-C Code. This is the only fix that will go into the current master branch.
The current 0.8 branch supports the following platforms:
- iOS (including iOS8)
- Android (SDK >=7)
- Windows 8.1 (added with v0.8.2)
- Windows Phone 8.1 (added with v0.8.2)
Find out more informations here in our wiki.
The plugin is installable from source and available on Cordova Plugin Registry and PhoneGap Build.
Find out more informations here in our wiki.
All wiki pages contain samples, but for a quick overview the sample section may be the fastest way.
Find out more informations here in our wiki.
The plugin supports scheduling local notifications in various ways with a single interface. It also allows you to update, clear or cancel them. There are different interfaces to query for local notifications and a complete set of events to hook into the life cycle of local notifications.
Find out more about how to schedule single, multiple, delayed or repeating local notifications here.
Informations about events like click or trigger can be found here.
To get a deep overview we recommend to read about all the topics in our wiki and try out the Kitchen Sink App
The plugin offers a kitchen sink sample app. Check out the cordova project and run the app directly from your command line or preferred IDE.
Find out more informations here in our wiki.
We are proud to announce our newest release version 0.8.x. Beside the hard work at the office and at the weekends it contains a lot of goodies, new features and easy to use APIs.
Find out more informations here in our wiki.
The sample demonstrates how to schedule a local notification which repeats every week. The listener will be called when the user has clicked on the local notification.
cordova.plugins.notification.local.schedule({
id: 1,
title: "Production Jour fixe",
text: "Duration 1h",
firstAt: monday_9_am,
every: "week",
sound: "file://sounds/reminder.mp3",
icon: "http://icons.com/?cal_id=1",
data: { meetingId:"123#fg8" }
});
cordova.plugins.notification.local.on("click", function (notification) {
joinMeeting(notification.data.meetingId);
});Find out more informations here in our wiki.
We appricate any feature proposal and support for their development. Please describe them here.
Find out more informations here in our wiki.
This software is released under the Apache 2.0 License.
© 2013-2015 appPlant UG, Inc. All rights reserved