Skip to content

Commit af04a0b

Browse files
EddyVerbruggenEddyVerbruggen
committed
Doc
1 parent a14e53d commit af04a0b

File tree

3 files changed

+113
-95
lines changed

3 files changed

+113
-95
lines changed

‎README.md

Lines changed: 109 additions & 91 deletions
Original file line numberDiff line numberDiff line change
@@ -1,125 +1,143 @@
11
# NativeScript Local Notifications Plugin
22

3-
Don't use yet, this is actively being worked on..
4-
5-
6-
7-
8-
9-
10-
11-
12-
13-
14-
15-
16-
17-
18-
19-
20-
21-
22-
23-
24-
25-
26-
27-
28-
29-
30-
31-
32-
3+
The Local Notifications plugin allows your app to show notifications when the app is not running.
4+
Just like remote push notifications, but a few orders of magnitude easier to set up.
335

6+
## Installation
7+
From the command prompt go to your app's root folder and execute:
8+
```
9+
tns plugin add nativescript-local-notifications
10+
```
3411

12+
## Usage
3513

14+
If you want a quickstart, [clone our demo app](https://github.com/EddyVerbruggen/nativescript-local-notifications-demo).
3615

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

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

23+
|option|description|
24+
|------|-----------|
25+
|`id` |A number so you can easilty distinguish your notifications. Default 0.|
26+
|`title` |The title which is shown in the statusbar. Default empty.|
27+
|`body` |The text below the title. Default empty.|
28+
|`ticker` |On Android you can show a different text in the statusbar, instead of the `body`. Default not set, so `body` is used.|
29+
|`at` |A JavaScript Date object indicating when the notification should be shown. Default 'now'.|
30+
|`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).|
31+
|`sound` |Currently this is only used on Android where you can set this to `null` to suppress the sound. Default 'the default notification sound'.|
3932

33+
```js
34+
LocalNotifications.schedule([{
35+
id: 1,
36+
title: 'The title',
37+
body: 'The body',
38+
ticker: 'The ticker',
39+
badge: 1,
40+
sound: null, // suppress sound on Android
41+
at: new Date(new Date().getTime() + (10 * 1000)) // 10 seconds from now
42+
}]).then(
43+
function() {
44+
console.log("Notification scheduled");
45+
},
46+
function(error) {
47+
console.log("scheduling error: " + error);
48+
}
49+
)
50+
```
4051

52+
### addOnMessageReceivedCallback
53+
Tapping a notification in the notification center will launch your app.
54+
But what if you scheduled two notifications and you want to know which one the user tapped?
4155

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

59+
```js
60+
LocalNotifications.addOnMessageReceivedCallback(
61+
function (notification) {
62+
console.log("ID: " + notification.id);
63+
console.log("Title: " + notification.title);
64+
console.log("Body: " + notification.body);
65+
}
66+
).then(
67+
function() {
68+
console.log("Listener added");
69+
}
70+
)
71+
```
4372

73+
### getScheduledIds
74+
If you want to know the ID's of all notifications which have been scheduled, do this:
4475

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

78+
```js
79+
LocalNotifications.getScheduledIds().then(
80+
function(ids) {
81+
console.log("ID's: " + ids);
82+
}
83+
)
84+
```
4685

86+
### cancel
87+
If you want to cancel a previously scheduled notification (and you know its ID), you can cancel it:
4788

89+
```js
90+
LocalNotifications.cancel(5 /* the ID */).then(
91+
function(foundAndCanceled) {
92+
if (foundAndCanceled) {
93+
console.log("OK, it's gone!");
94+
} else {
95+
console.log("No ID 5 was scheduled");
96+
}
97+
}
98+
)
99+
```
48100

101+
### cancelAll
102+
If you just want to cancel all previously scheduled notifications, do this:
49103

50-
## Installation
51-
From the command prompt go to your app's root folder and execute:
52-
```
53-
tns plugin add nativescript-admob
104+
```js
105+
LocalNotifications.cancelAll();
54106
```
55107

56-
## Usage
57-
58-
If you want a quickstart, [clone our demo app](https://github.com/EddyVerbruggen/nativescript-admob-demo).
108+
### requestPermission
109+
On Android you don't need permission, but on iOS you do. Android will simply return true.
59110

60-
Here are the supported functions:
111+
If the `requestPermission` or `schedule` function previously ran the user has already been prompted to grant permission.
112+
If the user granted permission this function returns `true`, but if he denied permission this function will return `false`,
113+
since an iOS can only request permission once. In which case the user needs to go to the iOS settings app and manually
114+
enable permissions for your app.
61115

62-
### function: createBanner
63116
```js
64-
var admob = require("nativescript-admob");
65-
66-
admob.createBanner({
67-
// if this 'view' property is not set, the banner is overlayed on the current top most view
68-
// view: ..,
69-
testing: true, // set to false to get actual banners
70-
size: size, // anything in admob.AD_SIZE, like admob.AD_SIZE.SMART_BANNER
71-
iosBannerId: "ca-app-pub-XXXXXX/YYYYYY", // add your own
72-
androidBannerId: "ca-app-pub-AAAAAAAA/BBBBBBB", // add your own
73-
// Android automatically adds the connected device as test device with testing:true, iOS does not
74-
iosTestDeviceIds: ["yourTestDeviceUDIDs", "canBeAddedHere"],
75-
margins: {
76-
// if both are set, top wins
77-
//top: 10
78-
bottom: 50
117+
LocalNotifications.requestPermission().then(
118+
function(granted) {
119+
console.log("Permission granted? " + granted);
79120
}
80-
}).then(
81-
function() {
82-
console.log("admob createBanner done");
83-
},
84-
function(error) {
85-
console.log("admob createBanner error: " + error);
86-
}
87121
)
88122
```
89123

90-
### function: hideBanner
91-
NOTE: If you want to show a different banner than the one showing you don't need to call the `hide` function
92-
since `show` will do that for you to prevent your app from crashing.
124+
### hasPermission
125+
On Android you don't need permission, but on iOS you do. Android will simply return true.
126+
127+
If the `requestPermission` or `schedule` functions previously ran you may want to check whether or not the user granted permission:
93128

94129
```js
95-
// the .then(.. bit is optional btw
96-
admob.hideBanner().then(
97-
function() {
98-
console.log("admob hideBanner done");
99-
},
100-
function(error) {
101-
console.log("admob hideBanner error: " + error);
102-
}
130+
LocalNotifications.hasPermission().then(
131+
function(granted) {
132+
console.log("Permission granted? " + granted);
133+
}
103134
)
104135
```
105136

106-
### function: createInterstitial
107-
To show a fullscreen banner you can use this function. Note that Interstitial banners need to be loaded before
108-
they can be shown, but don't worry: this plugin will manage that transparently for you.
137+
## Future work
138+
Let us know what you need by opening a Github issue.
109139

110-
```js
111-
admob.createInterstitial({
112-
testing: true,
113-
iosInterstitialId: "ca-app-pub-XXXXXX/YYYYY2", // add your own
114-
androidInterstitialId: "ca-app-pub-AAAAAAAA/BBBBBB2", // add your own
115-
// Android automatically adds the connected device as test device with testing:true, iOS does not
116-
iosTestDeviceIds: ["ce97330130c9047ce0d4430d37d713b1"]
117-
}).then(
118-
function() {
119-
console.log("admob createInterstitial done");
120-
},
121-
function(error) {
122-
console.log("admob createInterstitial error: " + error);
123-
}
124-
)
125-
```
140+
We're thinking about adding support for things like:
141+
- Scheduling repeating notifications (daily, weekly, etc)
142+
- Custom Notification sounds
143+
- Interactive Notifications on iOS

‎local-notifications-common.js

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,9 @@ LocalNotifications.defaults = {
44
id: 0,
55
title: '',
66
body: '',
7-
ongoing: false,
8-
autoclear: true, // TODO on iOS this doesn't yet clear the badge.. needs to be set to '0' somewhere.. I'm afraid it needs to be in native code
97
badge: 0
8+
//ongoing: false
9+
//autoclear: true
1010
};
1111

1212
LocalNotifications.merge = function merge(obj1, obj2) { // Our merge function

‎package.json

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,8 @@
1818
},
1919
"keywords": [
2020
"NativeScript",
21-
"Notifications",
22-
"Local Notifications"
21+
"Notification",
22+
"Local Notification"
2323
],
2424
"author": "Telerik / Eddy Verbruggen <eddyverbruggen@gmail.com>",
2525
"license": {

0 commit comments

Comments
 (0)