NativeScript Local Notifications Plugin

The Local Notifications plugin allows your app to show notifications when the app is not running. Just like remote push notifications, but a few orders of magnitude easier to set up.

Installation

From the command prompt go to your app's root folder and execute:

tns plugin add nativescript-local-notifications

TypeScript support

And do yourself a favor by adding TypeScript support to your nativeScript app:

tns install typescript

Now you can import the plugin as an object into your .ts file as follows:

import * as LocalNotifications from "nativescript-local-notifications";

// then use it as:
LocalNotifications.hasPermission()

Demo app (XML)

If you want a quickstart, clone our demo app.

Demo app (Angular)

This plugin is part of the plugin showcase app I built using Angular.

schedule

On iOS you need to ask permission to schedule a notification. You can have the schedule funtion do that for you automatically (the notification will be scheduled in case the user granted permission), or you can manually invoke requestPermission if that's your thing.

You can pass several options to this function, everything is optional:

option	description
id	A number so you can easily distinguish your notifications. Default 0.
title	The title which is shown in the statusbar. Default empty.
body	The text below the title. Default empty.
groupedMessages	An array of atmost 5 messages that would be displayed using android's notification inboxStyle. Note: The array would be trimed from the top if the messages exceed five. Default not set
groupSummary	An inboxStyle notification summary. Default empty
ticker	On Android you can show a different text in the statusbar, instead of the body. Default not set, so body is used.
at	A JavaScript Date object indicating when the notification should be shown. Default 'now'.
badge	On iOS (and some Android devices) you see a number on top of the app icon. On most Android devices you'll see this number in the notification center. Default not set (0).
sound	Notification sound. For custom notification sound (iOS only), copy the file to App_Resources/iOS. Set this to "default" (or do not set at all) in order to use default OS sound. Set this to null to suppress sound.
interval	Set to one of second minute hour day week month quarter year if you want a recurring notification.
smallIcon	On Android you can set a custom icon in the system tray. Pass in 'res://filename' (without the extension) which lives in App_Resouces/Android/drawable folders. If not passed, we look for a file named 'ic_stat_notify.png' in the App_Resources/Android/drawable folders. Default: the app icon.
largeIcon	Same as smallIcon, but this one is shown when you expand the notification center. The optional file we look for is not 'ic_stat_notify.png' but 'ic_notify.png'.
ongoing	Default is (false). Set whether this is an ongoing notification. Ongoing notifications cannot be dismissed by the user, so your application must take care of canceling them.(Android Only)
progress	Default is (0). Set the progress when this is "ongoing" notification.(Android Only)

Note that after a reboot the smallIcon and largeIcon are not restored but fall back to the default (app icon). This is a known issue and can be fixed in a future version.

  LocalNotifications.schedule([{
    id: 1,
    title: 'The title',
    body: 'Recurs every minute until cancelled',
    ticker: 'The ticker',
    badge: 1,
    groupedMessages:["The first", "Second", "Keep going", "one more..", "OK Stop"], //android only
    groupSummary:"Summary of the grouped messages above", //android only
    ongoing: true, // makes the notification ongoing (Android only)
    progress:10, // sets the progress of ongoing notification (Android only)
    smallIcon: 'res://heart',
    interval: 'minute',
    sound: "customsound-ios.wav", // falls back to the default sound on Android
    at: new Date(new Date().getTime() + (10 * 1000)) // 10 seconds from now
  }]).then(
      function(builder) {
        console.log("Notification scheduled",builder);
      },
      function(error) {
        console.log("scheduling error: " + error);
      }
  )

Notification icons

Background information: Local notifications may fail silently if you don't provide the notification icons in the correct dimensions. They may do work perfectly fine on one device but fail on the other. That's because android might fallback to your xxxhdpi launcher icon which is too big. This type of error is noticeable in logcat: !!! FAILED BINDER TRANSACTION !!! (parcel size = 1435376)

Spec for ic_stat_notify.png (smallIcon)

Android API Guides → Status Bar Icons

Spec for ic_notify.png (largeIcon)

Unfortunately it seems like there's no official guide for these. Anyways there's a dimen that's telling us the dp size which we can translate to the following spec:

Density qualifier	px	dpi
ldpi	48 x 48	120
mdpi	64 x 64	160
hdpi	96 x 96	240
xhdpi	128 x 128	320
xxhdpi	192 x 192	480

Don't include xxxhdpi

xxxhdpi: Extra-extra-extra-high-density uses (launcher icon only, see the note in Supporting Multiple Screens); approximately 640dpi. Added in API Level 18
Source: Density Qualifier Docs

###updateProgress(Android only)

Update progress of ongoing notification. if progress value is greater than or equal to 100 then notification will be finished automatically and onGoing property for notification will be set to false.

Use this function to have a callback invoked when a notification is updated to its new progress value. Note that it is android only. for ios it will not work.

  LocalNotifications.addOnMessageReceivedCallback(builder,50,"uploading file").then(
      function() {
        console.log("notification updated");
      }
  )

addOnMessageReceivedCallback

Tapping a notification in the notification center will launch your app. But what if you scheduled two notifications and you want to know which one the user tapped?

Use this function to have a callback invoked when a notification was used to launch your app. Note that on iOS it will even be triggered when your app is in the foreground and a notification is received.

  LocalNotifications.addOnMessageReceivedCallback(
      function (notification) {
        console.log("ID: " + notification.id);
        console.log("Title: " + notification.title);
        console.log("Body: " + notification.body);
      }
  ).then(
      function() {
        console.log("Listener added");
      }
  )

getScheduledIds

If you want to know the ID's of all notifications which have been scheduled, do this:

Note that all functions have an error handler as well (see schedule), but to keep things readable we won't repeat ourselves.

  LocalNotifications.getScheduledIds().then(
      function(ids) {
        console.log("ID's: " + ids);
      }
  )

cancel

If you want to cancel a previously scheduled notification (and you know its ID), you can cancel it:

  LocalNotifications.cancel(5 /* the ID */).then(
      function(foundAndCanceled) {
          if (foundAndCanceled) {
            console.log("OK, it's gone!");
          } else {
            console.log("No ID 5 was scheduled");
          }
      }
  )

cancelAll

If you just want to cancel all previously scheduled notifications, do this:

  LocalNotifications.cancelAll();

requestPermission

On Android you don't need permission, but on iOS you do. Android will simply return true.

If the requestPermission or schedule function previously ran the user has already been prompted to grant permission. If the user granted permission this function returns true, but if he denied permission this function will return false, since an iOS can only request permission once. In which case the user needs to go to the iOS settings app and manually enable permissions for your app.

  LocalNotifications.requestPermission().then(
      function(granted) {
        console.log("Permission granted? " + granted);
      }
  )

hasPermission

On Android you don't need permission, but on iOS you do. Android will simply return true.

If the requestPermission or schedule functions previously ran you may want to check whether or not the user granted permission:

  LocalNotifications.hasPermission().then(
      function(granted) {
        console.log("Permission granted? " + granted);
      }
  )

Help, my Android app is restarted

When your app is launched from a notification you may notice the app is not continuing from when you put it in the background. To fix that, open app/App_Resources/AndroidManifest.xml and change the launchMode of the NativeScript activity. For instance:

<activity android:launchMode="singleTop" />