diff options
Diffstat (limited to 'StoneIsland/plugins/phonegap-plugin-push/docs')
8 files changed, 0 insertions, 2443 deletions
diff --git a/StoneIsland/plugins/phonegap-plugin-push/docs/API.md b/StoneIsland/plugins/phonegap-plugin-push/docs/API.md deleted file mode 100644 index e0481af8..00000000 --- a/StoneIsland/plugins/phonegap-plugin-push/docs/API.md +++ /dev/null @@ -1,425 +0,0 @@ -# API - -- [.init()](#pushnotificationinitoptions) -- [.hasPermission() - Android & iOS only](#pushnotificationhaspermissionsuccesshandler---android--ios-only) -- [push.on()](#pushonevent-callback) - - [push.on('registration')](#pushonregistration-callback) - - [push.on('notification')](#pushonnotification-callback) - - [push.on('error')](#pushonerror-callback) -- [push.off()](#pushoffevent-callback) -- [push.unregister()](#pushunregistersuccesshandler-errorhandler-topics) -- [push.subscribe()](#pushsubscribetopic-successhandler-errorhandler) -- [push.unsubscribe()](#pushunsubscribetopic-successhandler-errorhandler) -- [push.setApplicationIconBadgeNumber() - iOS & Android only](#pushsetapplicationiconbadgenumbersuccesshandler-errorhandler-count---ios--android-only) -- [push.getApplicationIconBadgeNumber() - iOS only](#pushgetapplicationiconbadgenumbersuccesshandler-errorhandler---ios-only) -- [push.finish() - iOS only](#pushfinishsuccesshandler-errorhandler-id---ios-only) -- [push.clearAllNotifications() - iOS & Android only](#pushclearallnotificationssuccesshandler-errorhandler---ios--android-only) - -## PushNotification.init(options) - -Initializes the plugin on the native side. - -**Note:** like all plugins you must wait until you receive the [`deviceready`](https://cordova.apache.org/docs/en/5.4.0/cordova/events/events.deviceready.html) event before calling `PushNotification.init()`. - -**Note:** you will want to call `PushNotification.init()` each time your app starts. The remote push service can periodically reset your registration ID so this ensures you have the correct value. - -### Returns - -- Instance of `PushNotification`. - -### Parameters - -Parameter | Type | Default | Description ---------- | ---- | ------- | ----------- -`options` | `Object` | `{}` | An object describing relevant specific options for all target platforms. - -All available option attributes are described bellow. Currently, there are no Windows specific options. - -#### Android - -Attribute | Type | Default | Description ---------- | ---- | ------- | ----------- -`android.senderID` | `string` | | Maps to the project number in the Google Developer Console. -`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](http://developer.android.com/reference/android/graphics/Color.html#parseColor(java.lang.String)) -`android.sound` | `boolean` | `true` | Optional. If `true` it plays the sound specified in the push data or the default system sound. -`android.vibrate` | `boolean` | `true` | Optional. If `true` the device vibrates on receipt of notification. -`android.clearBadge` | `boolean` | `false` | Optional. If `true` the icon badge will be cleared on init and before push messages are processed. -`android.clearNotifications` | `boolean` | `true` | Optional. If `true` the app clears all pending notifications when it is closed. -`android.forceShow` | `boolean` | `false` | Optional. Controls the behavior of the notification when app is in foreground. If `true` and app is in foreground, it will show a notification in the notification drawer, the same way as when the app is in background (and `on('notification')` callback will be called *only when the user clicks the notification*). When `false` and app is in foreground, the `on('notification')` callback will be called immediately. -`android.topics` | `array` | `[]` | Optional. If the array contains one or more strings each string will be used to subscribe to a GcmPubSub topic. - -#### Browser - -Attribute | Type | Default | Description ---------- | ---- | ------- | ----------- -`browser.pushServiceURL` | `string` | `http://push.api.phonegap.com/v1/push` | Optional. URL for the push server you want to use. - -#### iOS - -All iOS boolean options can also be specified as `string` - -Attribute | Type | Default | Description ---------- | ---- | ------- | ----------- -`ios.alert` | `boolean` | `false` | Optional. 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. -`ios.badge` | `boolean` | `false` | Optional. 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. -`ios.sound` | `boolean` | `false` | Optional. 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. -`ios.clearBadge` | `boolean` | `false` | Optional. If `true` the badge will be cleared on app startup. -`ios.categories` | `Object` | `{}` | Optional. The data required in order to enabled Action Buttons for iOS. See [Action Buttons on iOS](https://github.com/phonegap/phonegap-plugin-push/blob/master/docs/PAYLOAD.md#action-buttons-1) for more details. - -#### iOS GCM support - -The following properties are used if you want use GCM on iOS. - -Attribute | Type | Default | Description ---------- | ---- | ------- | ----------- -`ios.senderID` | `string` | `undefined` (Native) | Maps to the project number in the Google Developer Console. Setting this uses GCM for notifications instead of native -`ios.gcmSandbox` | `boolean` | `false` | Whether to use prod or sandbox GCM setting. Defaults to false. -`ios.topics` | `array` | `[]` | Optional. 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 `senderID`. - -##### How GCM on iOS works. - -First it is kind of a misnomer as GCM does not send push messages directly to devices running iOS. - -What happens is on the device side is that it registers with APNS, then that registration ID is sent to GCM which returns a different GCM specific ID. That is the ID you get from the push plugin `registration` event. - -When you send a message to GCM using that ID, what it does is look up the APNS registration ID on it's side and forward the message you sent to GCM on to APSN to deliver to your iOS device. - -Make sure that the certificate you build with matches your `gcmSandbox` value. - -- If you build your app as development and set `gcmSandbox: false` it will fail. -- If you build your app as production and set `gcmSandbox: true` it will fail. -- If you build your app as development and set `gcmSandbox: true` but haven't uploaded the development certs to Google it will fail. -- If you build your app as production and set `gcmSandbox: false` but haven't uploaded the production certs to Google it will fail. - -> Note: The integration between GCM and APNS is a bit finicky. Personally, I feel it is much better to send pushes to Android using GCM and pushes to iOS using APNS which this plugin does support. - -### Example - -```javascript -var push = PushNotification.init({ - android: { - senderID: "12345679" - }, - browser: { - pushServiceURL: 'http://push.api.phonegap.com/v1/push' - }, - ios: { - alert: "true", - badge: true, - sound: 'false' - }, - windows: {} -}); -``` - -## PushNotification.hasPermission(successHandler) - Android & iOS only - -Checks whether the push notification permission has been granted. - -### Parameters - -Parameter | Type | Default | Description ---------- | ---- | ------- | ----------- -`successHandler` | `Function` | | Is called when the api successfully retrieves the details on the permission. - -### Callback parameters - -#### `successHandler` - -Parameter | Type | Description ---------- | ---- | ----------- -`data.isEnabled` | `Boolean` | Whether the permission for push notifications has been granted. - -### Example - -```javascript -PushNotification.hasPermission(function(data) { - if (data.isEnabled) { - console.log('isEnabled'); - } -}); -``` - -## push.on(event, callback) - -### Parameters - -Parameter | Type | Default | Description ---------- | ---- | ------- | ----------- -`event` | `string` | | Name of the event to listen to. See below for all the event names. -`callback` | `Function` | | Is called when the event is triggered. - -## push.on('registration', callback) - -The event `registration` will be triggered on each successful registration with the 3rd party push service. - -### Callback parameters - -Parameter | Type | Description ---------- | ---- | ----------- -`data.registrationId` | `string` | The registration ID provided by the 3rd party remote push service. - -### Example - -```javascript -push.on('registration', function(data) { - console.log(data.registrationId); -}); -``` - -For APNS users: the `registrationId` you will get will be a production or sandbox id according to how the app was built. ([Source](https://developer.apple.com/library/ios/technotes/tn2265/_index.html)) - -> Note: There is a separate persistent connection to the push service for each environment. The operating system establishes a persistent connection to the sandbox environment for development builds; ad hoc and distribution builds connect to the production environment. - - - -### Common Problems - -#### Got JSON Exception TIMEOUT - -If you run this plugin on older versions of Android and you get an error: - -``` -E/PushPlugin(20077): execute: Got JSON Exception TIMEOUT -``` - -It means you are running an older version of Google Play Services. You will need to open the Google Play Store app and update your version of Google Play Services. - -## push.on('notification', callback) - -The event `notification` will be triggered each time a push notification is received by a 3rd party push service on the device. - -### Callback parameters - -Parameter | Type | Description ---------- | ---- | ----------- -`data.message` | `string` | The text of the push message sent from the 3rd party service. -`data.title` | `string` | The optional title of the push message sent from the 3rd party service. -`data.count` | `string` | The number of messages to be displayed in the badge in iOS/Android 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. -`data.sound` | `string` | The name of the sound file to be played upon receipt of the notification. -`data.image` | `string` | The path of the image file to be displayed in the notification. -`data.launchArgs` | `string` | The args to be passed to the application on launch from push notification. This works when notification is received in background. (Windows Only) -`data.additionalData` | `Object` | An optional collection of data sent by the 3rd party push service that does not fit in the above properties. -`data.additionalData.foreground` | `boolean` | Whether the notification was received while the app was in the foreground -`data.additionalData.coldstart` | `boolean` | Will be `true` if the application is started by clicking on the push notification, `false` if the app is already started. - -### Example - -```javascript -push.on('notification', function(data) { - console.log(data.message); - console.log(data.title); - console.log(data.count); - console.log(data.sound); - console.log(data.image); - console.log(data.additionalData); -}); -``` - -## push.on('error', callback) - -The event `error` will trigger when an internal error occurs and the cache is aborted. - -### Callback parameters - -Parameter | Type | Description ---------- | ---- | ----------- -`e` | `Error` | Standard JavaScript error object that describes the error. - -### Example - -```javascript -push.on('error', function(e) { - console.log(e.message); -}); -``` - -## push.off(event, callback) - -Removes a previously registered callback for an event. - -### Parameters - -Parameter | Type | Default | Description ---------- | ---- | ------- | ----------- -`event` | `string` | | Name of the event type. The possible event names are the same as for the `push.on` function. -`callback` | `Function` | | The same callback used to register with `push.on`. - -### Example -```javascript -var callback = function(data){ /*...*/}; - -//Adding handler for notification event -push.on('notification', callback); - -//Removing handler for notification event -push.off('notification', callback); -``` - -**WARNING**: As stated in the example, you will have to store your event handler if you are planning to remove it. - -## push.unregister(successHandler, errorHandler, topics) - -The unregister method is used when the application no longer wants to receive push notifications. Beware that this cleans up all event handlers previously registered, so you will need to re-register them if you want them to function again without an application reload. - -If you provide a list of topics as an optional parameter then the application will unsubscribe from these topics but continue to receive other push messages. - -### Parameters - -Parameter | Type | Default | Description ---------- | ---- | ------- | ----------- -`successHandler` | `Function` | | Is called when the api successfully unregisters. -`errorHandler` | `Function` | | Is called when the api encounters an error while unregistering. -`topics` | `Array` | | A list of topics to unsubscribe from. - -### Example - -```javascript -push.unregister(function() { - console.log('success'); -}, function() { - console.log('error'); -}); -``` - -## push.subscribe(topic, successHandler, errorHandler) - -The subscribe method is used when the application wants to subscribe a new topic to receive push notifications. - -### Parameters - -Parameter | Type | Default | Description ---------- | ---- | ------- | ----------- -`topic` | `String` | | Topic to subscribe to. -`successHandler` | `Function` | | Is called when the api successfully subscribes. -`errorHandler` | `Function` | | Is called when the api encounters an error while subscribing. - -### Example - -```javascript -push.subscribe('my-topic', function() { - console.log('success'); -}, function(e) { - console.log('error:'); - console.log(e); -}); -``` -## push.unsubscribe(topic, successHandler, errorHandler) - -The unsubscribe method is used when the application no longer wants to receive push notifications from a specific topic but continue to receive other push messages. - -### Parameters - -Parameter | Type | Default | Description ---------- | ---- | ------- | ----------- -`topic` | `String` | | Topic to unsubscribe from. -`successHandler` | `Function` | | Is called when the api successfully unsubscribe. -`errorHandler` | `Function` | | Is called when the api encounters an error while unsubscribing. - -### Example - -```javascript -push.unsubscribe('my-topic', function() { - console.log('success'); -}, function(e) { - console.log('error:'); - console.log(e); -}); -``` - -## push.setApplicationIconBadgeNumber(successHandler, errorHandler, count) - iOS & Android only - -Set the badge count visible when the app is not running - -> Note: badges are not supported on all Android devices. See [our payload documentation](PAYLOAD.md#badges) for more details. - -### Parameters - -Parameter | Type | Default | Description ---------- | ---- | ------- | ----------- -`successHandler` | `Function` | | Is called when the api successfully sets the icon badge number. -`errorHandler` | `Function` | | Is called when the api encounters an error while trying to set the icon badge number. -`count` | `number` | | Indicates what number should show up in the badge. Passing 0 will clear the badge. Each `notification` event contains a `data.count` value which can be used to set the badge to correct number. - -### Example - -```javascript -push.setApplicationIconBadgeNumber(function() { - console.log('success'); -}, function() { - console.log('error'); -}, 2); -``` - -## push.getApplicationIconBadgeNumber(successHandler, errorHandler) - iOS only - -Get the current badge count visible when the app is not running - -### Parameters - -Parameter | Type | Default | Description ---------- | ---- | ------- | ----------- -`successHandler` | `Function` | | Is called when the api successfully retrieves the icon badge number. -`errorHandler` | `Function` | | Is called when the api encounters an error while trying to retrieve the icon badge number. - -### Callback parameters - -#### `successHandler` - -Parameter | Type | Description ---------- | ---- | ----------- -`n` | `number` | An integer which is the current badge count. - -### Example - -```javascript -push.getApplicationIconBadgeNumber(function(n) { - console.log('success', n); -}, function() { - console.log('error'); -}); -``` - -## push.finish(successHandler, errorHandler, id) - iOS only - -Tells the OS that you are done processing a background push notification. - -### Parameters - -Parameter | Type | Default | Description ---------- | ---- | ------- | ----------- -`successHandler` | `Function` | | Is called when the api successfully completes background push processing. -`errorHandler` | `Function` | | Is called when the api encounters an error while processing and completing the background push. -`id` | `String` | | Tells the OS which background process is complete. - -### Example - -```javascript -push.finish(function() { - console.log('success'); -}, function() { - console.log('error'); -}, 'push-1'); -``` - -## push.clearAllNotifications(successHandler, errorHandler) - iOS & Android only - -Tells the OS to clear all notifications from the Notification Center - -### Parameters - -Parameter | Type | Default | Description ---------- | ---- | ------- | ----------- -`successHandler` | `Function` | | Is called when the api successfully clears the notifications. -`errorHandler` | `Function` | | Is called when the api encounters an error when attempting to clears the notifications. - -### Example - -```javascript -push.clearAllNotifications(function() { - console.log('success'); -}, function() { - console.log('error'); -}); -``` diff --git a/StoneIsland/plugins/phonegap-plugin-push/docs/EXAMPLES.md b/StoneIsland/plugins/phonegap-plugin-push/docs/EXAMPLES.md deleted file mode 100644 index 8481e7bc..00000000 --- a/StoneIsland/plugins/phonegap-plugin-push/docs/EXAMPLES.md +++ /dev/null @@ -1,43 +0,0 @@ -# Creating a Project From a Template - -If you want to get started with a sample project you can create a new project from the example template. - -``` -phonegap create my-app --template phonegap-template-push -``` - -## Quick Example - -```javascript -var push = PushNotification.init({ - android: { - senderID: "12345679" - }, - browser: { - pushServiceURL: 'http://push.api.phonegap.com/v1/push' - }, - ios: { - alert: "true", - badge: "true", - sound: "true" - }, - windows: {} -}); - -push.on('registration', function(data) { - // data.registrationId -}); - -push.on('notification', function(data) { - // data.message, - // data.title, - // data.count, - // data.sound, - // data.image, - // data.additionalData -}); - -push.on('error', function(e) { - // e.message -}); -``` diff --git a/StoneIsland/plugins/phonegap-plugin-push/docs/INSTALLATION.md b/StoneIsland/plugins/phonegap-plugin-push/docs/INSTALLATION.md deleted file mode 100644 index 830bbdd7..00000000 --- a/StoneIsland/plugins/phonegap-plugin-push/docs/INSTALLATION.md +++ /dev/null @@ -1,313 +0,0 @@ -# Installation - -- [Installation Requirements](#installation-requirements) -- [Android details](#android-details) - - [Compilation](#compilation) - - [Co-existing with Facebook Plugin](#co-existing-with-facebook-plugin) - - [Common errors](#common-errors) - - [minSdkVersion === 14](#minsdkversion--14) - - [Multidex](#multidex) - - [More than one library with package name 'com.google.android.gms'](#more-than-one-library-with-package-name-comgoogleandroidgms) -- [Browser details](#browser-details) - - [Browser quirks](#browser-quirks) - - [Browser Support](#browser-support) -- [iOS details](#ios-details) - - [Xcode](#xcode) - - [Bitcode](#bitcode) - - [CocoaPods](#cocoapods) - - [Common CocoaPod Installation issues](#common-cocoapod-installation-issues) -- [Additional Resources](#additional-resources) - -## Installation Requirements - -Plugin version | Cordova CLI | Cordova Android | Cordova iOS | CocoaPods ----- | ---- | ---- | ---- | ---- -1.9.0 | 6.4.0 | 6.0.0 | 4.3.0 | 1.1.1 -1.8.0 | 3.6.3 | 4.0.0 | 4.1.0 | N/A - -To install from the command line: - -``` -phonegap plugin add phonegap-plugin-push --variable SENDER_ID="XXXXXXX" -``` -or - -``` -cordova plugin add phonegap-plugin-push --variable SENDER_ID="XXXXXXX" -``` - -It is also possible to install via repo url directly ( unstable ) - -``` -phonegap plugin add https://github.com/phonegap/phonegap-plugin-push --variable SENDER_ID="XXXXXXX" -``` - -or - -``` -cordova plugin add https://github.com/phonegap/phonegap-plugin-push --variable SENDER_ID="XXXXXXX" -``` - -Where the `XXXXXXX` in `SENDER_ID="XXXXXXX"` maps to the project number in the [Google Developer Console](https://www.google.ca/url?sa=t&rct=j&q=&esrc=s&source=web&cd=1&cad=rja&uact=8&ved=0ahUKEwikqt3nyPjMAhXJ5iYKHR0qDcsQFggbMAA&url=https%3A%2F%2Fconsole.developers.google.com%2F&usg=AFQjCNF0eH059mv86nMIlRmfsf42kde-wA&sig2=BQ2BJpchw1CpGt87sk5p6w&bvm=bv.122852650,d.eWE). To find the project number login to the Google Developer Console, select your project and click the menu item in the screen shot below to display your project number. - - - -If you are not creating an Android application you can put in anything for this value. - -> Note: if you are using Ionic you may need to specify the SENDER_ID variable in your package.json. - -``` - "cordovaPlugins": [ - { - "variables": { - "SENDER_ID": "XXXXXXX" - }, - "locator": "phonegap-plugin-push" - } - ] -``` - -> Note: You need to specify the SENDER_ID variable in your config.xml if you plan on installing/restoring plugins using the prepare method. The prepare method will skip installing the plugin otherwise. - -``` -<plugin name="phonegap-plugin-push" spec="1.6.0"> - <param name="SENDER_ID" value="XXXXXXX" /> -</plugin> -``` - -## Android details - -### Compilation - -As of version 1.3.0 the plugin has been switched to using Gradle/Maven for building. - -You will need to ensure that you have installed the following items through the Android SDK Manager: - -- Android Support Library version 23 or greater -- Local Maven repository for Support Libraries (formerly Android Support Repository) version 20 or greater -- Google Play Services version 27 or greater -- Google Repository version 22 or greater - - - -For more detailed instructions on how to install the Android Support Library visit [Google's documentation](https://developer.android.com/tools/support-library/setup.html). - -*Note:* if you are using an IDE to like Eclipse, Xamarin, etc. then the Android SDK installed by those tools may not be the same version as the one used by the Cordova/PhoneGap CLI while building. Please make sure your command line tooling is up to date with the software versions above. An easy way to make sure you up to date is to run the following command: - -``` -android update sdk --no-ui --filter "extra" -``` - -### Co-existing with Facebook Plugin - -There are a number of Cordova Facebook Plugins available but the one that we recommend is [Jeduan's fork](https://github.com/jeduan/cordova-plugin-facebook4) of the original Wizcorp plugin. It is setup to use Gradle/Maven and the latest Facebook SDK properly. - -To add to your app: - -``` -phonegap plugin add --save cordova-plugin-facebook4 --variable APP_ID="App ID" --variable APP_NAME="App Name" -``` -or - -``` -cordova plugin add --save cordova-plugin-facebook4 --variable APP_ID="App ID" --variable APP_NAME="App Name" -``` - -### Common errors - -#### minSdkVersion === 14 - -If you have an issue compiling the app and you are getting an error similar to this: - -``` -* What went wrong: -Execution failed for task ':processDebugManifest'. -> Manifest merger failed : uses-sdk:minSdkVersion 14 cannot be smaller than version 15 declared in library .../platforms/android/build/intermediates/exploded-aar/com.facebook.android/facebook-android-sdk/4.6.0/AndroidManifest.xml - Suggestion: use tools:overrideLibrary="com.facebook" to force usage -``` - -Then you can add the following entry into your config.xml file in the android platform tag: - -```xml -<platform name="android"> - <preference name="android-minSdkVersion" value="15"/> - </platform> -``` - -or compile your project using the following command, if the solution above doesn't work for you. Basically add `-- --minSdkVersion=15` to the end of the command line (mind the extra `--`, it's needed): - -```bash -cordova compile android -- --minSdkVersion=15 -cordova build android -- --minSdkVersion=15 -cordova run android -- --minSdkVersion=15 -cordova emulate android -- --minSdkVersion=15 -``` - -#### Multidex - -If you have an issue compiling the app and you're getting an error similar to this (`com.android.dex.DexException: Multiple dex files define`): - -``` -UNEXPECTED TOP-LEVEL EXCEPTION: -com.android.dex.DexException: Multiple dex files define Landroid/support/annotation/AnimRes; - at com.android.dx.merge.DexMerger.readSortableTypes(DexMerger.java:596) - at com.android.dx.merge.DexMerger.getSortedTypes(DexMerger.java:554) - at com.android.dx.merge.DexMerger.mergeClassDefs(DexMerger.java:535) - at com.android.dx.merge.DexMerger.mergeDexes(DexMerger.java:171) - at com.android.dx.merge.DexMerger.merge(DexMerger.java:189) - at com.android.dx.command.dexer.Main.mergeLibraryDexBuffers(Main.java:502) - at com.android.dx.command.dexer.Main.runMonoDex(Main.java:334) - at com.android.dx.command.dexer.Main.run(Main.java:277) - at com.android.dx.command.dexer.Main.main(Main.java:245) - at com.android.dx.command.Main.main(Main.java:106) -``` - -Then at least one other plugin you have installed is using an outdated way to declare dependencies such as `android-support` or `play-services-gcm`. -This causes gradle to fail, and you'll need to identify which plugin is causing it and request an update to the plugin author, so that it uses the proper way to declare dependencies for cordova. -See [this for the reference on the cordova plugin specification](https://cordova.apache.org/docs/en/5.4.0/plugin_ref/spec.html#link-18), it'll be usefull to mention it when creating an issue or requesting that plugin to be updated. - -Common plugins to suffer from this outdated dependency management are plugins related to *facebook*, *google+*, *notifications*, *crosswalk* and *google maps*. - -#### More than one library with package name 'com.google.android.gms' - -When some other packages include `cordova-google-play-services` as a dependency, such as is the case with the cordova-admob and cordova-plugin-analytics plugins, it is impossible to also add the phonegap-plugin-push, for the following error will rise during the build process: - -``` -:processDebugResources FAILED -FAILURE: Build failed with an exception. - -What went wrong: Execution failed for task ':processDebugResources'. > Error: more than one library with package name 'com.google.android.gms' -``` - -Those plugins should be using gradle to include the Google Play Services package but instead they include the play services jar directly or via a plugin dependency. So all of that is bad news. These plugins should be updated to use gradle. Please raise issues on those plugins as the change is not hard to make. - -In fact there is a PR open to do just that appfeel/analytics-google#11 for cordova-plugin-analytics. You should bug the team at appfeel to merge that PR. - -Alternatively, switch to another plugin that provides the same functionality but uses gradle: - -[https://github.com/danwilson/google-analytics-plugin](https://github.com/danwilson/google-analytics-plugin) -[https://github.com/cmackay/google-analytics-plugin](https://github.com/cmackay/google-analytics-plugin) - -## Browser details - -### Browser quirks - -For the time being push support on the browser will only work using the PhoneGap push server. - -When you run `phonegap serve` to test browser push point your browser at `http://localhost:3000`. The browser push implementation uses the W3C Push Spec's implementation which relies on ServiceWorkers and ServiceWorkers can only be accessed via the `https` protocol or via `http://localhost`. Pointing your browser at `localhost` will be the easiest way to test. - -### Browser Support - -Chrome 49+ -Firefox 46+ - -## iOS details - -### Xcode - -Xcode version 8.0 or greater is required for building this plugin. - -### Bitcode - -If you are running into a problem where the linker is complaining about bit code. For instance: - -``` -ld: '<file.o>' does not contain bitcode. You must rebuild it with bitcode enabled (Xcode setting ENABLE_BITCODE), obtain an updated library from the vendor, or disable bitcode for this target. for architecture arm64 clang: error: linker command failed with exit code 1 (use -v to see invocation) -``` - -You have two options. The first is to [disable bitcode as per this StackOverflow answer](http://stackoverflow.com/a/32466484/41679) or [upgrade to cordova-ios 4 or greater](https://cordova.apache.org/announcements/2015/12/08/cordova-ios-4.0.0.html). - -``` -cordova platform update ios@4.0.0 -``` - -### CocoaPods - -Required `cordova-cli` version: `6.4.0` - -Required `cordova-ios` version: `4.3.0` - -Version `1.9.0` (and above) of this plugin supports [CocoaPods](https://cocoapods.org) installation of the [Google Cloud Messaging](https://cocoapods.org/pods/GoogleCloudMessaging) library. - -If you are installing this plugin using `npm`, and you are using version `6.1.0` or greater of the `cordova-cli`, it will automatically download the right version of this plugin for both your platform and cli. - -If you are on a `cordova-cli` version less than `6.1.0`, you will either have to upgrade your `cordova-cli` version, or install the plugin explicitly: - -i.e. -``` -cordova plugin add phonegap-plugin-push@1.8.1 -``` - -If you are installing this plugin using a `local file reference` or a `git url`, you will have to specify the version of this plugin explicitly (see above) if you don't fulfill the `cordova-cli` and `cordova-ios` requirements. - -#### Common CocoaPod Installation issues - -If you are attempting to install this plugin and you run into this error: - -``` -Installing "phonegap-plugin-push" for ios -Failed to install 'phonegap-plugin-push':Error: pod: Command failed with exit code 1 - at ChildProcess.whenDone (/Users/smacdona/code/push151/platforms/ios/cordova/node_modules/cordova-common/src/superspawn.js:169:23) - at emitTwo (events.js:87:13) - at ChildProcess.emit (events.js:172:7) - at maybeClose (internal/child_process.js:818:16) - at Process.ChildProcess._handle.onexit (internal/child_process.js:211:5) -Error: pod: Command failed with exit code 1 -``` - -Please run the command `pod repo update` and re-install the plugin. - -## Additional Resources - -The push plugin enables you to play sounds and display different icons during push (Android only). These additional resources need to be added to your projects `platforms` directory in order for them to be included into your final application binary. One way of doing it is to create a hook to do the copying for you on each build. - -First create a `scripts` directory in the root of your project. Next add a file to the scripts directory called `copy_resource_files.js`. The contents of the file will look something like this: - -```javascript -#!/usr/bin/env node - -// each object in the array consists of a key which refers to the source and -// the value which is the destination. -var filestocopy = [{ - "resources/android/images/logo.png": - "platforms/android/res/drawable/logo.png" -}, { - "resources/android/sounds/ring.mp3": - "platforms/android/res/raw/ring.mp3" -}, { - "resources/ios/sounds/ring.caf": - "platforms/ios/YourAppName/ring.caf" -}, ]; - -var fs = require('fs'); -var path = require('path'); - -// no need to configure below -var rootdir = process.argv[2]; - -filestocopy.forEach(function(obj) { - Object.keys(obj).forEach(function(key) { - var val = obj[key]; - var srcfile = path.join(rootdir, key); - var destfile = path.join(rootdir, val); - //console.log("copying "+srcfile+" to "+destfile); - var destdir = path.dirname(destfile); - if (fs.existsSync(srcfile) && fs.existsSync(destdir)) { - fs.createReadStream(srcfile).pipe( - fs.createWriteStream(destfile)); - } - }); -}); -``` - -Obviously, you'll need to modify the `filestocopy` variable to suit your needs. Pay attention to the destination path on iOS where you will need to replace `YourAppName`. - -Next open up your `config.xml` file and add the following line: - -```xml -<hook type="before_build" src="scripts/copy_resource_files.js" /> -``` - -Now, when you build your app the files will get copied into your platforms directory for you. - -If you are using PhoneGap Build check out these instructions on [Additional Resources](PHONEGAP_BUILD.md#additional-resources) diff --git a/StoneIsland/plugins/phonegap-plugin-push/docs/ISSUES.md b/StoneIsland/plugins/phonegap-plugin-push/docs/ISSUES.md deleted file mode 100644 index 3b3021af..00000000 --- a/StoneIsland/plugins/phonegap-plugin-push/docs/ISSUES.md +++ /dev/null @@ -1,80 +0,0 @@ -# ISSUES - -- [Read the docs](#read-the-docs) -- [Search the issues](#search-the-issues) -- [Opening a new issue](#opening-a-new-issue) - - [Provide details](#provide-details) - - [An example issue](#an-example-issue) -- [Voting on an issue](#voting-on-an-issue) - -The following tips are for users of this plugin who want to get help. - -## Read the docs - -I'll be the first to admit that the docs are not perfect but start here at the [README](https://github.com/phonegap/phonegap-plugin-push/blob/master/README.md) to see if your problem is documented. If it isn't continue on but if you do get an answer then consider sending a documentation pull request. - -## Search the issues - -Your question may have already been answered. Make sure you search at least the repo's [issues](https://github.com/phonegap/phonegap-plugin-push/issues) before you create a new one. - -## Opening a new issue - -If you have searched the issues and haven't found anything that resembles your problem then follow these guidelines in creating a new issue. - -### Provide details - -Give as many details as possible. Issues without many details will be more difficult to debug and will encounter delays. - -Select a concise, informative title for the issue. Here's a good article on writing [subject lines](https://www.nngroup.com/articles/microcontent-how-to-write-headlines-page-titles-and-subject-lines/). - -Include the following at a minimum: -_ what version number of plugin are you using? -- which platform and version you are testing on? iOS 9.0, Android 5.0, etc. -- a detailed description of your problem. Including: - - steps to reproduce - - expected result - - actual result -- how you are sending the push data to the device, including an example payload - -You may also want to include: -- some sample code that illustrates the problem. -- logs taken while the problem was reproduced. -- screenshots! - -If the code or logs are huge, let's say over 20 lines please think about using a web service like [Gist](https://gist.github.com/) or [Pastebin](http://pastebin.com/). - -### An example issue - -**The wrong way** - -*Title:* This plugin does not work for me - -*Details:* Please fix quickly as my business depends on this plugin. - -**The right way** - -*Title:* Registration event never received on Samsung Galaxy S running Android 2.3 - -*Details:* I'm using version 1.5.2 of this plugin on my Samsung Galaxy S5 device which runs Android 4.4. I never receiving the `registration` event in my application when I expect it to return a value I can send to my push service. - -You can see the code I'm using in this gist: [https://gist.github.com/macdonst/191f74ac75b6802c047d](https://gist.github.com/macdonst/191f74ac75b6802c047d) - -And an output of the logs when trying to run the app are in this gist: [https://gist.github.com/macdonst/47549150c299080c455c](https://gist.github.com/macdonst/47549150c299080c455c) - -Please point me in the right direction. - -*Response:* - -Thanks for the detailed logs and example code by looking them over I'm sure of what your problem is. If you look at line [334](https://gist.github.com/macdonst/47549150c299080c455c#file-logcat-txt-L334) of your logcat you will see that it complains that: - -``` -I/chromium(11669): [INFO:CONSOLE(54)] "Uncaught ReferenceError: PushNotification is not defined", source: file:///android_asset/www/js/index.js (54) -``` - -This leads me to line [4](https://gist.github.com/macdonst/191f74ac75b6802c047d#file-app-js-L4) of your code where you are initializing push before you get the `deviceready` event. Like all Cordova API's you have to wait until you receive the `deviceready` event before you initialize Push. - -Check out [https://github.com/phonegap/phonegap-plugin-push/blob/20f489a90cf519f962fd957700f92115f142594b/example/www/js/index.js](https://github.com/phonegap/phonegap-plugin-push/blob/20f489a90cf519f962fd957700f92115f142594b/example/www/js/index.js) for an example of how to wait for `deviceready`. - -## Voting on an issue - -Did you know you can vote on issues in the phonegap-plugin-push repository? If you install the [ZenHub](https://chrome.google.com/webstore/detail/zenhub-for-github/ogcgkffhplmphkaahpmffcafajaocjbd) Chrome Extension you will be able to +1 issues to indicate how popular they are to the community. It's a way better way for the contributors to keep track of important issues. diff --git a/StoneIsland/plugins/phonegap-plugin-push/docs/PAYLOAD.md b/StoneIsland/plugins/phonegap-plugin-push/docs/PAYLOAD.md deleted file mode 100644 index b446612e..00000000 --- a/StoneIsland/plugins/phonegap-plugin-push/docs/PAYLOAD.md +++ /dev/null @@ -1,1400 +0,0 @@ -- [Overview](#overview) - - [Foreground Events](#push-message-arrives-with-app-in-foreground) - - [Background Events](#push-message-arrives-with-app-in-background) - - [Tap Events](#user-clicks-on-notification-in-notification-center) -- [Android Behaviour](#android-behaviour) - - [Localization](#localization) - - [Images](#images) - - [Sound](#sound) - - [Stacking](#stacking) - - [Inbox Stacking](#inbox-stacking) - - [Action Buttons](#action-buttons) - - [In Line Replies](#in-line-replies) - - [Led in Notifications](#led-in-notifications) - - [Vibration Pattern in Notifications](#vibration-pattern-in-notifications) - - [Priority in Notifications](#priority-in-notifications) - - [Picture Messages](#picture-messages) - - [Background Notifications](#background-notifications) - - [Use of content-available: true](#use-of-content-available-true) - - [Huawei and Xiaomi Phones](#huawei-and-xiaomi-phones) - - [Application force closed](#application-force-closed) - - [Visibility](#visibility-of-notifications) - - [Badges](#badges) - - [Support for Twilio Notify](#support-for-twilio-notify) -- [iOS Behaviour](#ios-behaviour) - - [Sound](#sound-1) - - [Background Notifications](#background-notifications-1) - - [Action Buttons](#action-buttons-1) - - [Action Buttons using GCM on iOS](#action-buttons-using-gcm-on-ios) - - [GCM and Additional Data](#gcm-and-additional-data) -- [Windows Behaviour](#windows-behaviour) - - [Notifications](#notifications) - - [Setting Toast Capable Option for Windows](#setting-toast-capable-option-for-windows) - - [Disabling the default processing of notifications by Windows](#disabling-the-default-processing-of-notifications-by-windows) - - [Background Notifications](#background-notifications-2) - - -# Overview - -The following flowchart attempts to give you a picture of what happens when a push message arrives on your device when you have an app using phonegap-plugin-push. - - - -## Push message arrives with app in foreground - -- The push plugin receives the data from the remote push service and calls all of your `notification` event handlers. -- The message is *not* displayed in the devices notification center as that is not normal behaviour for Android or iOS. - -## Push message arrives with app in background - -- The push plugin receives the data from the remote push service and checks to see if there is a title or message in the data received. If there is then the message will be displayed in the devices notification center. -- Then the push plugin checks to see if the app is running. If the user has killed the application then no further processing of the push data will occur. -- If the app is running in the background the push plugin then checks to see if `content-available` exists in the push data. -- If `content-available` is set to `1` then the plugin calls all of your `notification` event handlers. - -## User clicks on notification in notification center - -- The app starts. -- Then the plugin calls all of your `notification` event handlers. - -> Note: if the push payload contained `content-available: 1` then your `notification` event handler has already been called. It is up to you to handle the double event. - -Some ways to handle this *double* event are: - -- don't include title/message in the push so it doesn't show up in the shader. -- send two pushes, one to be processed in the background the other to show up in the shade. -- include a unique ID in your push so you can check to see if you've already processed this event. - -# Android Behaviour - -## Localization - -Plugin supported localization from resources for: title, message and summaryText. - -You may use simple link to locale constant. - -```javascript -{ - "registration_ids": ["my device id"], - "data": { - "title": {"locKey": "push_app_title"}, - "message": "Simple non-localizable text for message!" - } -} -``` - -Or use localization with formatted constants. - -```javascript -{ - "registration_ids": ["my device id"], - "data": { - "title": {"locKey": "push_app_title"}, - "message": {"locKey": "push_message_fox", "locData": ["fox", "dog"]} - } -} -``` - -Here is an example using node-gcm that sends the above JSON: - -```javascript -var gcm = require('node-gcm'); -// Replace these with your own values. -var apiKey = "replace with API key"; -var deviceID = "my device id"; -var service = new gcm.Sender(apiKey); -var message = new gcm.Message(); -message.addData('title', {"locKey": "push_app_title"}); -message.addData('message', 'Simple non-localizable text for message!'); -// Constant with formatted params -// message.addData('message', {"locKey": "push_message_fox", "locData": ["fox", "dog"]}); -service.send(message, { registrationTokens: [ deviceID ] }, function (err, response) { - if(err) console.error(err); - else console.log(response); -}); -``` - -Localization must store in strings.xml - -```xml -<string name="push_app_title">@string/app_name</string> -<string name="push_message_fox">The quick brown %1$s jumps over the lazy %2$s</string> -<string name="push_summary_text">%%n%% new message(s)</string> -``` - -## Images - -By default the icon displayed in your push notification will be your apps icon. So when you initialize the plugin like this: - -```javascript -var push = PushNotification.init({ - "android": { - "senderID": "12345679" - }, - browser: { - pushServiceURL: 'http://push.api.phonegap.com/v1/push' - }, - "ios": { - "alert": "true", - "badge": "true", - "sound": "true" - }, - "windows": {} -}); -``` - -The result will look much like this: - - - -This is because Android now uses Material design and the default icon for push will be completely white. - -In order to get a better user experience you can specify an alternate icon and background color to be shown when receiving a push notification. The code would look like this: - -```javascript -var push = PushNotification.init({ - "android": { - "senderID": "123456789", - "icon": "phonegap", - "iconColor": "blue" - }, - browser: { - pushServiceURL: 'http://push.api.phonegap.com/v1/push' - }, - "ios": { - "alert": "true", - "badge": "true", - "sound": "true" - }, - "windows": {} -}); -``` - -Where *icon* is the name of an image in the Android *drawables* folder. Writing a hook to describe how to copy an image to the Android *drawables* folder is out of scope for this README but there is an [excellent tutorial](http://devgirl.org/2013/11/12/three-hooks-your-cordovaphonegap-project-needs/) that you can copy. - -*iconColor* is one of the supported formats #RRGGBB or #AARRGGBB or one of the following names: 'red', 'blue', 'green', 'black', 'white', 'gray', 'cyan', 'magenta', 'yellow', 'lightgray', 'darkgray', 'grey', 'lightgrey', 'darkgrey', 'aqua', 'fuchsia', 'lime', 'maroon', 'navy', 'olive', 'purple', 'silver', 'teal'. *iconColor* is supported on Android 5.0 and greater. - -Please follow the [Android icon design guidelines](https://www.google.com/design/spec/style/icons.html#) when creating your icon. - - - -Additionally, each push can include a large icon which is used to personalize each push. The location of the image may one of three types. - -The first is the *drawables* folder in your app. This JSON sent from GCM: - -```javascript -{ - "registration_ids": ["my device id"], - "data": { - "title": "Large Icon", - "message": "Loaded from drawables folder", - "image": "twitter" - } -} -``` - -Here is an example using node-gcm that sends the above JSON: - -```javascript -var gcm = require('node-gcm'); -// Replace these with your own values. -var apiKey = "replace with API key"; -var deviceID = "my device id"; -var service = new gcm.Sender(apiKey); -var message = new gcm.Message(); -message.addData('title', 'Large Icon'); -message.addData('message', 'Loaded from drawables folder.'); -message.addData('image', 'twitter'); -service.send(message, { registrationTokens: [ deviceID ] }, function (err, response) { - if(err) console.error(err); - else console.log(response); -}); -``` - -Would look for the *twitter* image in the drawables folder and produce the following notification. - - - -The second is the *assets* folder in your app. This JSON sent from GCM: - -```javascript -{ - "registration_ids": ["my device id"], - "data": { - "title": "Large Icon", - "message": "Loaded from assets folder", - "image": "www/image/logo.png" - } -} -``` - -Here is an example using node-gcm that sends the above JSON: - -```javascript -var gcm = require('node-gcm'); -// Replace these with your own values. -var apiKey = "replace with API key"; -var deviceID = "my device id"; -var service = new gcm.Sender(apiKey); -var message = new gcm.Message(); -message.addData('title', 'Large Icon'); -message.addData('message', 'Loaded from assets folder.'); -message.addData('image', 'www/image/logo.png'); -service.send(message, { registrationTokens: [ deviceID ] }, function (err, response) { - if(err) console.error(err); - else console.log(response); -}); -``` - -Would look for the *logo.png* file in the assets/www/img folder. Since your apps www folder gets copied into the Android assets folder it is an excellent spot to store the images without needing to write a hook to copy them to the *drawables* folder. It produces the following notification. - - - - -The third is the remote *URL*. This JSON sent from GCM: - -```javascript -{ - "registration_ids": ["my device id"], - "data": { - "title": "Large Icon", - "message": "Loaded from URL", - "image": "https://dl.dropboxusercontent.com/u/887989/antshot.png" - } -} -``` - -Here is an example using node-gcm that sends the above JSON: - -```javascript -var gcm = require('node-gcm'); -// Replace these with your own values. -var apiKey = "replace with API key"; -var deviceID = "my device id"; -var service = new gcm.Sender(apiKey); -var message = new gcm.Message(); -message.addData('title', 'Large Icon'); -message.addData('message', 'Loaded from URL'); -message.addData('image', 'https://dl.dropboxusercontent.com/u/887989/antshot.png'); -service.send(message, { registrationTokens: [ deviceID ] }, function (err, response) { - if(err) console.error(err); - else console.log(response); -}); -``` - -Produces the following notification. - - - -## Sound - -For Android there are three special values for sound you can use. The first is `default` which will play the phones default notification sound. - -```javascript -{ - "registration_ids": ["my device id"], - "data": { - "title": "Default", - "message": "Plays default notification sound", - "soundname": "default" - } -} -``` - -Then second is `ringtone` which will play the phones default ringtone sound. - -```javascript -{ - "registration_ids": ["my device id"], - "data": { - "title": "Ringtone", - "message": "Plays default ringtone sound", - "soundname": "ringtone" - } -} -``` -The third is the empty string which will cause for the playing of sound to be skipped. - -```javascript -{ - "registration_ids": ["my device id"], - "data": { - "title": "Silece", - "message": "Skips playing any sound", - "soundname": "" - } -} -``` - -In order for your your notification to play a custom sound you will need to add the files to your Android project's `res/raw` directory. Then send the follow JSON from GCM: - -```javascript -{ - "registration_ids": ["my device id"], - "data": { - "title": "Sound Test", - "message": "Loaded res/raw", - "soundname": "test" - } -} -``` - -Here is an example using node-gcm that sends the above JSON: - -```javascript -var gcm = require('node-gcm'); -// Replace these with your own values. -var apiKey = "replace with API key"; -var deviceID = "my device id"; -var service = new gcm.Sender(apiKey); -var message = new gcm.Message(); -message.addData('title', 'Sound Test'); -message.addData('message', 'Loaded res/raw'); -message.addData('soundname', 'test'); -service.send(message, { registrationTokens: [ deviceID ] }, function (err, response) { - if(err) console.error(err); - else console.log(response); -}); -``` - -*Note:* when you specify the custom sound file name omit the file's extension. - -## Stacking - -By default when using this plugin on Android each notification that your app receives will replace the previous notification in the shade. - -If you want to see multiple notifications in the shade you will need to provide a notification ID as part of the push data sent to the app. For instance if you send: - -```javascript -{ - "registration_ids": ["my device id"], - "data": { - "title": "Test Push", - "message": "Push number 1" - } -} -``` - -Here is an example using node-gcm that sends the above JSON: - -```javascript -var gcm = require('node-gcm'); -// Replace these with your own values. -var apiKey = "replace with API key"; -var deviceID = "my device id"; -var service = new gcm.Sender(apiKey); -var message = new gcm.Message(); -message.addData('title', 'Test Push'); -message.addData('message', 'Push number 1'); -service.send(message, { registrationTokens: [ deviceID ] }, function (err, response) { - if(err) console.error(err); - else console.log(response); -}); -``` - -Followed by: - -```javascript -{ - "registration_ids": ["my device id"], - "data": { - "title": "Test Push", - "message": "Push number 2" - } -} -``` - -Here is an example using node-gcm that sends the above JSON: - -```javascript -var gcm = require('node-gcm'); -// Replace these with your own values. -var apiKey = "replace with API key"; -var deviceID = "my device id"; -var service = new gcm.Sender(apiKey); -var message = new gcm.Message(); -message.addData('title', 'Test Push'); -message.addData('message', 'Push number 2'); -service.send(message, { registrationTokens: [ deviceID ] }, function (err, response) { - if(err) console.error(err); - else console.log(response); -}); -``` - -You will only see "Push number 2" in the shade. However, if you send: - -```javascript -{ - "registration_ids": ["my device id"], - "data": { - "title": "Test Push", - "message": "Push number 1", - "notId": 1 - } -} -``` - -Here is an example using node-gcm that sends the above JSON: - -```javascript -var gcm = require('node-gcm'); -// Replace these with your own values. -var apiKey = "replace with API key"; -var deviceID = "my device id"; -var service = new gcm.Sender(apiKey); -var message = new gcm.Message(); -message.addData('title', 'Test Push'); -message.addData('message', 'Push number 1'); -message.addData('notId', 1); -service.send(message, { registrationTokens: [ deviceID ] }, function (err, response) { - if(err) console.error(err); - else console.log(response); -}); -``` - -and: - -```javascript -{ - "registration_ids": ["my device id"], - "data": { - "title": "Test Push", - "message": "Push number 2", - "notId": 2 - } -} -``` - -Here is an example using node-gcm that sends the above JSON: - -```javascript -var gcm = require('node-gcm'); -// Replace these with your own values. -var apiKey = "replace with API key"; -var deviceID = "my device id"; -var service = new gcm.Sender(apiKey); -var message = new gcm.Message(); -message.addData('title', 'Test Push'); -message.addData('message', 'Push number 2'); -message.addData('notId', 2); -service.send(message, { registrationTokens: [ deviceID ] }, function (err, response) { - if(err) console.error(err); - else console.log(response); -}); -``` - -You will see both "Push number 1" and "Push number 2" in the shade. - -## Inbox Stacking - -A better alternative to stacking your notifications is to use the inbox style to have up to 8 lines of notification text in a single notification. If you send the following JSON from GCM you will see: - -```javascript -{ - "registration_ids": ["my device id"], - "data": { - "title": "My Title", - "message": "My first message", - "style": "inbox", - "summaryText": "There are %n% notifications" - } -} -``` - -Here is an example using node-gcm that sends the above JSON: - -```javascript -var gcm = require('node-gcm'); -// Replace these with your own values. -var apiKey = "replace with API key"; -var deviceID = "my device id"; -var service = new gcm.Sender(apiKey); -var message = new gcm.Message(); -message.addData('title', 'My Title'); -message.addData('message', 'My first message'); -message.addData('style', 'inbox'); -message.addData('summaryText', 'There are %n% notifications'); -service.send(message, { registrationTokens: [ deviceID ] }, function (err, response) { - if(err) console.error(err); - else console.log(response); -}); -``` - -It will produce a normal looking notification: - - - -But, if you follow it up with subsequent notifications like: - -```javascript -{ - "registration_ids": ["my device id"], - "data": { - "title": "My Title", - "message": "My second message", - "style": "inbox", - "summaryText": "There are %n% notifications" - } -} -``` - -Here is an example using node-gcm that sends the above JSON: - -```javascript -var gcm = require('node-gcm'); -// Replace these with your own values. -var apiKey = "replace with API key"; -var deviceID = "my device id"; -var service = new gcm.Sender(apiKey); -var message = new gcm.Message(); -message.addData('title', 'My Title'); -message.addData('message', 'My second message'); -message.addData('style', 'inbox'); -message.addData('summaryText', 'There are %n% notifications'); -service.send(message, { registrationTokens: [ deviceID ] }, function (err, response) { - if(err) console.error(err); - else console.log(response); -}); -``` - -You will get an inbox view so you can display multiple notifications in a single panel. - - - -If you use `%n%` in the `summaryText` of the JSON coming down from GCM it will be replaced by the number of messages that are currently in the queue. - -## Action Buttons - -Your notification can include a maximum of three action buttons. If you wish to include an icon along with the button name they must be placed in the `res/drawable` directory of your Android project. Then you can send the following JSON from GCM: - -```javascript -{ - "registration_ids": ["my device id"], - "data": { - "title": "AUX Scrum", - "message": "Scrum: Daily touchbase @ 10am Please be on time so we can cover everything on the agenda.", - "actions": [ - { "icon": "emailGuests", "title": "EMAIL GUESTS", "callback": "app.emailGuests", "foreground": true}, - { "icon": "snooze", "title": "SNOOZE", "callback": "app.snooze", "foreground": false} - ] - } -} -``` - -Here is an example using node-gcm that sends the above JSON: - -```javascript -var gcm = require('node-gcm'); -// Replace these with your own values. -var apiKey = "replace with API key"; -var deviceID = "my device id"; -var service = new gcm.Sender(apiKey); -var message = new gcm.Message(); -message.addData('title', 'AUX Scrum'); -message.addData('message', 'Scrum: Daily touchbase @ 10am Please be on time so we can cover everything on the agenda.'); -message.addData('actions', [ - { "icon": "emailGuests", "title": "EMAIL GUESTS", "callback": "app.emailGuests", "foreground": true}, - { "icon": "snooze", "title": "SNOOZE", "callback": "app.snooze", "foreground": false}, -]); -service.send(message, { registrationTokens: [ deviceID ] }, function (err, response) { - if(err) console.error(err); - else console.log(response); -}); -``` - -This will produce the following notification in your tray: - - - -If your user clicks on the main body of the notification your app will be opened. However if they click on either of the action buttons the app will open (or start) and the specified JavaScript callback will be executed if there is a function defined, and if there isn't an event will be emitted with the callback name. In this case it is `app.emailGuests` and `app.snooze` respectively. If you set the `foreground` property to `true` the app will be brought to the front, if `foreground` is `false` then the callback is run without the app being brought to the foreground. - -### In Line Replies - -Android N introduces a new capability for push notifications, the in line reply text field. If you wish to get some text data from the user when the action button is called send the following type of payload: - -Your notification can include action buttons. If you wish to include an icon along with the button name they must be placed in the `res/drawable` directory of your Android project. Then you can send the following JSON from GCM: - -```javascript -{ - "registration_ids": ["my device id"], - "data": { - "title": "AUX Scrum", - "message": "Scrum: Daily touchbase @ 10am Please be on time so we can cover everything on the agenda.", - "actions": [ - { "icon": "emailGuests", "title": "EMAIL GUESTS", "callback": "app.emailGuests", "foreground": false, "inline": true }, - { "icon": "snooze", "title": "SNOOZE", "callback": "app.snooze", "foreground": false} - ] - } -} -``` - -Here is an example using node-gcm that sends the above JSON: - -```javascript -var gcm = require('node-gcm'); -// Replace these with your own values. -var apiKey = "replace with API key"; -var deviceID = "my device id"; -var service = new gcm.Sender(apiKey); -var message = new gcm.Message(); -message.addData('title', 'AUX Scrum'); -message.addData('message', 'Scrum: Daily touchbase @ 10am Please be on time so we can cover everything on the agenda.'); -message.addData('actions', [ - { "icon": "emailGuests", "title": "EMAIL GUESTS", "callback": "app.emailGuests", "foreground": false, "inline": true}, - { "icon": "snooze", "title": "SNOOZE", "callback": "app.snooze", "foreground": false}, -]); -service.send(message, { registrationTokens: [ deviceID ] }, function (err, response) { - if(err) console.error(err); - else console.log(response); -}); -``` - -On Android N and greater when the user clicks on the Email Guests button they will see the following: - - - -Then your app's `on('notification')` event handler will be called without the app being brought to the foreground and the event data would be: - -``` -{ - "title": "AUX Scrum", - "message": "Scrum: Daily touchbase @ 10am Please be on time so we can cover everything on the agenda.", - "additionalData": { - "inlineReply": "Sounds good", - "actions": [ - { - "inline": true, - "callback": "app.accept", - "foreground": false, - "title": "Accept" - }, - { - "icon": "snooze", - "callback": "app.reject", - "foreground": false, - "title": "Reject" - } - ], - "actionCallback": "app.accept", - "coldstart": false, - "collapse_key": "do_not_collapse", - "foreground": false - } -} -``` - -and the text data that the user typed would be located in `data.additionalData.inlineReply`. - -**Note:** On Android M and earlier the above in line behavior is not supported. As a fallback when `inline` is set to `true` the `foreground` setting will be changed to the default `true` setting. This allows your app to be launched from a closed state into the foreground where any behavior desired as a result of the user selecting the in line reply action button can be handled through the associated `callback`. - -#### Attributes - -Attribute | Type | Default | Description ---------- | ---- | ------- | ----------- -`icon` | `string` | | Optional. The name of a drawable resource to use as the small-icon. The name should not include the extension. -`title` | `string` | | Required. The label to display for the action button. -`callback` | `string` | | Required. The function to be executed or the event to be emitted when the action button is pressed. The function must be accessible from the global namespace. If you provide `myCallback` then it amounts to calling `window.myCallback`. If you provide `app.myCallback` then there needs to be an object call `app`, with a function called `myCallback` accessible from the global namespace, i.e. `window.app.myCallback`. If there isn't a function with the specified name an event will be emitted with the callback name. -`foreground` | `boolean` | `true` | Optional. Whether or not to bring the app to the foreground when the action button is pressed. -`inline` | `boolean` | `false` | Optional. Whether or not to provide a quick reply text field to the user when the button is clicked. - -## Led in Notifications - -You can use a Led notifcation and choose the color of it. Just add a `ledColor` field in your notification in the ARGB format array: - -```javascript -{ - "registration_ids": ["my device id"], - "data": { - "title": "Green LED", - "message": "This is my message with a Green LED", - "ledColor": [0, 0, 255, 0] - } -} -``` - -Here is an example using node-gcm that sends the above JSON: - -```javascript -var gcm = require('node-gcm'); -// Replace these with your own values. -var apiKey = "replace with API key"; -var deviceID = "my device id"; -var service = new gcm.Sender(apiKey); -var message = new gcm.Message(); -message.addData('title', 'Green LED'); -message.addData('message', 'This is my message with a Green LED'); -message.addData('ledColor', [0, 0, 255, 0]); -service.send(message, { registrationTokens: [ deviceID ] }, function (err, response) { - if(err) console.error(err); - else console.log(response); -}); -``` - -## Vibration Pattern in Notifications - -You can set a Vibration Pattern for your notifications. Just add a `vibrationPattern` field in your notification: - -```javascript -{ - "registration_ids": ["my device id"], - "data": { - "title": "Vibration Pattern", - "message": "Device should wait for 2 seconds, vibrate for 1 second then be silent for 500 ms then vibrate for 500 ms", - "vibrationPattern": [2000, 1000, 500, 500] - } -} -``` - -Here is an example using node-gcm that sends the above JSON: - -```javascript -var gcm = require('node-gcm'); -// Replace these with your own values. -var apiKey = "replace with API key"; -var deviceID = "my device id"; -var service = new gcm.Sender(apiKey); -var message = new gcm.Message(); -message.addData('title', 'Vibration Pattern'); -message.addData('message', 'Device should wait for 2 seconds, vibrate for 1 second then be silent for 500 ms then vibrate for 500 ms'); -message.addData('vibrationPattern', [2000, 1000, 500, 500]); -service.send(message, { registrationTokens: [ deviceID ] }, function (err, response) { - if(err) console.error(err); - else console.log(response); -}); -``` - -## Priority in Notifications - -You can set a priority parameter for your notifications. This priority value determines where the push notification will be put in the notification shade. Low-priority notifications may be hidden from the user in certain situations, while the user might be interrupted for a higher-priority notification. Add a `priority` field in your notification. -2: minimum, -1: low, 0: default , 1: high, 2: maximum priority. - -```javascript -{ - "registration_ids": ["my device id"], - "data": { - "title": "This is a maximum priority Notification", - "message": "This notification should appear in front of all others", - "priority": 2 - } -} -``` - -Here is an example using node-gcm that sends the above JSON: - -```javascript -var gcm = require('node-gcm'); -// Replace these with your own values. -var apiKey = "replace with API key"; -var deviceID = "my device id"; -var service = new gcm.Sender(apiKey); -var message = new gcm.Message(); -message.addData('title', 'This is a maximum priority Notification'); -message.addData('message', 'This notification should appear in front of all others'); -message.addData('priority', 2); -service.send(message, { registrationTokens: [ deviceID ] }, function (err, response) { - if(err) console.error(err); - else console.log(response); -}); -``` - -Do not confuse this with the GCM option of setting the [delivery priority of the message](https://developers.google.com/cloud-messaging/concept-options#setting-the-priority-of-a-message). Which is used by GCM to tell the device whether or not it should wake up to deal with the message. - -## Picture Messages - -Perhaps you want to include a large picture in the notification that you are sending to your users. Luckily you can do that too by sending the following JSON from GCM. - -```javascript -{ - "registration_ids": ["my device id"], - "data": { - "title": "Big Picture", - "message": "This is my big picture message", - "style": "picture", - "picture": "http://36.media.tumblr.com/c066cc2238103856c9ac506faa6f3bc2/tumblr_nmstmqtuo81tssmyno1_1280.jpg", - "summaryText": "The internet is built on cat pictures" - } -} -``` - -Here is an example using node-gcm that sends the above JSON: - -```javascript -var gcm = require('node-gcm'); -// Replace these with your own values. -var apiKey = "replace with API key"; -var deviceID = "my device id"; -var service = new gcm.Sender(apiKey); -var message = new gcm.Message(); -message.addData('title', 'Big Picture'); -message.addData('message', 'This is my big picture message'); -message.addData('style', 'picture'); -message.addData('picture', 'http://36.media.tumblr.com/c066cc2238103856c9ac506faa6f3bc2/tumblr_nmstmqtuo81tssmyno1_1280.jpg'); -message.addData('summaryText', 'The internet is built on cat pictures'); -service.send(message, { registrationTokens: [ deviceID ] }, function (err, response) { - if(err) console.error(err); - else console.log(response); -}); -``` - -This will produce the following notification in your tray: - - - -> Note: When the notification arrives you will see the title and message like normally. You will only see the picture when the notification is expanded. Once expanded not only will you see the picture but the message portion will disappear and you'll see the summary text portion. - -## Background Notifications - -On Android if you want your `on('notification')` event handler to be called when your app is in the background it is relatively simple. - -First the JSON you send from GCM will need to include `"content-available": "1"`. This will tell the push plugin to call your `on('notification')` event handler no matter what other data is in the push notification. - -```javascript -{ - "registration_ids": ["my device id"], - "data": { - "title": "Test Push", - "message": "Push number 1", - "info": "super secret info", - "content-available": "1" - } -} -``` - -Here is an example using node-gcm that sends the above JSON: - -```javascript -var gcm = require('node-gcm'); -// Replace these with your own values. -var apiKey = "replace with API key"; -var deviceID = "my device id"; -var service = new gcm.Sender(apiKey); -var message = new gcm.Message(); -message.addData('title', 'Test Push'); -message.addData('message', 'Push number 1'); -message.addData('info', 'super secret info'); -message.addData('content-available', '1'); -service.send(message, { registrationTokens: [ deviceID ] }, function (err, response) { - if(err) console.error(err); - else console.log(response); -}); -``` - -or if you want the payload to be delivered directly to your app without anything showing up in the notification center omit the tite/message from the payload like so: - - -```javascript -{ - "registration_ids": ["my device id"], - "data": { - "info": "super secret info", - "content-available": "1" - } -} -``` - -Here is an example using node-gcm that sends the above JSON: - -```javascript -var gcm = require('node-gcm'); -// Replace these with your own values. -var apiKey = "replace with API key"; -var deviceID = "my device id"; -var service = new gcm.Sender(apiKey); -var message = new gcm.Message(); -message.addData('info', 'super secret info'); -message.addData('content-available', '1'); -service.send(message, { registrationTokens: [ deviceID ] }, function (err, response) { - if(err) console.error(err); - else console.log(response); -}); -``` - -If do not want this type of behaviour just omit `"content-available": 1` from your push data and your `on('notification')` event handler will not be called. - -### Use of content-available: true - -The GCM docs will tell you to send a data payload of: - -```javascript -{ - "registration_ids": ["my device id"], - "content_available": true, - "data": { - "title": "Test Push", - "message": "Push number 1", - "info": "super secret info", - } -} -``` - -Where the `content-available` property is part of the main payload object. Setting the property in this part of the payload will result in the PushPlugin not getting the data correctly. Setting `content-available: true` will cause the Android OS to handle the push payload for you and not pass the data to the PushPlugin. - -Instead move `content-available: true` into the `data` object of the payload and set it to `1` as per the example below: - -```javascript -{ - "registration_ids": ["my device id"], - "data": { - "title": "Test Push", - "message": "Push number 1", - "info": "super secret info", - "content-available": "1" - } -} -``` - -### Huawei and Xiaomi Phones - -These phones have a particular quirk that when the app is force closed that you will no longer be able to receive notifications until the app is restarted. In order for you to receive background notifications: - -- On your Huawei device go to Settings > Protected apps > check "My App" where. -- On your Xiaomi makes sure your phone has the "Auto-start" property enabled for your app. - -### Application force closed - -In order to take advantage of this feature you will need to be using cordova-android 6.0.0 or higher. In order to check if the change has been properly applied look at `platforms/android/**/MainActivity.java`. You should see an `onCreate` method that looks like this: - -```java -@Override -public void onCreate(Bundle savedInstanceState) -{ - super.onCreate(savedInstanceState); - - // enable Cordova apps to be started in the background - Bundle extras = getIntent().getExtras(); - if (extras != null && extras.getBoolean("cdvStartInBackground", false)) { - moveTaskToBack(true); - } - - // Set by <content src="index.html" /> in config.xml - loadUrl(launchUrl); -} -``` - -If you don't see the `if` statement that checks for the appearance of `cdvStartInBackground` you will probably need to do: - -``` -phonegap platform rm android -phonegap platform add android -phonegap build android -``` - -This should add the correct code to the `MainActivity` class. - -If you add `force-start: 1` to the data payload the application will be restarted in background even if it was force closed. - -```javascript -{ - "registration_ids": ["my device id"], - "data": { - "title": "Force Start", - "message": "This notification should restart the app", - "force-start": 1 - } -} -``` - -Here is an example using node-gcm that sends the above JSON: - -```javascript -var gcm = require('node-gcm'); -// Replace these with your own values. -var apiKey = "replace with API key"; -var deviceID = "my device id"; -var service = new gcm.Sender(apiKey); -var message = new gcm.Message(); -message.addData('title', 'Force Start'); -message.addData('message', 'This notification should restart the app'); -message.addData('force-start', 1); -service.send(message, { registrationTokens: [ deviceID ] }, function (err, response) { - if(err) console.error(err); - else console.log(response); -}); -``` - -## Visibility of Notifications - -You can set a visibility parameter for your notifications. Just add a `visibility` field in your notification. -1: secret, 0: private (default), 1: public. `Secret` shows only the most minimal information, excluding even the notification's icon. `Private` shows basic information about the existence of this notification, including its icon and the name of the app that posted it. The rest of the notification's details are not displayed. `Public` Shows the notification's full content. - -```javascript -{ - "registration_ids": ["my device id"], - "data": { - "title": "This is a maximum public Notification", - "message": "This notification should appear in front of all others", - "visibility": 1 - } -} -``` - -Here is an example using node-gcm that sends the above JSON: - -```javascript -var gcm = require('node-gcm'); -// Replace these with your own values. -var apiKey = "replace with API key"; -var deviceID = "my device id"; -var service = new gcm.Sender(apiKey); -var message = new gcm.Message(); -message.addData('title', 'This is a public Notification'); -message.addData('message', 'You should be able to read this notification on your lock screen'); -message.addData('visibility', 1); -service.send(message, { registrationTokens: [ deviceID ] }, function (err, response) { - if(err) console.error(err); - else console.log(response); -}); -``` - -## Badges - -On Android not all launchers support badges. In order for us to set badges we use [ShortcutBadger](https://github.com/leolin310148/ShortcutBadger) in order to set the badge. Check out their website to see which launchers are supported. - -In order to set the badge number you will need to include the `badge` property in your push payload as below: - -```javascript -{ - "registration_ids": ["my device id"], - "data": { - "title": "Badge Test", - "message": "Badges, we don't need no stinking badges", - "badge": 7 - } -} -``` - -Here is an example using node-gcm that sends the above JSON: - -```javascript -var gcm = require('node-gcm'); -// Replace these with your own values. -var apiKey = "replace with API key"; -var deviceID = "my device id"; -var service = new gcm.Sender(apiKey); -var message = new gcm.Message(); -message.addData('title', 'Badge Test'); -message.addData('message', 'Badges, we don\'t need no stinking badges'); -message.addData('badge', 7); -service.send(message, { registrationTokens: [ deviceID ] }, function (err, response) { - if(err) console.error(err); - else console.log(response); -}); -``` - -## Support for Twilio Notify - -This plugin seamlessly supports payloads generated by Twilio Notify on Android. Specifically the parameters passed in to the Twilio REST API are available in the message payload passed to your app as follows: - -- `Title` --> `data.title` -- `Body` --> `data.message` -- `Sound` --> `data.sound` - -Here is an example request to Twilio REST API and the corresponding JSON received by your app. - -``` -curl 'https://notify.twilio.com/v1/Services/IS1e928b239609199df31d461071fd3d23/Notifications' -X POST \ ---data-urlencode 'Identity=Bob' \ ---data-urlencode 'Body=Hello Bob! Twilio Notify + Phonegap is awesome!' \ ---data-urlencode 'Title=Hello Bob!' \ ---data-urlencode 'Sound=chime' \ --u [AccountSID]:[AuthToken] -``` - -The JSON received by your app will comply with the standards described in the sections above: - -```javascript -{ - "registration_ids": ["my device id"], - "data": { - "title": "Hello Bob!", - "message": "Hello Bob! Twilio Notify + Phonegap is awesome!", - "sound": "chime" - } -} -``` - -Note: "sound" and "soundname" are equivalent and are considered to be the same by the plugin. - -# iOS Behaviour - -## Sound - -In order for your notification to play a custom sound you will need to add the files to root of your iOS project. The files must be in the proper format. See the [Local and Remote Notification Programming Guide](https://developer.apple.com/library/ios/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/Chapters/IPhoneOSClientImp.html#//apple_ref/doc/uid/TP40008194-CH103-SW6) for more info on proper file formats and how to convert existing sound files. - -Then send the follow JSON from APNS: - -```javascript -{ - "aps": { - "alert": "Test sound", - "sound": "sub.caf" - } -} -``` - -If you want the default sound to play upon receipt of push use this payload: - -``` -{ - "aps": { - "alert": "Test sound", - "sound": "default" - } -} -``` - -## Background Notifications - -On iOS if you want your `on('notification')` event handler to be called when your app is in the background you will need to do a few things. - -First the JSON you send from APNS will need to include `"content-available": 1` to the `aps` object. The `"content-available": 1` property in your push message is a signal to iOS to wake up your app and give it up to 30 seconds of background processing. If do not want this type of behaviour just omit `"content-available": 1` from your push data. As well you *should* set a `notId` property in the root of payload object. This is the parameter you pass to the `finish` method in order to tell the operating system that the processing of the push event is done. - -For instance the following JSON: - -```javascript -{ - "aps": { - "alert": "Test background push", - "content-available": 1 - }, - "notId": 1 // unique ID you generate -} -``` - -will produce a notification in the notification shade and call your `on('notification')` event handler. - -**NOTE:** The `on('notification')` event handler will **not** be called if Background App Refresh is disabled on the user's iOS device. (Settings > General > Background App Refresh) - -However if you want your `on('notification')` event handler called but no notification to be shown in the shader you would omit the `alert` property and send the following JSON to APNS: - -```javascript -{ - "aps": { - "data": "Test silent background push", - "moredata": "Do more stuff", - "content-available": 1 - }, - "notId": 2 // unique ID you generate -} -``` - -That covers what you need to do on the server side to accept background pushes on iOS. However, it is critically important that you continue reading as there will be a change in your `on('notification')`. When you receive a background push on iOS you will be given 30 seconds of time in which to complete a task. If you spend longer than 30 seconds on the task the OS may decide that your app is misbehaving and kill it. In order to signal iOS that your `on('notification')` handler is done you will need to call the new `push.finish()` method. - -For example: - -```javascript -var push = PushNotification.init({ - "ios": { - "sound": "true", - "alert": "true", - "badge": "true", - "clearBadge": "true" - } -}); - -push.on('registration', function(data) { - // send data.registrationId to push service -}); - - -push.on('notification', function(data) { - // do something with the push data - // then call finish to let the OS know we are done - push.finish(function() { - console.log("processing of push data is finished"); - }, function() { - console.log("something went wrong with push.finish for ID = " + data.additionalData.notId) - }, data.additionalData.notId); -}); -``` - -It is absolutely critical that you call `push.finish()` when you have successfully processed your background push data. - -## Action Buttons - -Your notification can include action buttons. For iOS 8+ you must setup the possible actions when you initialize the plugin: - -```javascript -var push = PushNotification.init({ - "ios": { - "sound": true, - "alert": true, - "badge": true, - "categories": { - "invite": { - "yes": { - "callback": "app.accept", "title": "Accept", "foreground": true, "destructive": false - }, - "no": { - "callback": "app.reject", "title": "Reject", "foreground": true, "destructive": false - }, - "maybe": { - "callback": "app.maybe", "title": "Maybe", "foreground": true, "destructive": false - } - }, - "delete": { - "yes": { - "callback": "app.doDelete", "title": "Delete", "foreground": true, "destructive": true - }, - "no": { - "callback": "app.cancel", "title": "Cancel", "foreground": true, "destructive": false - } - } - } - } -}); -``` - -You’ll notice that we’ve added a new parameter to the iOS object of our init code called categories. Each category is a named object, invite and delete in this case. These names will need to match the one you send via your payload to APNS if you want the action buttons to be displayed. Each category can have up to three buttons which must be labeled `yes`, `no` and `maybe`. In turn each of these buttons has four properties, `callback` the javascript function you want to call, `title` the label for the button, `foreground` whether or not to bring your app to the foreground and `destructive` which doesn’t actually do anything destructive it just colors the button red as a warning to the user that the action may be destructive. - -Just like with background notifications it is absolutely critical that you call `push.finish()` when you have successfully processed the button callback. For instance: - -```javascript -app.accept = function(data) { - // do something with the notification data - - push.finish(function() { - console.log('accept callback finished'); - }, function() { - console.log('accept callback failed'); - }, data.additionalData.notId); -}; -``` - -You may notice that the `finish` method now takes `success`, `failure` and `id` parameters. The `id` parameter let's the operating system know which background process to stop. You'll set it in the next step. - -Then you will need to set the `category` value in your `aps` payload to match one of the objects in the `categories` object. As well you *should* set a `notId` property in the root of payload object. This is the parameter you pass to the `finish` method in order to tell the operating system that the processing of the push event is done. - -```javascript -{ - "aps": { - "alert": "This is a notification that will be displayed ASAP.", - "category": "invite" - }, - "notId": "1" -} -``` - -This will produce the following notification in your tray: - - - -If your users clicks on the main body of the notification your app will be opened. However if they click on either of the action buttons the app will open (or start) and the specified JavaScript callback will be executed. - -### Action Buttons using GCM on iOS - -If you are using GCM to send push messages on iOS you will need to send a different payload in order for the action buttons to be present in the notification shade. You'll need to use the `click-action` property in order to specify the category. - -```javascript -{ - "registration_ids": ["my device id"], - "notification": { - "title": "AUX Scrum", - "body": "Scrum: Daily touchbase @ 10am Please be on time so we can cover everything on the agenda.", - "click-action": "invite" - } -} -``` - -## GCM and Additional Data - -GCM on iOS is a different animal. The way you send data via GCM on Android is like: - -```javascript -{ - "registration_ids": ["my device id"], - "data": { - "title": "My Title", - "message": "My message", - "key1": "data 1", - "key2": "data 2" - } -} -``` - -will produce a `notification` event with the following data: - -```javascript -{ - "title": "My Title", - "message": "My message", - "additionalData": { - "key1": "data 1", - "key2": "data 2" - } -} -``` - -but in order for the same `notification` event you would need to send your push to GCM iOS in a slight different format: - -```javascript -{ - "registration_ids": ["my device id"], - "notification": { - "title": "My Title", - "body": "My message" - } - "data": { - "key1": "data 1", - "key2": "data 2" - } -} -``` - -The `title` and `body` need to be in the `notification` part of the payload in order for the OS to pick them up correctly. Everything else should be in the `data` part of the payload. - -## GCM Messages Not Arriving - -For some users of the plugin they are unable to get messages sent via GCM to show up on their devices. If you are running into this issue try setting the `priority` of the message to `high` in the payload. - -```javascript -{ - "registration_ids": ["my device id"], - "notification": { - "title": "My Title", - "body": "My message" - }, - "priority": "high" -} -``` - -# Windows Behaviour - -## Notifications - -The plugin supports all types of windows platform notifications namely [Tile, Toast, Badge and Raw](https://msdn.microsoft.com/en-us/library/windows/apps/Hh779725.aspx). The API supports the basic cases of the notification templates with title corresponding to the first text element and message corresponding to the second if title is present else the first one. The image corresponds to the first image element of the notification xml. - -The count is present only for the badge notification in which it represent the value of the notification which could be a number from 0-99 or a status glyph. - -For advanced templates and usage, the notification object is included in [`data.additionalData.pushNotificationReceivedEventArgs`](https://msdn.microsoft.com/en-us/library/windows/apps/windows.networking.pushnotifications.pushnotificationreceivedeventargs). - -## Setting Toast Capable Option for Windows - -This plugin automatically sets the toast capable flag to be true for Cordova 5.1.1+. For lower versions, you must declare that it is Toast Capable in your app's manifest file. - -## Disabling the default processing of notifications by Windows - -The default handling can be disabled by setting the 'cancel' property in the notification object. - -```javascript -data.additionalData.pushNotificationReceivedEventArgs.cancel = true -``` - -## Background Notifications - -On Windows, to trigger the on('notification') event handler when your app is in the background and it is launched through the push notification, you will have to include `activation` data in the payload of the notification. This is done by using the `launch` attribute, which can be any string that can be understood by the app. However it should not cause the XML payload to become invalid. - -If you do not include a launch attribute string, your app will be launched normally, as though the user had launched it from the Start screen, and the notification event handler won't be called. - -Here is an example of a sample toast notification payload containing the launch attribute: - -```xml -<toast launch="{"myContext":"12345"}"> - <visual> - <binding template="ToastImageAndText01"> - <image id="1" src="ms-appx:///images/redWide.png" alt="red graphic"/> - <text id="1">Hello World!</text> - </binding> - </visual> -</toast> -``` - -This launch attribute string is passed on to the app as data.launchArgs through the on('notification') handler. It's important to note that due to the Windows platform design, the other visual payload is not available to the handler on cold start. So notification attributes like message, title etc. which are available through the on('notification') handler when the app is running, won't be available for background notifications. diff --git a/StoneIsland/plugins/phonegap-plugin-push/docs/PHONEGAP_BUILD.md b/StoneIsland/plugins/phonegap-plugin-push/docs/PHONEGAP_BUILD.md deleted file mode 100644 index 8a95d6a1..00000000 --- a/StoneIsland/plugins/phonegap-plugin-push/docs/PHONEGAP_BUILD.md +++ /dev/null @@ -1,93 +0,0 @@ -# Cloud Build Services - -- [PhoneGap Build Support](#phonegap-build-support) - - [Including the plugin](#including-the-plugin) - - [Adding Resources](#adding-resources) -- [IntelXDK Support](#intelxdk-support) - -## PhoneGap Build Support - -> Currently PhoneGap Build does not support version 1.9.0 of the plugin. Updates are being made to PGB to support the latest release. - -### Including the plugin - -Including this plugin in a project that is built by PhoneGap Build is as easy as adding: - -```xml -<preference name="android-build-tool" value="gradle" /> -<plugin name="phonegap-plugin-push" source="npm"> - <param name="SENDER_ID" value="<Your Sender ID>" /> -</plugin> -``` - -into your app's `config.xml` file. PhoneGap Build will pick up the latest version of phonegap-plugin-push published on npm. If you want to specify a particular version of the plugin you can add the `spec` attribute to the `plugin` tag. - -```xml -<preference name="android-build-tool" value="gradle" /> -<plugin name="phonegap-plugin-push" spec="~1.4.5" source="npm" /> -``` - -Note: version 1.3.0 of this plugin begins to use Gradle to install the Android Support Framework. Support for Gradle has recently been added to PhoneGap Build. Please read [this blog post](http://phonegap.com/blog/2015/09/28/android-using-gradle/) for more information. - -### Adding resources - -Because PhoneGap Build does not support running hooks if you want to include custom image or sounds you will need to use a *beta* feature to include these files. - -#### Android - -To add custom files, create a directory called `locales/android/` in the root of your PGB application zip / repo, and place your resource files there. The contents will be copied into the Android `res/` directory, and any nested sub-directory structures will persist. Here's an example of how these files will be compiled into your APK: - -``` -<www.zip>/locales/android/drawables/logo.png --> <android_apk>/res/drawables/logo.png -<www.zip>/locales/android/raw/beep.mp3 --> <android_apk>/res/raw/beep.mp3 -<www.zip>/locales/android/values-fr/strings.xml --> <android_apk>/res/values-fr/strings.xml -``` - -Existing directories will be merged, but at this time any individual files you include will overwrite their target if it exists. - -## IntelXDK Support - -1. Do pre-requisite setup on [the iOS Provisioning Portal](https://developer.apple.com/account/ios/identifier/bundle). Refer to [this guide](https://www.raywenderlich.com/123862/push-notifications-tutorial) or Apple docs for detailed steps. -a. make a new App ID (you'll need to set this in Intel XDK config later) -b. enable push notifications -c. iOS Distribution cert: create (if needed), download and install (if needed), export as a .p12 (set and remember the password as you'll need this to import into Intel XDK later) -**NOTE**: Intel XDK does not support Development certs, so you MUST use your Distribution cert. -d. Make an AdHoc Provisioning Profile using your App ID from (1a) and your cert from (1c). Make sure your test device is enabled. Download and save with a name you will recognize. (you'll need to add this to your Intel XDK project later) -e. make a push cert, download it, install it, export it to .p12, convert it to .pem (this is for the push server that will send the notification - you'll need this later to test your Intel XDK app) - -2. In Intel XDK, make a new Cordova CLI 5.4.1 project using the HTML5+Cordova Blank Template, then replace the contents of www with [the contents of www from the PhoneGap Push Template](https://github.com/phonegap/phonegap-template-push/tree/master/template_src/www). - -3. Delete www/config.xml (optional? Intel XDK does not use config.xml) - -4. Intel XDK Project Settings -a. set the iOS App ID to match the App ID from (1a) -b. (if needed) import your .p12 from (1c) - Account Settings->Developer Certificates->iOS, then select it as the Developer Certificate for the project -c. Select "adhoc" for Provisioning Profile -d. copy your provisioning profile from (1d) into www/, then click "Ad hoc Provisioning Profile" and select the profile -e. Add the latest version of phonegap-plugin-push as a "Third-Party Plugin" (at time of testing this was 1.6.4) -f. **After the plugin is added, you will need to edit plugins/phonegap-plugin-push/plugin.xml**. Intel XDK 3357 does not support plugins with gradle references, so the gradle reference must be commented out (this will prevent this version of the plugin from working for Android but is needed for the iOS build to succeed): -`<!--framework src="push.gradle" custom="true" type="gradleReference" /-->` -A future version of Intel XDK will support gradle references. - -5. XDK Build Tab -a. Enable iOS build (click the checkmark) -b. Unlock your iOS certificate (click the lock and enter the password from (1c)) -c. click Start Builds -d. once the build completes, download and install the app - -6. connect test device by USB and open XCode Devices window (probably could also use Safari Web Inspector + Cordova Console plugin) - start the app and a log message should be written into the console that looks like "Push Plugin register success: \<XXXXXXXX 19b101a3 71590c03 9ea7f446 50eb8409 19ac24bb c1ec1320 XXXXXXXX\>" - -7. exit the app (close with home button then swipe it off the multitask view) - -8. The angle brackets and everything between (from (5)) is the device token - copy it into a text file - -9. Add the device token to your server and send a push notification -a. I used [phonegap-plugin-push/example/server/pushAPNS.rb](https://github.com/phonegap/phonegap-plugin-push/blob/master/example/server/pushAPNS.rb) for this -b. APNS.host = 'gateway.push.apple.com' -c. APNS.pem = 'PGPush926Prod.pem' #path to your pem file from (1e) -d. device_token = '\<XXXXXXXX 19b101a3 71590c03 9ea7f446 50eb8409 19ac24bb c1ec1320 XXXXXXXX\>' #the device token from (7) -e. edit the alert message and badge number -f. you probably need to install the required gem (`gem install pushmeup`) -g. send the notification (`ruby pushAPNS.rb`) - -10. See notification on device! diff --git a/StoneIsland/plugins/phonegap-plugin-push/docs/PLATFORM_SUPPORT.md b/StoneIsland/plugins/phonegap-plugin-push/docs/PLATFORM_SUPPORT.md deleted file mode 100644 index 3a4e2969..00000000 --- a/StoneIsland/plugins/phonegap-plugin-push/docs/PLATFORM_SUPPORT.md +++ /dev/null @@ -1,17 +0,0 @@ -## Supported Platforms - -### Version 1.9.x - -- Cordova CLI (6.4.0 or newer) -- Android (`cordova-android` 6.0.0 or higher) -- Browser -- iOS (`cordova-ios` 4.3.0 or higher) -- Windows Universal (not Windows Phone 8) - -### Version 1.8.x - -- Cordova CLI (3.6.3 or newer) -- Android (`cordova-android` 4.0.0 or higher) -- Browser -- iOS (`cordova-ios` 4.1.0 or higher) -- Windows Universal (not Windows Phone 8) diff --git a/StoneIsland/plugins/phonegap-plugin-push/docs/TYPESCRIPT.md b/StoneIsland/plugins/phonegap-plugin-push/docs/TYPESCRIPT.md deleted file mode 100644 index 37117d16..00000000 --- a/StoneIsland/plugins/phonegap-plugin-push/docs/TYPESCRIPT.md +++ /dev/null @@ -1,72 +0,0 @@ -# Typescript definition file - -For those of you who use typescript, we're glad to say that we have the complete definition file available at [DefinitelyTyped](https://github.com/DefinitelyTyped/DefinitelyTyped). -Search for `phonegap-plugin-push` there, or simply grab it directly [here](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/phonegap-plugin-push/phonegap-plugin-push.d.ts). - -## Example usage - -All objects will be understood as having a defined type, including init options and eventHandler parameters. -All available attributes and properties will have autocomplete support and type checkings. - -```typescript -let push = PushNotification.init({ - android: { - senderID: "12345679" - }, - ios: { - alert: "true", - badge: true, - sound: 'false' - }, - windows: {} -}); - -push.on('registration', (data) => { - console.log(data.registrationId); -}); - -push.on('notification', (data) => { - console.log(data.message); - console.log(data.title); - console.log(data.count); - console.log(data.sound); - console.log(data.image); - console.log(data.additionalData); -}); - -push.on('error', (e) => { - console.log(e.message); -}); -``` - -If you have custom attributes being sent from the server on the payload, you can define them on a custom interface extending the standard one: - -```typescript -module my.custom { - export interface NotificationEventResponse extends PhonegapPluginPush.NotificationEventResponse { - additionalData: NotificationEventAdditionalData; - } - - export interface NotificationEventAdditionalData extends PhonegapPluginPush.NotificationEventAdditionalData { - bacon?: boolean; - } -} - -push.on('notification', (data: my.custom.NotificationEventResponse) => { - //standard attributes - console.log(data.message); - console.log(data.title); - console.log(data.count); - console.log(data.sound); - console.log(data.image); - console.log(data.additionalData); - - //custom attributes - console.log(data.additionalData.bacon); -}); -``` - -## Outdated definitions - -Is our definition file at DefinitelyTyped outdated? Is there any improvements that could be done? -We welcome any contribution, and they should be done through issues created [there](https://github.com/DefinitelyTyped/DefinitelyTyped/issues/new).
\ No newline at end of file |