cordova-plugin-leanpush

A Cordova plugin for LeanCloud Push and Analytics services

Usage no npm install needed!

<script type="module">
  import cordovaPluginLeanpush from 'https://cdn.skypack.dev/cordova-plugin-leanpush';
</script>

README

cordova-plugin-leanpush

Cordova plugin for LeanCloud push notification

Installation

  • Fetch from cordova npm
 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
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

Usage

Init

Put the initialization Code in your "deviceReady" Code Block (like $ionicPlatform.ready)

window.LeanPush.init();

Push Related API

Coresponding to the Leancloud Push documentation.


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.
//   }
// }
    

$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 XD 😁

About Sending Push

Use the JS API: AV.Push that leancloud provide.

LeanAnalytics API

Corresponding code is forked from https://github.com/Hybrid-Force/cordova-plugin-leancloud.

Only a novice for leancloud I am, so

is the better way to go.

Screen Recording

Android

IOS

See the Attention Below, the webview can't alert when onResume

One

  • notice from close
  • notice while foreground

Two

  • notice from background
mobile

console.log

The debugger in screenshot is 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.

So if you use another plugin that also goes this way, then there gonna be conflicts.

Uninstall

For fully uninstallation:

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

 packagingOptions {
       exclude 'META-INF/LICENSE.txt'
       exclude 'META-INF/NOTICE.txt'
}

It should look like below

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