Push
Register and receive push notifications.
Requires Cordova plugin: phonegap-plugin-push. For more info, please see the Push plugin docs.
For TypeScript users, see the Push plugin docs about using TypeScript for custom notifications.
Repo: https://github.com/phonegap/phonegap-plugin-push
Installation
- Install the Cordova and Ionic Native plugins:
$ ionic cordova plugin add phonegap-plugin-push $ npm install --save @ionic-native/push@4 - Add this plugin to your app's module
Supported platforms
- Android
- Browser
- iOS
- Windows
Usage
import { Push, PushObject, PushOptions } from '@ionic-native/push';
constructor(private push: Push) { }
...
// to check if we have permission
this.push.hasPermission()
.then((res: any) => {
if (res.isEnabled) {
console.log('We have permission to send push notifications');
} else {
console.log('We do not have permission to send push notifications');
}
});
// Create a channel (Android O and above). You'll need to provide the id, description and importance properties.
this.push.createChannel({
id: "testchannel1",
description: "My first test channel",
// The importance property goes from 1 = Lowest, 2 = Low, 3 = Normal, 4 = High and 5 = Highest.
importance: 3
}).then(() => console.log('Channel created'));
// Delete a channel (Android O and above)
this.push.deleteChannel('testchannel1').then(() => console.log('Channel deleted'));
// Return a list of currently configured channels
this.push.listChannels().then((channels) => console.log('List of channels', channels))
// to initialize push notifications
const options: PushOptions = {
android: {},
ios: {
alert: 'true',
badge: true,
sound: 'false'
},
windows: {},
browser: {
pushServiceURL: 'http://push.api.phonegap.com/v1/push'
}
};
const pushObject: PushObject = this.push.init(options);
pushObject.on('notification').subscribe((notification: any) => console.log('Received a notification', notification));
pushObject.on('registration').subscribe((registration: any) => console.log('Device registered', registration));
pushObject.on('error').subscribe(error => console.error('Error with Push plugin', error));
Instance Members
init(options)
Init push notifications
| Param | Type | Details |
|---|---|---|
| options |
PushOptions
|
Returns: PushObject
hasPermission()
Check whether the push notification permission has been granted.
Returns: Promise<{isEnabled: boolean}> Returns a Promise that resolves with an object with one property: isEnabled, a boolean that indicates if permission has been granted.
createChannel(channel)
Create a new notification channel for Android O and above.
| Param | Type | Details |
|---|---|---|
| channel |
Channel
|
deleteChannel(id)
Delete a notification channel for Android O and above.
| Param | Type | Details |
|---|---|---|
| id |
string
|
listChannels()
Returns a list of currently configured channels.
Returns: Promise<Channel[]>
RegistrationEventResponse
| Param | Type | Details |
|---|---|---|
| registrationId |
string
|
The registration ID provided by the 3rd party remote push service. |
NotificationEventResponse
| Param | Type | Details |
|---|---|---|
| message |
string
|
The text of the push message sent from the 3rd party service. |
| title |
string
|
The optional title of the push message sent from the 3rd party service. (optional) |
| count |
string
|
The number of messages to be displayed in the badge iOS or message count in the notification shade in Android. For windows, it represents the value in the badge notification which could be a number or a status glyph. |
| sound |
string
|
The name of the sound file to be played upon receipt of the notification. |
| image |
string
|
The path of the image file to be displayed in the notification. |
| additionalData |
NotificationEventAdditionalData & any
|
An optional collection of data sent by the 3rd party push service that does not fit in the above properties. |
NotificationEventAdditionalData
| Param | Type | Details |
|---|---|---|
| foreground |
boolean
|
Whether the notification was received while the app was in the foreground (optional) |
| collapse_key |
string
|
(optional) |
| coldstart |
boolean
|
(optional) |
| from |
string
|
(optional) |
| notId |
string
|
(optional) |
IOSPushOptions
| Param | Type | Details |
|---|---|---|
| fcmSandbox |
boolean | string
|
Whether to use prod or sandbox GCM setting. (optional) |
| alert |
boolean | string
|
If true the device shows an alert on receipt of notification. Note: the value you set this option to the first time you call the init method will be how the application always acts. Once this is set programmatically in the init method it can only be changed manually by the user in Settings>Notifications>App Name. This is normal iOS behaviour. (optional) |
| badge |
boolean | string
|
If true the device sets the badge number on receipt of notification. Note: the value you set this option to the first time you call the init method will be how the application always acts. Once this is set programmatically in the init method it can only be changed manually by the user in Settings>Notifications>App Name. This is normal iOS behaviour. (optional) |
| sound |
boolean | string
|
If true the device plays a sound on receipt of notification. Note: the value you set this option to the first time you call the init method will be how the application always acts. Once this is set programmatically in the init method it can only be changed manually by the user in Settings>Notifications>App Name. This is normal iOS behaviour. (optional) |
| clearBadge |
boolean | string
|
If true the badge will be cleared on app startup. (optional) |
| topics |
string[]
|
If the array contains one or more strings each string will be used to
subscribe to a GcmPubSub topic.
Note: only usable in conjunction with |
| categories |
CategoryArray
|
The data required in order to enable Action Buttons for iOS. Action Buttons on iOS - https://github.com/phonegap/phonegap-plugin-push/blob/master/docs/PAYLOAD.md#action-buttons-1 (optional) |
| voip |
boolean | string
|
If true the device will be set up to receive VoIP Push notifications and the other options will be ignored since VoIP notifications are silent notifications that should be handled in the "notification" event. (optional) |
AndroidPushOptions
| Param | Type | Details |
|---|---|---|
| senderID |
string
|
Maps to the project number in the Google Developer Console. (optional) |
| icon |
string
|
The name of a drawable resource to use as the small-icon. The name should not include the extension. (optional) |
| iconColor |
string
|
Sets the background color of the small icon on Android 5.0 and greater. Supported Formats) (optional) |
| sound |
boolean | string
|
If true it plays the sound specified in the push data or the default system sound. (optional) |
| vibrate |
boolean | string
|
If true the device vibrates on receipt of notification. (optional) |
| clearBadge |
boolean | string
|
If true the icon badge will be cleared on init and before push messages are processed. (optional) |
| clearNotifications |
boolean | string
|
If true the app clears all pending notifications when it is closed. (optional) |
| forceShow |
boolean | string
|
If true will always show a notification, even when the app is on the foreground. (optional) |
| topics |
string[]
|
If the array contains one or more strings each string will be used to subscribe to a GcmPubSub topic. (optional) |
| messageKey |
string
|
The key to search for text of notification. (optional) |
| titleKey |
string
|
The key to search for title of notification. (optional) |
BrowserPushOptions
| Param | Type | Details |
|---|---|---|
| applicationServerKey |
string
|
Optional. Your GCM API key if you are using VAPID keys. (optional) |
| pushServiceURL |
string
|
URL for the push server you want to use. Default: http://push.api.phonegap.com/v1/push Optional. (optional) |
PushOptions
| Param | Type | Details |
|---|---|---|
| ios |
IOSPushOptions
|
(optional) |
| android |
AndroidPushOptions
|
(optional) |
| windows |
any
|
(optional) |
| browser |
BrowserPushOptions
|
(optional) |