com.devicepush.cordova-phonegap
v0.4.6
Published
This plugin is for use with Cordova and PhoneGap, and allows your application to receive push notifications on Android and iOS devices.
Downloads
37
Maintainers
Readme
Device Push Notification Plugin
Description
This plugin is for use with Cordova, and allows your application to receive push notifications on Android and iOS devices.
- The Android implementation uses FCM Firebase Cloud Messaging.
- The iOS version is based on APNS Notifications.
Contents
Requires Versions
- phonegap/cordova 6.0+
Supported Platforms
- Android
- iOS
How to install the Plugin
Cordova and PhoneGap CLI
The plugin can be installed via the Cordova command line interface:
Navigate to the root folder for your phonegap project.
Run the command:
cordova plugin add com.devicepush.cordova-phonegap
or
phonegap plugin add com.devicepush.cordova-phonegap
PhoneGap Build Support
The plugin can be installed via PhoneGap Build:
Open config.xml file of your project.
Add this line and replace XXXXXXX with your FCM Sender ID:
<plugin name="com.devicepush.cordova-phonegap" source="npm">
<param name="SENDER_ID" value="XXXXXXX" />
</param>
If you want to specify a particular version of the plugin you can add the version attribute to the gap tag.
<plugin name="com.devicepush.cordova-phonegap" source="npm" version="0.4.6">
<param name="SENDER_ID" value="XXXXXXX" />
</param>
Whitelist
Add *.devicepush.com domain in the config.xml file:
<access origin="*.devicepush.com" />
<allow-navigation href="*.devicepush.com" />
Plugin API
To register a new device
When the device is ready, you must call the register function.
var app = {
initialize: function() {
this.bindEvents();
},
bindEvents: function() {
document.addEventListener('deviceready', this.onDeviceReady, false);
},
onDeviceReady: function() {
app.receivedEvent('deviceready');
devicePush.register({
idUser: 'USER_ID', // Your User ID in Device Push
idApplication: 'APPLICATION_ID', // Aplication ID in Device Push
position: true // Activate or deactivate gps position record. Default value is false
additionalData: {} // Include additional data of the current user for targeting
});
},
receivedEvent: function(id) {}
};
To unregister a device
You must call the unregister function.
devicePush.unregister();
To get id or token device
You can get the device id or token of the device.
document.addEventListener("deviceRegistered", successDeviceRegistered, false);
function successDeviceRegistered(evt){
console.log("Device Id" + evt.devicePushId);
var id = evt.devicePushId;
console.log("Device Token" + evt.devicePushToken);
var tokenDevice = evt.devicePushToken;
}
With this ID you can send notification from your server.
To manager a notification received
You can manage notifications received with the next method
document.addEventListener('notificationReceived', successNotificationReceived, false);
function successNotificationReceived(evt){
// evt.data.message,
// evt.data.title,
// evt.data.count,
// evt.data.sound,
// evt.data.image,
// evt.data.additionalData
console.log(evt.data.message) // data is your text sent
}
When you unregister device
You can unregister device.
document.addEventListener("deviceUnregistered", successDeviceUnregistered, false);
function successDeviceUnregistered(){
//TODO
}
When happen any error
The event error will trigger when an internal error occurs and the cache is aborted.
document.addEventListener("deviceError", successDeviceError, false);
function successDeviceError(){
//TODO
}
To show a dynamic and floating notification, you have to add the following function into the function successNotificationReceived.
devicePush.showNotification(evt.data.message);
To activate or not gps position record
You can activate or deactivate gps position record.
devicePush.setPosition(true); //Active gps position record, true o false. Default value is false.
To put additional user data for segmentation
To activate the segmentation of notifications, you will have to send additional user data, such as personal data.
devicePush.putAdditionalData({
name: '',
surnames: '',
age: '',
gender: ''
});
When the additional data is updated
document.addEventListener("additionalDataUpdated", successAdditionalDataUpdated, false);
function successAdditionalDataUpdated(){
//TODO
}
You can see more information about this at: https://www.devicepush.com/es/phonegap-cordova/
Looking at the above message handling code for Android, a few things bear explanation. Your app may receive a notification while it is active (INLINE). If you background the app by hitting the Home button on your device, you may later receive a status bar notification. Selecting that notification from the status will bring your app to the front and allow you to process the notification (BACKGROUND). Finally, should you completely exit the app by hitting the back button from the home page, you may still receive a notification. Touching that notification in the notification tray will relaunch your app and allow you to process the notification (COLDSTART). In this case the coldstart flag will be set on the incoming event. You can look at the foreground flag on the event to determine whether you are processing a background or an in-line notification. You may choose, for example to play a sound or show a dialog only for inline or coldstart notifications since the user has already been alerted via the status bar.
Since the Android notification data models are much more flexible than that of iOS, there may be additional elements beyond message. You can access those elements and any additional ones via the payload element. This means that if your data model should change in the future, there will be no need to change and recompile the plugin.
License
The MIT License
Copyright (c) 2017 Device Push.
portions Copyright (c) 2017 Device Push
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.