cordova-plugin-leanpush

.gitignore

@@ -0,0 +1,3 @@
+.DS_Store
+.tern_port
+/node_modules/

LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2015 Derek Hsu
+Copyright (c) 2015 Xinyu Zhang, Derek Hsu 
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,39 +1,262 @@
-cordova-plugin-lean-push
+cordova-plugin-leanpush
 ========================
 
-Cordova plugin for LeanCloud push notification
+Cordova plugin for [LeanCloud](https://leancloud.cn) push notification
+
+
 
 ## Installation
+
+
+- Fetch from cordova npm
+
+```shell
+ cordova plugin add cordova-plugin-leanpush  --variable LEAN_APP_ID=<YOUR_LEANCOULD_APP_ID> --variable LEAN_APP_KEY=<YOUR_LEANCOULD_APP_KEY>
+```
+
+
+
+
+- Add this to your `gulpfile.js`
+
+```js
+gulp.task('lpush-install', function(done){
+    require('./plugins/cordova-plugin-leanpush/lpush-installer.js')(__dirname, done);
+});
+```
+
+- `npm install --save-dev xml2js thunks && npm install`
+
+- Then exectue this gulp task by running `gulp lpush-install` in shell.
+
+- Done.
+
+### Known Android Build Issue
+
+See [Attention/Android Build Issue](#android-build-issue)
+
+
+
+## Usage
+
+### Init
+
+
+Put the initialization Code in your "deviceReady" Code Block (like $ionicPlatform.ready)
+
+```js
+window.LeanPush.init();
+```
+
+<!-- The Init accepts a optional function as the callback when the notification recieves *(If provided, it will call onNotificationReceived on this function)*. -->
+
+
+
+### Push Related API
+
+
+Coresponding to the [Leancloud Push documentation](https://leancloud.cn/docs/ios_push_guide.html).
+
+```js
+
+window.LeanPush.subscribe(channel, success, error)  // 订阅频道 channel :string 
+window.LeanPush.unsubscribe(channel, success, error) //退订频道 channel :string
+window.LeanPush.clearSubscription(success, error) //退订所有频道 
+
+window.LeanPush.getInstallation(success, error)  //Installation 表示一个允许推送的设备的唯一标示, 对应数据管理平台中的 _Installation 表
+// success callback:
+// function(data){
+//   data = {
+//        'deviceType':'android' or 'ios',
+//        'installationId': 'android installation id' or 'ios deviceToken'
+//        'deviceToken':    'ios deviceToken' or 'android installation id'
+//   }
+// }
+
+
+window.LeanPush.onNotificationReceived(callback) // 一个notification到来的回调函数
+// callback:
+// function(notice){
+//  notice = {
+//     'prevAppState': 'background' or 'foreground' or 'closed',
+
+//      push到来的时候上一个App状态:
+//      android只有 'background' 和 'closed', 因为android所有push都要点击
+//      ios都有，因为ios如果app在前台，系统推送的alert不会出现
+//      用户没有任何操作，app就自动执行notification的函数不好, 可以加个判断
+
+//     'alert':'Notice Text',
+//     'file_url':'Push File',
+//     'key':'value'   if you send JSON Type Push, they will map to here.
+//   }
+// }
 
-    cordova plugin add git@github.com:Hybrid-Force/cordova-plugin-leancloud.git --variable LEAN_APP_ID=<YOUR_LEANCOULD_APP_ID> --variable LEAN_APP_KEY=<YOUR_LEANCOULD_APP_KEY>
-
-## Android Quirk
-The LeanCloud push service need to be initialized in Application::onCreate, otherwise, the app might crash when opening via push notification when the app is not running in foreground. To fix this, add an application where we can initialize the push service.
-
-1. Edit `platforms/android/src/com/sum/cordova/leancloud/LeanApplication.java`, replace `<%MAINACTIVITY%>`, `<%APPID%>` and `<%APPKEY%>`.
-
-2. Edit `platforms/android/AndroidManifest.xml`, add `android:name="com.sum.cordova.leancloud.LeanApplication"` to application element
-
-These can be easily done with gulp, for example:
-
-    var xeditor = require('gulp-xml-editor');
-    var replace = require('gulp-replace');
-    var config = require('./package.json');
-
-    gulp.task('android-manifest', function() {
-        return gulp.src("platforms/android/AndroidManifest.xml")
-            .pipe(xeditor([
-                {
-                    path: '/manifest/application',
-                    attr: {'android:name': 'com.sum.cordova.leancloud.LeanApplication'}
-                }], {'android': 'http://schemas.android.com/apk/res/android'}))
-            .pipe(gulp.dest("platforms/android"));
-    });
-
-    gulp.task('android-application', function() {
-        return gulp.src("platforms/android/src/com/sum/cordova/leancloud/LeanApplication.java")
-            .pipe(replace('<%MAINACTIVITY%>', config.mainActivity))
-            .pipe(replace('<%APPID%>', config.leanAppId))
-            .pipe(replace('<%APPKEY%>', config.leanAppKey))
-            .pipe(gulp.dest("platforms/android/src/com/sum/cordova/leancloud"));
-    });
+
+$rootScope.$on('leancloud:notificationReceived', callback) // 如果你用了angular， 一个notification会在scope上broadcast这个event
+// callback:
+// function(event, notice){
+//    // event is from angular, notice is same above 
+// }
+```
+
+Many Thanks to [Derek Hsu](https://github.com/Hybrid-Force) XD 😁
+
+
+
+
+### About Sending Push
+
+Use the [JS API: AV.Push](https://leancloud.cn/docs/js_guide.html#Push_通知) that leancloud provide.
+
+
+
+### LeanAnalytics API
+
+Corresponding code is forked from [https://github.com/Hybrid-Force/cordova-plugin-leancloud](https://github.com/Hybrid-Force/cordova-plugin-leancloud).
+
+
+Only a novice for leancloud I am, so
+
+- take a look at the source code [https://github.com/BenBBear/cordova-plugin-leanpush/blob/master/www/LeanAnalytics.js](https://github.com/BenBBear/cordova-plugin-leanpush/blob/master/www/LeanAnalytics.js) to know the API
+
+- and study the [Leancloud documentation about leanAnalytics](https://leancloud.cn/docs/ios_statistics.html)
+
+is the better way to go.
+
+
+
+---
+
+## Screen Recording
+
+### Android
+![](./img/android.gif)
+
+### IOS
+
+See the [Attention Below](#attention), the webview can't `alert` when `onResume`
+
+#### One
+
+- notice from close
+- notice while foreground
+
+![](./img/ios.gif)
+
+#### Two
+
+- notice from background
+
+##### mobile
+
+![](./img/ios-back-phone.gif)
+
+##### console.log
+
+![](./img/ios-back.gif)
+
+The debugger in screenshot is [GapDebug](https://www.genuitec.com/products/gapdebug/), debug phonegap in browser :D
+
+
+
+
+
+
+## Behavior
+
+The `onNotificationReceived callback`  and the `$rootScope.$emit('leancloud:notificationReceived')` will fires when
+
+### IOS
+
+- app in the foreground, notice comes (won't show the system notification alert)
+- app in the background, tap the notification to resume it
+- app closed, tap the notification to open it
+
+### Android
+
+
+- app in the foreground, tap the notification to see it
+- app in the background, tap the notification to resume it
+- app closed, tap the notification to open it
+
+
+
+## Attention
+
+### Android Quirk
+
+In order to receive push from android, I change the default `MainActivity` and `Application Entry`  in that gulp task. Details in the [lpush_installer.js](https://github.com/BenBBear/cordova-plugin-leanpush/blob/master/lpush-installer.js).
+
+> So if you use another plugin that also goes this way, then there gonna be conflicts.
+
+
+#### Uninstall
+
+For fully uninstallation:
+
+```shell
+cordova plugin rm cordova-plugin-leanpush
+ionic platform rm android && ionic platform rm ios
+ionic platform add android && ionic platform add ios
+```
+
+### Don't Use Alert in the IOS inside Notification Callback
+
+> `alert` is a blocking function.
+
+#### IOS UIWebView
+
+It will cause the app to freeze when you resume the app by clicking notification. (but it seems ok when the app is in the foreground or closed.)
+
+###  For Android
+
+As far as I try, `alert` is fine, guess is the difference of webView between  IOS and android.
+
+
+### Notification Handler
+
+There are two ways, both will be fired when notification comes
+
+- `onNotificationReceived`
+
+- `$rootScope.$emit('leancloud:notificationReceived')`
+
+
+You can choose one of them, but may not both.
+
+
+###  Android Build Issue
+
+- **Error: duplicate files during packaging of APK**
+
+**How to Solve:**
+
+
+insert following code into the **android tag** of `platforms/android/build.gradle`
+
+```groovy
+ packagingOptions {
+       exclude 'META-INF/LICENSE.txt'
+ 	   exclude 'META-INF/NOTICE.txt'
+}
+```
+
+It should look like below
+
+```groovy
+android{
+   packagingOptions {
+       exclude 'META-INF/LICENSE.txt'
+ 	   exclude 'META-INF/NOTICE.txt'
+   }
+    //stuff
+}
+```
+
+
+
+## LICENSE
+
+The MIT License (MIT)
+
+Copyright (c) 2015 Xinyu Zhang, Derek Hsu