Using Local Notifications in Titanium

A recent Titanium project called for the use of Local Notifications.  I wanted to share my experience implementing this feature in hopes it will help others.

Tips / Questions

1. Tips on using Ti.App.iOS.scheduleLocalNotification

The current (version 2.0.2 ) implementation of the Ti.App.scheduleLocalNotification API requires that you call this method as part of a background service.  Keep in mind, this might change in future versions so please test your scenario on the current version of the framework.

Most problems with scheduling local notifications can be solved by moving your scheduling actions to a background service.  The below shows how the KitchenSink sample app performs this task.

First we need to register the background service in app.js. This will create the service once the app is based into the background.

    // register a background service. this JS will run when the app is backgrounded
    var service = Ti.App.iOS.registerBackgroundService({url:'bg.js'});

Second we create the notification in the bg.js

  var notification = 	Ti.App.iOS.scheduleLocalNotification({
	alertBody:"Kitchen Sink was put in background",
	alertAction:"Re-Launch!",
	userInfo:{"hello":"world"},
	sound:"pop.caf",
	date:new Date(new Date().getTime() + 3000) // 3 seconds after backgrounding
  });

Please visit this great QA Forum thread to learn more about different strategies to implement Ti.App.scheduleLocalNotification.

2. How do I cancel an individual notification?

It is my understanding there is currently two ways to do this:

• You can call cancel on the notification after you create a notification.  See below for an example show how to implement this approach as demonstrated in the KitchenSink sample app.

Notification example from bg.js

  var notification = 	Ti.App.iOS.scheduleLocalNotification({
	alertBody:"Kitchen Sink was put in background",
	alertAction:"Re-Launch!",
	userInfo:{"hello":"world"},
	sound:"pop.caf",
	date:new Date(new Date().getTime() + 3000) // 3 seconds after backgrounding
  });

  // we cancel our notification if we don't want it to continue
  notification.cancel();

• I believe you can use Ti.App.iOS.cancelLocalNotification to cancel a notification using a convention.  If when you created your notification you set the userInfo.id property to a unique integer value you can then pass this integer into the Ti.App.iOS.cancelLocalNotification method to cancel your notification.  This approach seems to work under some use cases but not others.  I would recommend testing on device to make sure it fits your app’s workflow.

Modify the bg.js example to add id to the userInfo object.

  //Create the notification
  var notification = 	Ti.App.iOS.scheduleLocalNotification({
	alertBody:"Kitchen Sink was put in background",
	alertAction:"Re-Launch!",
	userInfo:{"id":4, "hello":"world"},
	sound:"pop.caf",
	date:new Date(new Date().getTime() + 3000) // 3 seconds after backgrounding
  });

  //Cancel the notification using the id passed in as part of the userInfo object
  Ti.App.iOS.cancelLocalNotification(4);

3. How do I cancel all of my my Scheduled Notifications?

To cancel all of your notification you simply need to call the Ti.App.iOS.cancelAllLocalNotifications() method.  This will cancel all scheduled notifications linked to your app.

    // Cancel all notifications linked to your app
    Ti.App.iOS.cancelAllLocalNotifications();

4. How do I list my Scheduled Notifications?

Currently Titanium does not support querying scheduled notifications.  I discuss this more in how I implemented by solution below.

My implementation

Titanium is open source and extendable, making it easy to understand the platform’s current implementation and quickly add functionality.  For this project I needed to implement a custom workflow around local notifications that allowed users to schedule and managed their own notifications through a “dashboard”.

To assist with that I created a custom module that allows you to extend or replace the extending Titanium creation and cancellation methods.

1. ScheduleLocalNotification – Same as the native Titanium but without the return object and you are able to call without a background service.
2. activeScheduledNotifications  – Provides a callback with a list of your scheduled local notifications.
3. returnScheduledNotifications – Provides the same collection of scheduled local notifications as the activeScheduledNotifications but directly without the callback.
4. cancelLocalNotification – Takes an id and loops through canceling any scheduled local notification with a userInfo.id property that matches. A value is returned with the number of notifications that were scheduled.
5. cancelAllLocalNotifications – Works the exact same way as the native method.

If you are interested in learning more about the benCoding.localNotify module please visit the project on Github here.