NativeScript Notifications Plugin

This is a fork of the Nativescript Local Notifications Plugin. The eventual goal of this project will be to create a comprehensive plugin for managing local and push notifications, without the need for two distinct packages and hacking the shared delegate for ios.

In it's current state this plugin allows your app to show notifications from within the app.

Installation

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

NativeScript 7+:

ns plugin add @badideas/nativescript-notifications

NativeScript prior to 7:

tns plugin add [email protected]

Setup (since plugin version 3.0.0)

Add this so for iOS 10+ we can do some wiring (set the iOS UNUserNotificationCenter.delegate, to be precise). Not needed if your app loads the plugin on startup anyway.

You'll know you need this if on iOS 10+ notifications are not received by your app or addOnMessageReceivedCallback is not invoked... better safe than sorry, though!

// either
import { LocalNotifications } from '@badideas/nativescript-notifications';
// or (if that doesn't work for you)
import * as LocalNotifications from '@badideas/nativescript-notifications';

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

NativeScript-Angular

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

There's also a simple Angular demo in this repo:

NativeScript-Vue

There is a Vue demo:

Plugin API

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:

NotificationAction

LocalNotifications.schedule([
	{
		id: 1, // generated id if not set
		title: 'The title',
		body: 'Recurs every minute until cancelled',
		ticker: 'The ticker',
		color: new Color('red'),
		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)
		icon: 'res://heart',
		image: 'https://cdn-images-1.medium.com/max/1200/1*c3cQvYJrVezv_Az0CoDcbA.jpeg',
		thumbnail: true,
		interval: 'minute',
		channel: 'My Channel', // default: 'Channel'
		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(
	(scheduledIds) => {
		console.log('Notification id(s) scheduled: ' + JSON.stringify(scheduledIds));
	},
	(error) => {
		console.log('scheduling error: ' + error);
	}
);

Notification icons (Android)

These options default to res://ic_stat_notify and res://ic_stat_notify_silhouette respectively, or the app icon if not present.

silhouetteIcon should be an alpha-only image and will be used in Android >= Lollipop (21).

These are the official icon size guidelines, and here's a great guide on how to easily create these icons on Android.

Source: Density Qualifier Docs

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((notification) => {
	console.log('ID: ' + notification.id);
	console.log('Title: ' + notification.title);
	console.log('Body: ' + notification.body);
}).then(() => {
	console.log('Listener added');
});

getScheduledIds

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

LocalNotifications.getScheduledIds().then((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((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((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((granted) => {
	console.log('Permission granted? ' + granted);
});