Open Source & Free  

Local Notifications on iOS and Android

Local Notifications on iOS and Android

Header Image

We are happy to announce support for local notifications on iOS and Android. Local notifications are similar to push notifications, except that they are initiated locally by the app, rather than remotely. They are useful for communicating information to the user while the app is running in the background, since they manifest themselves as pop-up notifications on supported devices.

Sending Notifications

The process for sending a notification is:

  1. Create a LocalNotification object with the information you want to send in the notification.

  2. Pass the object to Display.scheduleLocalNotification().

Notifications can either be set up as one-time only or as repeating.

Example Sending Notification

LocalNotification n = new LocalNotification();
n.setAlertBody("It's time to take a break and look at me");
n.setAlertTitle("Break Time!");
    // alert sound file name must begin with notification_sound

        System.currentTimeMillis() + 10 * 1000, // fire date/time
        LocalNotification.REPEAT_MINUTE  // Whether to repeat and what frequency

The resulting notification will look like

f7200840 677e 11e5 8fd7 41eb027f8a6c

The above screenshot was taken on the iOS simulator.

Receiving Notifications

The API for receiving/handling local notifications is also similar to push. Your application’s main lifecycle class needs to implement the com.codename1.notifications.LocalNotificationCallback interface which includes a single method:

public void localNotificationReceived(String notificationId)

The notificationId parameter will match the id value of the notification as set using LocalNotification.setId().

Example Receiving Notification

public class BackgroundLocationDemo implements LocalNotificationCallback {

    public void init(Object context) {

    public void start() {


    public void stop() {

    public void destroy() {

    public void localNotificationReceived(String notificationId) {
        System.out.println("Received local notification "+notificationId);
localNotificationReceived() is only called when the user responds to the notification by tapping on the alert. If the user doesn’t opt to click on the notification, then this event handler will never be fired.

Cancelling Notifications

Repeating notifications will continue until they are canceled by the app. You can cancel a single notification by calling:


Where notificationId is the string id that was set for the notification using LocalNotification.setId().

Sample App

You can see a full sample that uses the new local notifications API here.


  • Carlos says:


    Is it possible to reset an scheduled notification? I’m thinking on something like “Hey, it’s been a while since you last visited us”. So if the user opens the app before the notification is triggered, the scheduled time gets back to zero. I haven’t checked the api so I don’t know if something like this is possible.

  • shannah78 says:

    Yes. You can cancel the existing notification, then schedule a new one. One strategy might be to cancel the notification in your start() method, the schedule it in your stop() method. Might be a good idea to additionally schedule the notification before the stop method (e.g. in the start method) so that the user will be triggered to allow notifications when the app opens.

    The key is that nothing bad happens if you cancel a notification id that doesn’t exist.

  • Nick Koirala says:

    What sort of limit is there for how far in advance a notification can be set? can it be days or months away?

  • ahmed says:

    hi. I am using intelliJ and updated the codename libs and found that the new notification folder is now part of the jar. However when implementing using the sample code and the sample application I do not get any notifications. I tried this on the simulator and also sent the build to the physical phone but same result, no notifications.

  • Shai Almog says:

    This will only work on devices. On which device type did you try?

  • ahmed says:

    iPhone 6 running iOS 9.

  • shannah78 says:

    I’m not aware of any limitation as to how far in advance the notification can be. On iOS you are limited to 64 notifications at a time. (recurring notifications are treated as a single notification).

  • shannah78 says:

    Notifications will only be shown when the app is not running, or in the background. If the app is in the foreground, the notification will not appear.

  • ahmed says:

    Yes of course. The app was in the background at the time the scheduled notification would have fired.

  • shannah78 says:

    Wow. Just looked at the source and it seems that the entire local notifications section had been commented out. This was caused by a sort of git race condition. I implemented it -> Shai commented it out because of a build error-> I fixed it and uncommented it -> tried to push but needed to first merge from origin master… so merged from master which re-added the comment outs .

    I have now uncommented it so it should be working next time Shai updates the server.


  • ahmed says:

    Thank you for the info and update. I assume the IntelliJ lib will also get updated with the next build. Will keep an eye open.

  • Keshav Rai says:

    Hey! Fellas 🙂 #iOs
    Can we set CUSTOM SOUNDS on Local Notifications? !?!
    Pls. Help …

  • Chen Fishbein says:

    From the code above :

  • Lukman Javalove Idealist Jaji says:

    One question…can we place a container with components in the notification…similar to what Uber and other apps have? I will like o have a few buttons in that area

  • Shai Almog says:

    Those aren’t containers as you can’t add arbitrary data there. Currently that isn’t supported as the behavior here differs too much between platforms but if there is demand for it we might address it thru common use cases.

  • madhu thestudent says:

    can we see the local notifications in simulator and how?

  • madhu thestudent says:

    does the codename one support notification builders and how?

  • Daniel Le Cardinal says:

    hi guys,
    can someone tell me if local notification can allow to trigger some part of my app when it is in background ? For instance, i want to count the number of push notification received which are in a pending state (even if i restart my phone)?

  • Shai Almog says:

    you can schedule a local notification to the background but it’s not exactly a background task. It’s more of a visual use case.

    Apps don’t really run in the background in iOS, they perform background use cases which is a pretty limited scope. I’m assuming you want to do background processing similar to Androids services which is something iOS just doesn’t allow.

  • Shai Almog says:

    Sorry I didn’t see that comment.

    We support local notifications which provide similar functionality see the discussion on this in the developer guide.

  • Chibuike Mba says:

    How can I reschedule my LocalNotification on device reboot?
    Android has this user permission <uses-permission android_name=”android.permission.RECEIVE_BOOT_COMPLETED”/>
    which invokes a BroadcastReceiver but I can’t figure out how to use it with my LocalNotification.

  • Chibuike Mba says:

    OK, will be expecting your reply.

  • Ch Hjelm says:

    I use localNotificationReceived for setting reminders and it works as expected when the app is active in the background.

    However, when the app is not running (eg killed manually), tapping the ios notification starts up the app and calls init() and start() as expected, but it doesn’t seem to get around to calling localNotificationReceived after that. How can I ensure the call to localNotificationReceived happens so the app takes the action the user expects?

Leave a Reply