@nativescript/local-notifications

Contents

• Intro
• Installation
• Use @nativescript/local-notifications
  • Import the plugin
  • Request for permissions
  • Schedule a notification
  • Get the IDs of all the scheduled notifications
  • Cancel a scheduled notification
  • Listen to a notification tap event
• API
  • schedule()
    • ScheduleOptions
      • NotificationAction
  • addOnMessageReceivedCallback()
  • addOnMessageClearedCallback()
  • getScheduledIds()
  • cancel()
  • cancelAll()
  • requestPermission()
  • hasPermission()

Intro

A plugin that 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

Install the plugin by running the following command in the root directory of your project.

npm install @nativescript/local-notifications

Use @nativescript/local-notifications

> Note: Advanced! If on iOS 10+ notifications are not being received or the method addOnMessageReceivedCallback is not invoked, you can try wiring to the UNUserNotificationCenterDelegate

Import the plugin

To import the plugin, use either of the 2 ways below.

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

Request for permissions

By default, the schedule method prompts the user for permission for you. For a manual permission request, use the requestPermission method:

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

Schedule a notification

To schedule a notification, call the schedule method and pass it an array of notification objects. For a list of members of a notification object, see ScheduleOptions.

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': 15 }, // repeat the notification every 15 minutes
		displayImmediately: true, // display the notification immediately when using a ScheduleIntervalObject
		channel: 'My Channel', // default: 'Channel'
		sound: isAndroid ? 'customsound' : 'customsound.wav',
		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);
	}
);

Get the IDs of all the scheduled notifications

To get the IDs of all the scheduled notifications, call the getScheduledIds method:

LocalNotifications.getScheduledIds().then((ids: number[]) => {
  console.log("ID's: " + ids)
})

Cancel a scheduled notification

To cancel a scheduled notification, use the cancel method.

LocalNotifications.cancel(5).then((foundAndCanceled: boolean) => {
	if (foundAndCanceled) {
		console.log("OK, it's gone!");
	} else {
		console.log('No ID 5 was scheduled');
	}
});

Listen to a notification tap event

Tapping a notification in the notification center will launch your app.

On iOS it can even be triggered when your app is in the foreground and a notification is received.

To handle a notification tap, call the addMessageReceivedCallback method and pass it a callback function. The callback receives a notification object of type ReceivedNotification.

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

API

schedule()

scheduledNotificationsIDs: Array = await LocalNotifications.schedule(scheduleOptions)

Schedules the specified scheduleOptions notification(s), if the user has granted the permission. If the user has not been prompted for permission, it prompts the user for permission and schedules the notification(s) if permission is granted. For a manual permission request, use the requestPermission method.

ScheduleOptions

NotificationAction

icon and silhouetteIcon Options (Android-only)

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

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()

LocalNotifications.addOnMessageReceivedCallback((notification: ReceivedNotification) => {
	//Handle the received notification
}).then(() => {
	console.log('Listener added');
});

Responds to a notification tap event.

ReceivedNotification

addOnMessageClearedCallback()

LocalNotifications.addOnMessageClearedCallback((notification: ReceivedNotification) => {
	//Handle the received notification
}).then(() => {
	console.log('Listener added');
});

Responds to a notification clear event. See ReceivedNotification for more info.

getScheduledIds()

LocalNotifications.getScheduledIds().then((ids: number[]) => {
	console.log("ID's: " + ids);
});

Returns the ids of all the scheduled notifications.

cancel()

LocalNotifications.cancel(id).then((foundAndCanceled: boolean) => {
	if (foundAndCanceled) {
		//
	} else {
		//
	}
});

Cancels the scheduled notification with the specified id.

cancelAll()

LocalNotifications.cancelAll();

Cancels all the scheduled notifications.

requestPermission()

LocalNotifications.requestPermission().then((granted) => {
	console.log('Permission granted? ' + granted);
});

Requests for the user's permissions for the app to send her notifications. You only need to call this method on iOS. If the permission has already been granted, it returns true. Otherwise, it returns false.

hasPermission()

LocalNotifications.hasPermission().then((granted) => {
	console.log('Permission granted? ' + granted);
});

Checks if the application has permission to notify the user.