README
Introduction
The Cordova plugin is designed to work in conjunction with the existing Javascript SDK. It allows your Cordova or PhoneGap app to easily receive native Push Notifications and use all the functionality of the Donky JavaScript SDK.
Read through the sections below to discover how to deploy and use the Donky Cordova Plugin to Donky enable your apps:
Compatability
This plugin supports iOS (7 and above) and Android (4.0 - API level 14 and above). It works with Cordova and PhoneGap frameworks.
Installation
To install the plugin into your app, simply execute the following command in your applications development folder. If you are using PhoneGap or Ionic then substitute in the relevant CLI command name.
The android senderId is specified as a variable (SENDER_ID) when the plugin is added. More information about FCM here.
If your app is iOS only, or you wish to use to use the Donky default FCM configuration, you don't need to specify the SENDER_ID variable.
If you want to change the SENDER_ID, you can remove the plugin and then re-add it specifying the different SENDER_ID.
From Github
$ cordova plugin add https://github.com/Donky-Network/cordova-plugin-donky-jsmodular
or if you want to specify a senderId
$ cordova plugin add https://github.com/Donky-Network/cordova-plugin-donky-jsmodular --variable SENDER_ID=\"XXXXXXXXXX\"
Via NPM
$ cordova plugin add cordova-plugin-donky-jsmodular
or if you want to specify a senderId
$ cordova plugin add cordova-plugin-donky-jsmodular --variable SENDER_ID=\"XXXXXXXXXX\"
Dependencies
donkyLogicBundle.js
This plugin is intended to be used with the Donky Javascript SDK.
This has been bundled with this plugin and can be included in your index.html as follows
<script src="js/jquery-1.11.2.min.js"></script>
<script src="js/jquery.signalR-2.2.0.min.js"></script>
<script src="lib/donky/js/donkyLogicBundle.js"></script>
jQuery and signalR Dependencies
As can be seen in the above snippet, the Donky SDK has dependencies on jQuery and signalR
This bundle contains all of the Donky logic modules apart from the donkyCoreAnalytics module which is incompatible. (If you want to cherry pick the bare minimum modules, then you can do that too)
The Logic Bundle can also be downloaded from here:
https://cdn.dnky.co/sdk/2.2.3.5/modules/donkyLogicBundle.js
https://cdn.dnky.co/sdk/2.2.3.5/modules/donkyLogicBundle.min.js
or for the latest version ...
https://cdn.dnky.co/sdk/latest-modular/modules/donkyLogicBundle.js
https://cdn.dnky.co/sdk/latest-modular/modules/donkyLogicBundle.min.js
Note: 2.2.3.5 is the MINIMUM version of the SDK that supports this plugin
Push configuration
To use push in your app you will need to setup APNS and FCM (The above links are links to the respective Donky native SDK push configuration sections)
Setting FCM Sender ID
Setting FCM Sender ID in your application resources in res/values/strings.xml is NOT necessary as we will specify it when we install the plugin
Initialisation
Here is a minimal code fragment showing how to initialise everything. You need to do the following in sequence:
- Wait for device ready event
- Initialise the Donky plugin
- Initialise the Donky SDK
As can be seen, a pushOptions object is passed into the initialise method which allows the customisation of the native push message.
// Wait for device ready ...
document.addEventListener('deviceready', function(){
// Initialise plugin ....
var pushOptions = {
ios: {
clearTray: false
},
android:{
vibrate: true,
icon: "newMessage",
iconColor: "green"
}
};
window.cordova.plugins.donkyPlugin.initialise(function(){
// Initialise Donky
donkyCore.initialise({
apiKey: ">>>YOUR API KEY<<<",
resultHandler: function(result) {
if(result.succeeded) {
// Your cool app code ...
}else{
console.error(result);
}
}
});
}, function(e){
console.error("initialise failed", JSON.stringify(e));
}, pushOptions );
}, false);
Push Options
Here is a summary of the available push options:
Android
| Attribute | Type | Default | Description |
|---|---|---|---|
| android.vibrate | boolean | true | Optional. If true the device vibrates on receipt of notification. |
| android.icon | string | Optional. The name of a drawable resource to use as the small-icon. The name should not include the extension. | |
| android.iconColor | string | Optional. Sets the background color of the small icon on Android 5.0 and greater. Supported Formats |
iOS
| Attribute | Type | Default | Description |
|---|---|---|---|
| ios.clearTray | boolean | true | Determines whether the native notification tray is cleared when the badge count becomes zero |
Push Registration
Native Push registration is internally managed by the plugin. The plugin subscribes to the local event DonkyInitialised and performs the push registration off the back of this. The APNS device token / FCM registrationId is queried from the device and then it is sent to Donky.
You can register to listen for a local event (registerForPush), which is published after the native push registration has been performed which will indicate success or failure.
// Listen for Donky's push registration result
donkyCore.subscribeToLocalEvent("registerForPush", function (event) {
var result = event.data;
if(result.succeded){
console.log("registerForPush succeeded", result.token);
}else{
console.error("registerForPush succeeded", result.error);
}
});
Enabling / Disabling push notifications
If you would like to enable / disable push notifications in your app, you can do this using the following method:
Enable Push
// Enable
donkyCore.donkyAccount.enablePush(true, function(result){
// callback function fires when cached push token sent to donky
if(result.succeeded){
console.log("enablePush(true) succeeded");
}else{
console.error("enablePush(true) failed");
}
});
Disable Push
// Disable
donkyCore.donkyAccount.enablePush(false, function(result){
// callback function fires when push token deleted from Donky network
if(result.succeeded){
console.log("enablePush(false) succeeded");
}else{
console.error("enablePush(false) failed");
}
});
Deep links
You can send a deep link as part of an interactive push message using Donky. These will be correctly handled by the Cordova plugin but you will need to use another plugin to correctly handle the links in your application (for routing purposes). The following two 3rd party plugins are recommended (The ionic sample app uses ionic-plugin-deeplinks)
To correctly handle deep links in your app you will need to tweak the native project files:
iOS
You will need to add LSApplicationQueriesSchemes key to your info.plist file to allow opening of deep links.
Android
You will need to modify AndroidManifest.xml
- android:launchMode needs to be set to singleTask
<activity android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale"
android:label="@string/activity_name"
**android:launchMode="singleTask"
**android:name="MainActivity"
android:theme="@android:style/Theme.DeviceDefault.NoActionBar"
android:windowSoftInputMode="adjustResize">
- add an intent filter for the scheme
<intent-filter>
<data android:scheme=">>>YOUR SCHEME NAME<<<"/>
<action android:name="android.intent.action.VIEW" />
<category android:name="android.intent.category.DEFAULT" />
<category android:name="android.intent.category.BROWSABLE" />
</intent-filter>
Location Services
Donky provides core location module that works with the HTML5 geolocation API.
If you import the cordova-plugin-geolocation plugin, it will use this API with a native location tracking sensors therefore you get the benefits of native accuracy and the ability to interact with Donky.
$ cordova plugin add cordova-plugin-geolocation
Sample Apps
Various sample projects can be found on Github, including popular frameworks such as Ionic and Angular here:
https://github.com/Donky-Network/Donky-Cordova-JSModular-Samples
The Readme.md in the root of the repo details how to get these projects running