nativescript-push-notifications
Advanced tools
Comparing version 1.0.0 to 1.1.0
@@ -0,1 +1,26 @@ | ||
// Android only | ||
export declare interface FcmNotificaion { | ||
getBody(): string; | ||
getBodyLocalizationArgs(): string[]; | ||
getBodyLocalizationKey(): string; | ||
getClickAction(): string; | ||
getColor(): string; | ||
getIcon(): string; | ||
getSound(): string; | ||
getTag(): string; | ||
getTitle(): string; | ||
getTitleLocalizationArgs(): string[]; | ||
getTitleLocalizationKey(): string; | ||
} | ||
export declare function register(options: { | ||
senderID: string; | ||
notificationCallbackAndroid?: (stringifiedData: String, fcmNotification: any) => void; | ||
}, successCallback: (fcmRegistrationToken: string) => void, errorCallback: (errorMessage: string) => void): void; | ||
export declare function unregister(onSuccessCallback: (successMessage: string) => void, onErrorCallback: (errorMessage: string) => void, options: { | ||
senderID: string; | ||
}): void; | ||
export declare function onMessageReceived(onSuccessCallback: (message: string, stringifiedData: string, fcmNotification: FcmNotificaion) => void): void; | ||
export declare function onTokenRefresh(onSuccessCallback: () => void): void; | ||
// iOS only | ||
export declare interface IosInteractiveNotificationAction { | ||
@@ -9,3 +34,2 @@ identifier: string; | ||
} | ||
export declare interface IosInteractiveNotificationCategory { | ||
@@ -16,3 +40,2 @@ identifier: string; | ||
} | ||
export declare interface IosRegistrationOptions { | ||
@@ -24,8 +47,7 @@ badge: boolean; | ||
interactiveSettings: { | ||
actions: IosInteractiveNotificationAction[], | ||
categories: IosInteractiveNotificationCategory[] | ||
actions: IosInteractiveNotificationAction[]; | ||
categories: IosInteractiveNotificationCategory[]; | ||
}; | ||
notificationCallbackIOS: (message: any) => void; | ||
} | ||
export declare interface NSError { | ||
@@ -36,30 +58,7 @@ code: number; | ||
} | ||
export declare function register(options: IosRegistrationOptions, successCallback: (token: string) => void, errorCallback: (error: NSError) => void): void; | ||
export declare function registerUserNotificationSettings(success: () => void, error: (error: NSError) => void): void; | ||
export declare function unregister(done: (context: any) => void): void; | ||
export declare interface FcmNotificaion { | ||
getBody(): string; | ||
getBodyLocalizationArgs(): string[]; | ||
getBodyLocalizationKey(): string; | ||
getClickAction(): string; | ||
getColor(): string; | ||
getIcon(): string; | ||
getSound(): string; | ||
getTag(): string; | ||
getTitle(): string; | ||
getTitleLocalizationArgs(): string[]; | ||
getTitleLocalizationKey(): string; | ||
} | ||
// Common | ||
export declare function register(options: IosRegistrationOptions, successCallback: (token: string) => void, errorCallback: (error: NSError) => void): void; | ||
export declare function register(options: { senderID: string }, successCallback: (fcmRegistrationToken: string) => void, errorCallback: (errorMessage: string) => void): void; | ||
export declare function unregister(successCallback: (successMessage: string) => void): void; // iOS | ||
export declare function unregister(successCallback: (successMessage: string) => void, errorCallback: (errorMessage: string) => void, options: { senderID: string }): void; | ||
export declare function areNotificationsEnabled(successCallback: (areEnabled: boolean) => void): void; | ||
// Android only | ||
export declare function onMessageReceived(callback: (stringifiedData: string, fcmNotification: FcmNotificaion) => void): void; | ||
export declare function onTokenRefresh(callback: () => void): void; | ||
// iOS only | ||
export declare function registerUserNotificationSettings(successCallback: () => void, errorCallback: (error: NSError) => void): void; | ||
export declare function areNotificationsEnabled(done: (areEnabled: Boolean) => void): void; |
{ | ||
"name": "nativescript-push-notifications", | ||
"version": "1.0.0", | ||
"version": "1.1.0", | ||
"description": "Receive push notifications in your NativeScript app on Android and iOS.", | ||
@@ -35,3 +35,2 @@ "main": "push-plugin", | ||
"tslint": "cd .. && tslint \"**/*.ts\" --config tslint.json --exclude \"**/node_modules/**\"", | ||
"plugin.link": "npm link && cd ../demo && npm link nativescript-push-notifications && cd ../src", | ||
"clean": "cd ../demo && rimraf hooks node_modules platforms && cd ../src && rimraf node_modules && npm run plugin.link", | ||
@@ -38,0 +37,0 @@ "ci.tslint": "npm i --ignore-scripts && tslint '**/*.ts' --config ../tslint.json --exclude '**/node_modules/**'", |
@@ -16,2 +16,3 @@ export interface FcmNotificaion { | ||
senderID: string; | ||
notificationCallbackAndroid?: (stringifiedData: String, fcmNotification: any) => void; | ||
}, successCallback: (fcmRegistrationToken: string) => void, errorCallback: (errorMessage: string) => void): void; | ||
@@ -18,0 +19,0 @@ export declare function unregister(onSuccessCallback: (successMessage: string) => void, onErrorCallback: (errorMessage: string) => void, options: { |
@@ -17,3 +17,8 @@ "use strict"; | ||
com.telerik.pushplugin.PushPlugin.register(app.android.context, options.senderID, new com.telerik.pushplugin.PushPluginListener({ | ||
success: successCallback, | ||
success: function (fcmRegistrationToken) { | ||
if (options && typeof options.notificationCallbackAndroid === 'function') { | ||
onMessageReceived(options.notificationCallbackAndroid); | ||
} | ||
successCallback(fcmRegistrationToken); | ||
}, | ||
error: errorCallback | ||
@@ -20,0 +25,0 @@ })); |
@@ -0,0 +0,0 @@ export interface IosInteractiveNotificationAction { |
@@ -0,0 +0,0 @@ "use strict"; |
611
README.md
# Push Plugin for NativeScript | ||
[![Build Status](https://travis-ci.org/NativeScript/push-plugin.svg?branch=master)](https://travis-ci.org/NativeScript/push-plugin) | ||
@@ -13,11 +14,10 @@ | ||
## Installation | ||
## Installation | ||
In the Command prompt / Terminal navigate to your application root folder and run: | ||
tns plugin add nativescript-push-notifications | ||
tns plugin add nativescript-push-notifications | ||
## Configuration | ||
## Configuration | ||
### Android | ||
@@ -28,30 +28,31 @@ | ||
- Edit the `package.json` file in the root of application, by changing the bundle identifier to match the Firebase's project package name. For example: | ||
```json | ||
"id": "org.nativescript.PushNotificationApp" | ||
``` | ||
"id": "org.NativeScript.PushNotificationApp" | ||
``` | ||
- Edit the `app/App_Resources/Android/app.gradle` file of your application, by changing the application ID to match the bundle identifier from the package.json. For example: | ||
``` | ||
android { | ||
... | ||
defaultConfig { | ||
applicationId = "org.NativeScript.PushNotificationApp" | ||
} | ||
... | ||
} | ||
``` | ||
```Groovy | ||
android { | ||
// ... | ||
defaultConfig { | ||
applicationId = "org.nativescript.PushNotificationApp" | ||
} | ||
// ... | ||
} | ||
``` | ||
- Go to the application folder and add the Android platform to the application | ||
```bash | ||
tns platform add android | ||
``` | ||
tns platform add android | ||
- Add the `google-settings.json` file with the FCM configuration to the `app/App_Resources/Android folder` in your app. If this file is not added, building the app for android will fail. | ||
The plugin will default to version 11.4.2 of the `firebase-messaging` SDK. If you need to change the version, you can add a project ext property `firebaseMessagingVersion` like so: | ||
The plugin will default to version 11.8.0 of the `firebase-messaging` SDK. If you need to change the version, you can add a project ext property `firebaseMessagingVersion`: | ||
```Groovy | ||
// in the root level of /app/App_Resources/Android/app.gradle: | ||
project.ext { | ||
firebaseMessagingVersion = "+" // OR the version you wish | ||
} | ||
// in the root level of /app/App_Resources/Android/app.gradle: | ||
project.ext { | ||
firebaseMessagingVersion = "+" // OR the version you wish | ||
} | ||
``` | ||
@@ -64,170 +65,183 @@ | ||
- Edit the package.json file in the root of application, by changing the bundle identifier to match the App ID. For example: | ||
```json | ||
"id": "org.nativescript.PushNotificationApp" | ||
``` | ||
"id": "org.NativeScript.PushNotificationApp" | ||
``` | ||
- Go to the application folder and add the iOS platform to the application | ||
``` | ||
tns build ios | ||
``` | ||
```bash | ||
tns build ios | ||
``` | ||
- Go to (application folder)/platforms/ios and open the XCode project. Enable Push Notifications in the project Capabilities options. In case you don't have XCode, | ||
go to (application folder)/platforms/ios/(application folder name) , find *.entitlements file and add to it `aps-environment` key and its value as shown below: | ||
``` | ||
<plist version="1.0"> | ||
<dict> | ||
<key>aps-environment</key> | ||
<string>development</string> | ||
</dict> | ||
</plist> | ||
- Go to (application folder)/platforms/ios and open the XCode project. Enable Push Notifications in the project Capabilities options. In case you don't have XCode, go to (application folder)/platforms/ios/(application folder name) , find *.entitlements file and add to it `aps-environment` key and its value as shown below: | ||
```xml | ||
<plist version="1.0"> | ||
<dict> | ||
<key>aps-environment</key> | ||
<string>development</string> | ||
</dict> | ||
</plist> | ||
``` | ||
## Usage | ||
### Android | ||
## Usage | ||
### Using the plugin in Android | ||
Add code in your view model or component to subscribe and receive messages (don't forget to enter your Firebase Cloud Messaging **Sender ID** in the options of the register method): | ||
*TypeScript* | ||
#### TypeScript | ||
```TypeScript | ||
import * as pushPlugin from "nativescript-push-notifications"; | ||
pushPlugin.register({ senderID: '<ENTER_YOUR_PROJECT_NUMBER>' }, (token: String) => { | ||
alert("Device registered. Access token: " + token);; | ||
}, function() { }); | ||
pushPlugin.onMessageReceived((stringifiedData: String, fcmNotification: any) => { | ||
import * as pushPlugin from "nativescript-push-notifications"; | ||
private pushSettings = { | ||
senderID: "<ENTER_YOUR_PROJECT_NUMBER>", // Required: setting with the sender/project number | ||
notificationCallbackAndroid: (stringifiedData: String, fcmNotification: any) => { | ||
const notificationBody = fcmNotification && fcmNotification.getBody(); | ||
alert("Message received!\n" + notificationBody + "\n" + stringifiedData); | ||
}); | ||
this.updateMessage("Message received!\n" + notificationBody + "\n" + stringifiedData); | ||
} | ||
}; | ||
pushPlugin.register(pushSettings, (token: String) => { | ||
alert("Device registered. Access token: " + token);; | ||
}, function() { }); | ||
``` | ||
*Javascript* | ||
#### Javascript | ||
```Javascript | ||
var pushPlugin = require("nativescript-push-notifications"); | ||
pushPlugin.register({ senderID: '<ENTER_YOUR_PROJECT_NUMBER>' }, function (data){ | ||
alert("message", "" + data); | ||
}, function() { }); | ||
pushPlugin.onMessageReceived(function callback(stringifiedData, fcmNotification) { | ||
var notificationBody = fcmNotification && fcmNotification.getBody(); | ||
alert("Message received!\n" + notificationBody + "\n" + stringifiedData); | ||
}); | ||
var pushPlugin = require("nativescript-push-notifications"); | ||
var pushSettings = { | ||
senderID: "<ENTER_YOUR_PROJECT_NUMBER>", // Required: setting with the sender/project number | ||
notificationCallbackAndroid: function (stringifiedData, fcmNotification) { | ||
var notificationBody = fcmNotification && fcmNotification.getBody(); | ||
_this.updateMessage("Message received!\n" + notificationBody + "\n" + stringifiedData); | ||
} | ||
}; | ||
pushPlugin.register(pushSettings, function (token) { | ||
alert("Device registered. Access token: " + token); | ||
}, function() { }); | ||
``` | ||
- Run the app on the phone or emulator: | ||
```bash | ||
tns run android | ||
``` | ||
tns run android | ||
- The access token is written in the console and displayed on the device after the plugin sucessfully subscribes to receive notifications. When a notification comes, the message will be displayed in the notification area if the app is closed or handled directly in the notificationCallbackAndroid callback if the app is open. | ||
- The access token is written in the console and displayed on the device after the plugin sucessfully subscribes to receive notifications. When a notification comes, the message will be displayed in the notification area if the app is closed or handled directly in the onMessageReceived callback if the app is open. | ||
### Using the plugin in iOS | ||
### iOS | ||
Add code in your view model or component to subscribe and receive messages: | ||
*TypeScript* | ||
#### TypeScript | ||
```TypeScript | ||
import * as pushPlugin from "nativescript-push-notifications"; | ||
const iosSettings = { | ||
badge: true, | ||
sound: true, | ||
alert: true, | ||
interactiveSettings: { | ||
actions: [{ | ||
identifier: 'READ_IDENTIFIER', | ||
title: 'Read', | ||
activationMode: "foreground", | ||
destructive: false, | ||
authenticationRequired: true | ||
}, { | ||
identifier: 'CANCEL_IDENTIFIER', | ||
title: 'Cancel', | ||
activationMode: "foreground", | ||
destructive: true, | ||
authenticationRequired: true | ||
}], | ||
categories: [{ | ||
identifier: 'READ_CATEGORY', | ||
actionsForDefaultContext: ['READ_IDENTIFIER', 'CANCEL_IDENTIFIER'], | ||
actionsForMinimalContext: ['READ_IDENTIFIER', 'CANCEL_IDENTIFIER'] | ||
}] | ||
}, | ||
notificationCallbackIOS: (message: any) => { | ||
alert("Message received!\n" + JSON.stringify(message)); | ||
} | ||
}; | ||
import * as pushPlugin from "nativescript-push-notifications"; | ||
const iosSettings = { | ||
badge: true, | ||
sound: true, | ||
alert: true, | ||
interactiveSettings: { | ||
actions: [{ | ||
identifier: 'READ_IDENTIFIER', | ||
title: 'Read', | ||
activationMode: "foreground", | ||
destructive: false, | ||
authenticationRequired: true | ||
}, { | ||
identifier: 'CANCEL_IDENTIFIER', | ||
title: 'Cancel', | ||
activationMode: "foreground", | ||
destructive: true, | ||
authenticationRequired: true | ||
}], | ||
categories: [{ | ||
identifier: 'READ_CATEGORY', | ||
actionsForDefaultContext: ['READ_IDENTIFIER', 'CANCEL_IDENTIFIER'], | ||
actionsForMinimalContext: ['READ_IDENTIFIER', 'CANCEL_IDENTIFIER'] | ||
}] | ||
}, | ||
notificationCallbackIOS: (message: any) => { | ||
alert("Message received!\n" + JSON.stringify(message)); | ||
} | ||
}; | ||
pushPlugin.register(iosSettings, (token: String) => { | ||
alert("Device registered. Access token: " + token); | ||
pushPlugin.register(iosSettings, (token: String) => { | ||
alert("Device registered. Access token: " + token); | ||
// Register the interactive settings | ||
if(iosSettings.interactiveSettings) { | ||
pushPlugin.registerUserNotificationSettings(() => { | ||
alert('Successfully registered for interactive push.'); | ||
}, (err) => { | ||
alert('Error registering for interactive push: ' + JSON.stringify(err)); | ||
}); | ||
} | ||
}, (errorMessage: any) => { | ||
alert("Device NOT registered! " + JSON.stringify(errorMessage)); | ||
}); | ||
// Register the interactive settings | ||
if(iosSettings.interactiveSettings) { | ||
pushPlugin.registerUserNotificationSettings(() => { | ||
alert('Successfully registered for interactive push.'); | ||
}, (err) => { | ||
alert('Error registering for interactive push: ' + JSON.stringify(err)); | ||
}); | ||
} | ||
}, (errorMessage: any) => { | ||
alert("Device NOT registered! " + JSON.stringify(errorMessage)); | ||
}); | ||
``` | ||
*Javascript* | ||
#### Javascript | ||
```Javascript | ||
var pushPlugin = require("nativescript-push-notifications"); | ||
var iosSettings = { | ||
badge: true, | ||
sound: true, | ||
alert: true, | ||
interactiveSettings: { | ||
actions: [{ | ||
identifier: 'READ_IDENTIFIER', | ||
title: 'Read', | ||
activationMode: "foreground", | ||
destructive: false, | ||
authenticationRequired: true | ||
}, { | ||
identifier: 'CANCEL_IDENTIFIER', | ||
title: 'Cancel', | ||
activationMode: "foreground", | ||
destructive: true, | ||
authenticationRequired: true | ||
}], | ||
categories: [{ | ||
identifier: 'READ_CATEGORY', | ||
actionsForDefaultContext: ['READ_IDENTIFIER', 'CANCEL_IDENTIFIER'], | ||
actionsForMinimalContext: ['READ_IDENTIFIER', 'CANCEL_IDENTIFIER'] | ||
}] | ||
}, | ||
notificationCallbackIOS: function (data) { | ||
alert("message", "" + JSON.stringify(data)); | ||
} | ||
}; | ||
var pushPlugin = require("nativescript-push-notifications"); | ||
var iosSettings = { | ||
badge: true, | ||
sound: true, | ||
alert: true, | ||
interactiveSettings: { | ||
actions: [{ | ||
identifier: 'READ_IDENTIFIER', | ||
title: 'Read', | ||
activationMode: "foreground", | ||
destructive: false, | ||
authenticationRequired: true | ||
}, { | ||
identifier: 'CANCEL_IDENTIFIER', | ||
title: 'Cancel', | ||
activationMode: "foreground", | ||
destructive: true, | ||
authenticationRequired: true | ||
}], | ||
categories: [{ | ||
identifier: 'READ_CATEGORY', | ||
actionsForDefaultContext: ['READ_IDENTIFIER', 'CANCEL_IDENTIFIER'], | ||
actionsForMinimalContext: ['READ_IDENTIFIER', 'CANCEL_IDENTIFIER'] | ||
}] | ||
}, | ||
notificationCallbackIOS: function (data) { | ||
alert("message", "" + JSON.stringify(data)); | ||
} | ||
}; | ||
pushPlugin.register(iosSettings, function (data) { | ||
alert("Device registered. Access token" + data); | ||
pushPlugin.register(iosSettings, function (data) { | ||
alert("Device registered. Access token" + data); | ||
// Register the interactive settings | ||
if(iosSettings.interactiveSettings) { | ||
pushPlugin.registerUserNotificationSettings(function() { | ||
alert('Successfully registered for interactive push.'); | ||
}, function(err) { | ||
alert('Error registering for interactive push: ' + JSON.stringify(err)); | ||
}); | ||
} | ||
}, function() { }); | ||
// Register the interactive settings | ||
if(iosSettings.interactiveSettings) { | ||
pushPlugin.registerUserNotificationSettings(function() { | ||
alert('Successfully registered for interactive push.'); | ||
}, function(err) { | ||
alert('Error registering for interactive push: ' + JSON.stringify(err)); | ||
}); | ||
} | ||
}, function() { }); | ||
``` | ||
- Run the app on the phone or simulator: | ||
```bash | ||
tns run ios | ||
``` | ||
tns run ios | ||
- [HINT] Install the [pusher app](https://github.com/noodlewerk/NWPusher) to send notifications to the device being debugged on. In the 'device push token' field paste the device access token generated in the {N} CLI / XCode debug console after launching the app. | ||
## API Reference | ||
## API Reference | ||
#### register(options, successCallback, errorCallback) - subscribe the device with Apple/Google push notifications services so the app can receive notifications. Options can contain: | ||
### Methods | ||
#### register(options, successCallback, errorCallback) - subscribe the device with Apple/Google push notifications services so the app can receive notifications | ||
| Option | Platform | Type | Description | | ||
| --- | --- | --- | --- | | ||
| senderID | Android | String | The Sender ID for the FCM project. This option is required for Android. | | ||
| notificationCallbackAndroid | Android | Function | Callback to invoke, when a push is received on Android. | | ||
| badge | iOS | Boolean | Enable setting the badge through Push Notification. | | ||
@@ -238,3 +252,3 @@ | sound | iOS | Boolean | Enable playing a sound. | | ||
| notificationCallbackIOS | iOS | Function | Callback to invoke, when a push is received on iOS. | | ||
| interactiveSettings | iOS | Object | Interactive settings for use when registerUserNotificationSettings is used on iOS. | | ||
| interactiveSettings | iOS | Object | Interactive settings for use when registerUserNotificationSettings is used on iOS. | | ||
@@ -248,3 +262,3 @@ The interactiveSettings object for iOS can contain the following: | ||
The `actions` array from the iOS interactive settings contains: | ||
The `actions` array from the iOS interactive settings contains: | ||
@@ -260,3 +274,3 @@ | Option | Type | Description | | ||
The `categories` array from the iOS interactive settings contains: | ||
The `categories` array from the iOS interactive settings contains: | ||
@@ -271,61 +285,53 @@ | Option | Type | Description | | ||
*Javascript* | ||
```Javascript | ||
var settings = { | ||
badge: true, | ||
sound: true, | ||
alert: true, | ||
interactiveSettings: { | ||
actions: [{ | ||
identifier: 'READ_IDENTIFIER', | ||
title: 'Read', | ||
activationMode: "foreground", | ||
destructive: false, | ||
authenticationRequired: true | ||
}, { | ||
identifier: 'CANCEL_IDENTIFIER', | ||
title: 'Cancel', | ||
activationMode: "foreground", | ||
destructive: true, | ||
authenticationRequired: true | ||
}], | ||
categories: [{ | ||
identifier: 'READ_CATEGORY', | ||
actionsForDefaultContext: ['READ_IDENTIFIER', 'CANCEL_IDENTIFIER'], | ||
actionsForMinimalContext: ['READ_IDENTIFIER', 'CANCEL_IDENTIFIER'] | ||
}] | ||
}, | ||
notificationCallbackIOS: function(message) { | ||
alert(JSON.stringify(message)); | ||
} | ||
}; | ||
var settings = { | ||
badge: true, | ||
sound: true, | ||
alert: true, | ||
interactiveSettings: { | ||
actions: [{ | ||
identifier: 'READ_IDENTIFIER', | ||
title: 'Read', | ||
activationMode: "foreground", | ||
destructive: false, | ||
authenticationRequired: true | ||
}, { | ||
identifier: 'CANCEL_IDENTIFIER', | ||
title: 'Cancel', | ||
activationMode: "foreground", | ||
destructive: true, | ||
authenticationRequired: true | ||
}], | ||
categories: [{ | ||
identifier: 'READ_CATEGORY', | ||
actionsForDefaultContext: ['READ_IDENTIFIER', 'CANCEL_IDENTIFIER'], | ||
actionsForMinimalContext: ['READ_IDENTIFIER', 'CANCEL_IDENTIFIER'] | ||
}] | ||
}, | ||
notificationCallbackIOS: function(message) { | ||
alert(JSON.stringify(message)); | ||
} | ||
}; | ||
pushPlugin.register(settings, | ||
// Success callback | ||
function(token){ | ||
// if we're on android device we have the onMessageReceived function to subscribe | ||
// for push notifications | ||
if(pushPlugin.onMessageReceived) { | ||
pushPlugin.onMessageReceived(settings.notificationCallbackAndroid); | ||
} | ||
// Register the interactive settings | ||
if(settings.interactiveSettings) { | ||
pushPlugin.registerUserNotificationSettings(function() { | ||
alert('Successfully registered for interactive push.'); | ||
}, function(err) { | ||
alert('Error registering for interactive push: ' + JSON.stringify(err)); | ||
}); | ||
} | ||
}, | ||
// Error Callback | ||
function(error){ | ||
alert(error.message); | ||
} | ||
); | ||
pushPlugin.register(settings, | ||
// Success callback | ||
function(token){ | ||
// Register the interactive settings | ||
if(settings.interactiveSettings) { | ||
pushPlugin.registerUserNotificationSettings(function() { | ||
alert('Successfully registered for interactive push.'); | ||
}, function(err) { | ||
alert('Error registering for interactive push: ' + JSON.stringify(err)); | ||
}); | ||
} | ||
}, | ||
// Error Callback | ||
function(error){ | ||
alert(error.message); | ||
} | ||
); | ||
``` | ||
#### unregister(successCallback, errorCallback, options) - unsubscribe the device so the app stops receiving push notifications. The options object is the same as on the `register` method. | ||
#### unregister(successCallback, errorCallback, options) - unsubscribe the device so the app stops receiving push notifications. The options object is the same as on the `register` method | ||
@@ -339,16 +345,15 @@ | Parameter | Platform | Type | Description | | ||
*Javascript* | ||
```Javascript | ||
pushPlugin.unregister( | ||
// Success callback | ||
function(result) { | ||
alert('Device unregistered successfully'); | ||
}, | ||
// Error Callback | ||
function(errorMessage) { | ||
alert(errorMessage); | ||
}, | ||
// The settings from the registration phase | ||
settings | ||
); | ||
pushPlugin.unregister( | ||
// Success callback | ||
function(result) { | ||
alert('Device unregistered successfully'); | ||
}, | ||
// Error Callback | ||
function(errorMessage) { | ||
alert(errorMessage); | ||
}, | ||
// The settings from the registration phase | ||
settings | ||
); | ||
``` | ||
@@ -362,12 +367,11 @@ | ||
*Javascript* | ||
```Javascript | ||
pushPlugin.areNotificationsEnabled(function(areEnabled) { | ||
alert('Are Notifications enabled: ' + areEnabled); | ||
pushPlugin.areNotificationsEnabled(function(areEnabled) { | ||
alert('Are Notifications enabled: ' + areEnabled); | ||
}); | ||
``` | ||
### Android only: | ||
### Android only methods | ||
#### onMessageReceived(callback) - register a callback function to execute when receiving a notification. Callback function has the followint parameters: | ||
#### onMessageReceived(callback) ***DEPRECATED*** - register a callback function to execute when receiving a notification. You should set this from the `notificationCallbackAndroid` registration option instead | ||
@@ -381,5 +385,5 @@ | Parameter | Type | Description | | ||
| Method | Returns | | ||
| Method | Returns | | ||
| --- | --- | | ||
| getBody() | String | | ||
| getBody() | String | | ||
| getBodyLocalizationArgs() | String[] | | ||
@@ -396,3 +400,3 @@ | getBodyLocalizationKey() | String | | ||
#### onTokenRefresh(callback) - register a callback function to execute when the old token is revoked and a new token is obtained. Note that the token is _not_ passed to the callback as an argument. If you need the new token value, you'll need to call `register` again or add some native code to obtain the token from FCM. | ||
#### onTokenRefresh(callback) - register a callback function to execute when the old token is revoked and a new token is obtained. Note that the token is _not_ passed to the callback as an argument. If you need the new token value, you'll need to call `register` again or add some native code to obtain the token from FCM | ||
@@ -403,14 +407,11 @@ | Parameter | Type | Description | | ||
*Javascript* | ||
```Javascript | ||
pushPlugin.onTokenRefresh(function() { | ||
alert("new token obtained"); | ||
}); | ||
pushPlugin.onTokenRefresh(function() { | ||
alert("new token obtained"); | ||
}); | ||
``` | ||
### iOS only: | ||
### iOS only | ||
#### registerUserNotificationSettings(successCallback, errorCallback) - used to register for interactive push on iOS. | ||
#### registerUserNotificationSettings(successCallback, errorCallback) - used to register for interactive push on iOS | ||
@@ -426,50 +427,9 @@ | Parameter | Type | Description | | ||
### Android | ||
### Troubleshooting issues in Android | ||
- When the application is started using `tns run android` (i.e. in debug mode with livesync) some background notifications might not be received correctly. This happens because the app is not started in a normal way for debugging and the resume from background happens differently. To receive all notifications correctly, stop the app (swipe it away it from the recent apps list) and start it again by tapping the app icon on the device. | ||
- When the application is started using `tns run android` (i.e. in debug mode with livesync) some background notifications might not be received correctly. This happens because the app is not started in a normal way for debugging and the resume from background happens differently. To receive all notifications correctly, stop the app (swipe it away it from the recent apps list) and start it again by tapping the app icon on the device. | ||
- Ensure that the AndroidManifest.xml located at platforms/android/build/... (**do not add it in your "App_Resources/Android/AndroidManifest.xml" file**) contains the following snippets for registering the GCM listener: | ||
```XML | ||
<activity android:name="com.telerik.pushplugin.PushHandlerActivity"/> | ||
<receiver | ||
android:name="com.google.android.gms.gcm.GcmReceiver" | ||
android:exported="true" | ||
android:permission="com.google.android.c2dm.permission.SEND" > | ||
<intent-filter> | ||
<action android:name="com.google.android.c2dm.intent.RECEIVE" /> | ||
<category android:name="com.pushApp.gcm" /> | ||
</intent-filter> | ||
</receiver> | ||
<service | ||
android:name="com.telerik.pushplugin.PushPlugin" | ||
android:exported="false" > | ||
<intent-filter> | ||
<action android:name="com.google.android.c2dm.intent.RECEIVE" /> | ||
</intent-filter> | ||
</service> | ||
``` | ||
- Ensure that the AndroidManifest.xml located at platforms/android/build/... contains the following permissions for push notifications: | ||
```xml | ||
<uses-permission android:name="android.permission.WAKE_LOCK" /> | ||
<uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" /> | ||
``` | ||
### iOS | ||
- Error "Error registering: no valid 'aps-environment' entitlement string found for application" - this means that the certificates are not correctly set in the xcodeproject. Open the xcodeproject, fix them and you can even run the application from xcode to verify it's setup correctly. The bundle identifier in xcode should be the same as the "id" in the package.json file in the root of the project. Also make sure that "Push Notifications" is switched ON in the "Capabilities" page of the project settings. | ||
## Android Configuration for using Firebase Cloud Messaging | ||
The `nativescript-push-notifications` module for Android relies on the Firebase Cloud Messaging (FCM) SDK. In the steps below you will be guided to complete a few additional steps to prepare your Android app to receive push notifications from FCM. | ||
1. Add the FCM SDK | ||
> Thе `google-services` plugin is added automatically. If this fails, you can try adding it manually: | ||
- Navigate to the project `platforms/android/` folder and locate the application-level `build.gradle` file | ||
- Add the `google-services` plugin to the list of other dependencies in your app's `build.gradle` file | ||
- Thе `google-services` plugin is added automatically. If this fails, you can try adding it manually: | ||
- - Navigate to the project `platforms/android/` folder and locate the application-level `build.gradle` file | ||
- - Add the `google-services` plugin to the list of other dependencies in your app's `build.gradle` file | ||
```Groovy | ||
@@ -482,3 +442,3 @@ dependencies { | ||
``` | ||
- Add the following line be at the bottom of your `build.gradle` file to enable the Gradle plugin | ||
- - Add the following line be at the bottom of your `build.gradle` file to enable the Gradle plugin | ||
```Groovy | ||
@@ -488,12 +448,47 @@ apply plugin: 'com.google.gms.google-services' | ||
2. Add the `google-services.json` file | ||
- Ensure that the AndroidManifest.xml located at platforms/android/build/... (**do not add it in your "App_Resources/Android/AndroidManifest.xml" file**) contains the following snippets for registering the GCM listener: | ||
```XML | ||
<activity android:name="com.telerik.pushplugin.PushHandlerActivity"/> | ||
<receiver | ||
android:name="com.google.android.gms.gcm.GcmReceiver" | ||
android:exported="true" | ||
android:permission="com.google.android.c2dm.permission.SEND" > | ||
<intent-filter> | ||
<action android:name="com.google.android.c2dm.intent.RECEIVE" /> | ||
<category android:name="com.pushApp.gcm" /> | ||
</intent-filter> | ||
</receiver> | ||
<service | ||
android:name="com.telerik.pushplugin.PushPlugin" | ||
android:exported="false" > | ||
<intent-filter> | ||
<action android:name="com.google.android.c2dm.intent.RECEIVE" /> | ||
</intent-filter> | ||
</service> | ||
``` | ||
To use FCM, you need this file. It contains configurations and credentials for your Firebase project. To obtain this follow the instructions for adding Firebase to your project from the official [documentation](https://firebase.google.com/docs/android/setup). Scroll down to the **Manually add Firebase** section. | ||
- Ensure that the AndroidManifest.xml located at platforms/android/build/... contains the following permissions for push notifications: | ||
```xml | ||
<uses-permission android:name="android.permission.WAKE_LOCK" /> | ||
<uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" /> | ||
``` | ||
Place the file in your app's `App_Resources/Android` folder | ||
### Troubleshooting issues in iOS | ||
3. Obtain the FCM Server Key | ||
- Error "Error registering: no valid 'aps-environment' entitlement string found for application" - this means that the certificates are not correctly set in the xcodeproject. Open the xcodeproject, fix them and you can even run the application from xcode to verify it's setup correctly. The bundle identifier in xcode should be the same as the "id" in the package.json file in the root of the project. Also make sure that "Push Notifications" is switched ON in the "Capabilities" page of the project settings. | ||
This key is required to be able to send programmatically push notifications to your app. You can obtain this key from your Firebase project. | ||
## Android Configuration for using Firebase Cloud Messaging | ||
The `nativescript-push-notifications` module for Android relies on the Firebase Cloud Messaging (FCM) SDK. In the steps below you will be guided to complete a few additional steps to prepare your Android app to receive push notifications from FCM. | ||
1. Add the `google-services.json` file | ||
To use FCM, you need this file. It contains configurations and credentials for your Firebase project. To obtain this follow the instructions for adding Firebase to your project from the official [documentation](https://firebase.google.com/docs/android/setup). Scroll down to the **Manually add Firebase** section. | ||
Place the file in your app's `App_Resources/Android` folder | ||
2. Obtain the FCM Server Key (optional) | ||
This key is required to be able to send programmatically push notifications to your app. You can obtain this key from your Firebase project. | ||
### Receive and Handle Messages from FCM on Android | ||
@@ -503,19 +498,19 @@ | ||
The plugin extends the `FirebaseMessagingService` and overrides its `onMessageReceived` callback. In your app you need to use the `onMessageReceived(stringifiedData, fcmNotification)` method of the NativeScript module. | ||
The plugin extends the `FirebaseMessagingService` and overrides its `onMessageReceived` callback. In your app you need to use the `notificationCallbackAndroid` setting when calling the `register` method of the plugin. | ||
The behavior of the `onMessageReceived` callback in the module follows the behavior of the FCM service. | ||
The behavior of the callback in the module follows the behavior of the FCM service. | ||
#### Handling **Data** Messages | ||
The `onMessageReceived` method of the plugin is called each time a `data` notification is received. | ||
The `notificationCallbackAndroid` method of the plugin is called each time a `data` notification is received. | ||
If the app is stopped or suspended, NO notification is constructed and placed in the tray. Tapping the app icon launches the app and invokes the `onMessageReceived` callback where you will receive the notification data. | ||
If the app is stopped or suspended, NO notification is constructed and placed in the tray. Tapping the app icon launches the app and invokes the `notificationCallbackAndroid` callback where you will receive the notification data. | ||
If the app is active and in foreground, the `onMessageReceived` callback is invoked immediately with the notification data (fcmNotification). | ||
If the app is active and in foreground, the `notificationCallbackAndroid` callback is invoked immediately with the notification data (fcmNotification). | ||
#### Handling **Notification** Messages | ||
If the app is active and in foreground, it invokes the `onMessageReceived` callback with two arguments (stringifiedData, fcmNotification). | ||
If the app is active and in foreground, it invokes the `notificationCallbackAndroid` callback with two arguments (stringifiedData, fcmNotification). | ||
If the app is in background, a notification is put in the tray. When tapped, it launches the app, but does not invoke the `onMessageReceived` callback. | ||
If the app is in background, a notification is put in the tray. When tapped, it launches the app, but does not invoke the `notificationCallbackAndroid` callback. | ||
@@ -526,8 +521,7 @@ #### Handling **Mixed** Messages | ||
- The app is in foreground, the `onMessageReceived` callback is invoked with parameters (stringifiedData, fcmNotification) | ||
- The app is in background, the `onMessageReceived` callback is not invoked. A notification is placed in the system tray. If the notification in the tray is tapped, the `data` part of the mixed message is available in the extras of the intent of the activity and are available in the respective [application event](https://docs.nativescript.org/core-concepts/application-lifecycle) of NativeScript. | ||
- The app is in foreground, the `notificationCallbackAndroid` callback is invoked with parameters (stringifiedData, fcmNotification) | ||
- The app is in background, the `notificationCallbackAndroid` callback is not invoked. A notification is placed in the system tray. If the notification in the tray is tapped, the `data` part of the mixed message is available in the extras of the intent of the activity and are available in the respective [application event](https://docs.nativescript.org/core-concepts/application-lifecycle) of NativeScript. | ||
Example of handling the `data` part in the application *resume* event (e.g. the app was brought to the foreground from the notification): | ||
*Javascript* | ||
```Javascript | ||
@@ -549,23 +543,22 @@ application.on(application.resumeEvent, function(args) { | ||
#### Parameters of the onMessageReceived Callback | ||
#### Parameters of the notificationCallbackAndroid Callback | ||
Depending on the notification event and payload, the `onMessageReceived` callback is invoked with two arguments. | ||
Depending on the notification event and payload, the `notificationCallbackAndroid` callback is invoked with two arguments. | ||
* `stringifiedData` - *String*. A stringified JSON representation of the `data` value in the notification payload. | ||
* `fcmNotification` - `RemoteMessage.Notification`. A representation of the `RemoteMessage.Notification` class which can be accessed according to its public methods. This parameter is available in case the callback was called from a message with a `notification` key in the payload. | ||
- `stringifiedData` - *String*. A stringified JSON representation of the `data` value in the notification payload. | ||
- `fcmNotification` - `RemoteMessage.Notification`. A representation of the `RemoteMessage.Notification` class which can be accessed according to its public methods. This parameter is available in case the callback was called from a message with a `notification` key in the payload. | ||
#### Setting Notification Icon and Color | ||
The plugin automatically handles some keys in the `data` object like `message`, `title`, `color`, `smallIcon`, `largeIcon` and uses them to construct a notification entry in the tray. | ||
The plugin automatically handles some keys in the `data` object like `message`, `title`, `color`, `smallIcon`, `largeIcon` and uses them to construct a notification entry in the tray. | ||
Custom default color and icon for **notification** messages can be set in the `AndroidManifest.xml` inside the `application` directive: | ||
```XML | ||
<meta-data | ||
android:name="com.google.firebase.messaging.default_notification_icon" | ||
android:resource="@drawable/ic_stat_ic_notification" /> | ||
<meta-data | ||
android:name="com.google.firebase.messaging.default_notification_color" | ||
android:resource="@color/colorAccent" /> | ||
<meta-data | ||
android:name="com.google.firebase.messaging.default_notification_icon" | ||
android:resource="@drawable/ic_stat_ic_notification" /> | ||
<meta-data | ||
android:name="com.google.firebase.messaging.default_notification_color" | ||
android:resource="@color/colorAccent" /> | ||
``` | ||
> For more info visit the [Edit the app manifest](https://firebase.google.com/docs/cloud-messaging/android/topic-messaging#edit-the-app-manifest) article. |
Sorry, the diff of this file is not supported yet
487249
24
486
547