Android 推送指南
请先阅读推送通知总览了解相关概念。
Android 消息推送有专门的 Demo,请见 Android-Push-Demo 项目。
推送流程简介
Android 的推送主要依赖客户端的 PushService 服务。PushService 是一个独立于应用程序的进程,在应用程序第一次启动时顺带创建,其后则(尽量)一直存活于后台,它主要负责维持与云推送服务器的 WebSocket 长链接。 所以,只要 PushService 存活,那么推送服务器上有任何需要下发到当前设备的消息,都会立刻推送下来;如果 PushService 被杀死,那推送通道中断,Android 设备就收不到任何推送消息(混合推送除外,后述会有说明)。PushService 第一次启动,建立起与推送服务器的 WebSocket 长链接之后,也会一次性收到多条服务端缓存的未成功下发的历史消息。
接入推送服务
要接入推送服务,需要依赖 realtime-android library。首先打开 app
目录下的 build.gradle
进行如下配置:
dependencies {
implementation 'cn.leancloud:realtime-android:8.2.24'
implementation 'io.reactivex.rxjava2:rxandroid:2.1.0'
}
然后新建一个 Java Class ,名字叫做 MyLeanCloudApp,让它继承自 Application 类,实例代码如下:
public class MyLeanCloudApp extends Application {
@Override
public void onCreate() {
super.onCreate();
// 初始 化参数依次为 this, ClientID, clientToken
LeanCloud.initialize(this, "{{clientID}}", "{{clientToken}}", "https://please-replace-with-your-customized.domain.com");
}
}
配置 AndroidManifest
请确保你的 AndroidManifest.xml
的 <application>
中包含如下内容:
<service android:name="cn.leancloud.push.PushService" />
同时设置了必要的权限:
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
为了让应用能在关闭的情况下也可以收到推送,你需要在 <application>
中加入:
<receiver android:name="cn.leancloud.push.LCBroadcastReceiver">
<intent-filter>
<action android:name="android.intent.action.BOOT_COMPLETED" />
<action android:name="android.intent.action.USER_PRESENT" />
<action android:name="android.net.conn.CONNECTIVITY_CHANGE" />
</intent-filter>
</receiver>
推送唤醒
如果希望支持应用间的推送唤醒机制,即在同一设备上有两个使用了云推送的应用,应用 A 被杀掉后,当应用 B 被唤醒时可以同时唤醒应用 A 的推送,可以这样配置:
<service android:name="cn.leancloud.push.PushService" android:exported="true"/>
完整的 AndroidManifest.xml
完整的 AndroidManifest.xml
文件配置示意如下:
<!-- 基本模块(必须)START -->
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<!-- 基本模块 END -->
<application
android:icon="@drawable/notification"
android:theme="@android:style/Theme.Holo.Light"
android:label="@string/app_name"
android:name=".MyLeanCloudApp" >
<!-- 即时通讯和推送 START -->
<!-- 即时通讯、推送、LiveQuery 都需要 PushService -->
<service android:name="cn.leancloud.push.PushService"/>
<receiver android:name="cn.leancloud.push.LCBroadcastReceiver">
<intent-filter>
<action android:name="android.intent.action.BOOT_COMPLETED"/>
<action android:name="android.intent.action.USER_PRESENT"/>
<action android:name="android.net.conn.CONNECTIVITY_CHANGE" />
</intent-filter>
</receiver>
<!-- 即时通讯和推送 END -->
<!-- 用户反馈 START -->
<activity
android:name="cn.leancloud.feedback.ThreadActivity" >
</activity>
<!-- 用户反馈 END -->
保存 Installation
当应用在用户设备上安装 好以后,如果要使用推送功能,SDK 会自动生成一个 Installation 对象。该对象本质上是应用在设备上生成的安装信息,需要首先将它保存到云端设备才能收到推送:
LCInstallation.getCurrentInstallation().saveInBackground();
这段代码应该在应用启动的时候调用一次,保证设备注册到云端。你可以监听调用回调,获取 installationId 做数据关联。
LCInstallation.getCurrentInstallation().saveInBackground().subscribe(new Observer<LCObject>() {
@Override
public void onSubscribe(Disposable d) {
}
@Override
public void onNext(LCObject avObject) {
// 关联 installationId 到用户表等操作。
String installationId = LCInstallation.getCurrentInstallation().getInstallationId();
System.out.println("保存成功:" + installationId );
}
@Override
public void onError(Throwable e) {
System.out.println("保存失败,错误信息:" + e.getMessage());
}
@Override
public void onComplete() {
}
});
启动推送服务
通过调用以下代码启动推送服务,同时设置默认打开的 Activity。
// 设置默认打开的 Activity
PushService.setDefaultPushCallback(this, PushDemo.class);
订阅频道
你的应用可以订阅某个频道(channel)的消息,只要在保存 Installation 之前调用 PushService.subscribe
方法:
// 订阅频道,当该频道消息到来的时候,打开对应的 Activity
// 参数依次为:当前的 context、频道名称、回调对象的类
PushService.subscribe(this, "public", PushDemo.class);
PushService.subscribe(this, "private", Callback1.class);
PushService.subscribe(this, "protected", Callback2.class);
注意:
- 频道名称只能包含大小写英文字母、数字、下划线(
_
)、连字符(-
)、等号(=
)、汉字(中日韩统一表意文字)。 - 回调对象指用户点击通知栏的通知进入的 Activity 页面。
退订频道也很简单:
PushService.unsubscribe(context, "protected");
//退订之后需要重新保存 Installation
LCInstallation.getCurrentInstallation().saveInBackground();