在调用 LeanCloud.initialize 之后,需要调用 PushService.setDefaultChannelId(context, channelid) 设置通知展示的默认 channel,否则消息无法展示。Channel ID 的解释请阅读 Google 官方文档 Creating a notification。
另外,我们的推送服务也支持多个推送 Channel。在客户端,开发者可以通过调用 PushService 的如下方法创建新的通知 Channel(也可以自己调用底层 API 创建):
public static void createNotificationChannel(Context context, String channelId, String channelName,
String description, int importance,
boolean enableLights, int lightColor,
boolean enableVibration, long[] vibrationPattern)
/**
* 设置 PushService 以前台进程的方式运行(默认是 background service)。
* Android 前台 Service 必须要显示一个 Notification 在通知栏,详见说明:
* https://developer.android.com/guide/components/services
*
* @param enableForeground enable PushService run on foreground or not.
* @param identifier The identifier for this notification as per
* {@link NotificationManager#notify(int, Notification)
* NotificationManager.notify(int, Notification)}; must not be 0.
* @param notification The Notification to be displayed.
*/
public static void setForegroundMode(boolean enableForeground, int identifier, Notification notification);
Android 推送开发指南
请先阅读《推送通知服务总览》了解相关概念。
Android 消息推送有专门的 Demo,请见 Android-Push-Demo 项目。
推送流程简介
Android 的推送主要依赖客户端的 PushService 服务。PushService 是一个独立于应用程序的进程,在应用程序第一次启动时顺带创建,其后则(尽量)一直存活于后台,它主要负责维持与云推送服务器的 WebSocket 长链接。 所以,只要 PushService 存活,那么推送服务器上有任何需要下发到当前设备的消息,都会立刻推送下来;如果 PushService 被杀死,那推送通道中断,Android 设备就收不到任何推送消息(混合推送除外,后述会有说明)。PushService 第一次启动,建立起与推送服务器的 WebSocket 长链接之后,也会一次性收到多条服务端缓存的未成功下发的历史消息。
接入推送服务
要接入推送服务,需要依赖 realtime-android library。首先打开
app
目录下的build.gradle
进行如下配置:然后新建一个 Java Class ,名字叫做 MyLeanCloudApp,让它继承自 Application 类,实例代码如下:
配置 AndroidManifest
请确保你的
AndroidManifest.xml
的<application>
中包含如下内容:同时设置了必要的权限:
为了让应用能在关闭的情况下也可以收到推送,你需要在
<application>
中加入:推送唤醒
如果希望支持应用间的推送唤醒机制,即在同一设备上有两个使用了云推送的应用,应用 A 被杀掉后,当应用 B 被唤醒时可以同时唤醒应用 A 的推送,可以这样配置:
完整的
AndroidManifest.xml
完整的
AndroidManifest.xml
文件配置示意如下:保存 Installation
当应用在用户设备上安装好以后,如果要使用推送功能,SDK 会自动生成一个 Installation 对象。该对象本质上是应用在设备上生成的安装信息,需要首先将它保存到云端设备才能收到推送:
这段代码应该在应用启动的时候调用一次,保证设备注册到云端。你可以监听调用回调,获取 installationId 做数据关联。
启动推送服务
通过调用以下代码启动推送服务,同时设置默认打开的 Activity。
订阅频道
你的应用可以订阅某个频道(channel)的消息,只要在保存 Installation 之前调用
PushService.subscribe
方法:注意:
_
)、连字符(-
)、等号(=
)、汉字(中日韩统一表意文字)。退订频道也很简单:
Android 8.0 推送适配
在调用
LeanCloud.initialize
之后,需要调用PushService.setDefaultChannelId(context, channelid)
设置通知展示的默认channel
,否则消息无法展示。Channel ID 的解释请阅读 Google 官方文档 Creating a notification。另外,我们的推送服务也支持多个推送 Channel。在客户端,开发者可以通过调用
PushService
的如下方法创建新的通知 Channel(也可以自己调用底层 API 创建):记下这里的
channelId
,因为之后发送推送通知的时候,我们还需要用到它。在发送推送请求的时候,通过_notificationChannel
这个自定义的关键字可以选择不同的 channel 进行消息展示。例如如下的请求会在客户端通知 id 为 “1” 的通道进行显示:
推送消息
云服务控制台 > 推送 > 设置 中默认选中了 禁止从客户端进行消息推送,从而避免了客户端可以不经限制的给应用内任意目标设备推送消息的可能。我们建议用户都将此限制启用。如果有需求要从客户端发推送,需要先打开这个限制。
推送给所有的设备
发送给特定的用户
发送给「public」频道的用户:
发送给某个 Installation id 的用户,通常来说,你会将 LCInstallation 关联到设备的登录用户 LCUser 上作为一个属性,然后就可以通过下列代码查询 InstallationId 的方式来发送消息给特定用户,实现类似私信的功能:
深入阅读:如何响应推送消息
注意,以下内容不适用于混合推送。 混合推送中,需要使用各厂商提供的机制指定特定的 activity 来响应推送消息,详见《混合推送开发指南》。
消息格式
具体的消息格式,可参考《推送 REST API 使用指南》的《推送消息》一节。 对于 Android 设备,默认的消息内容参数支持下列属性:
上面 silent 属性,是透传消息与通知栏消息的标志。silent 为 true,表示消息不展示在通知栏;silent 为 false,表示消息会展示在通知栏。
前面讲过,在 PushService 里面接收到推送消息之后,在转发消息之前,会判断消息是否过期,以及是否收到了重复的消息,只有非过期、非重复的消息,才会会通过发送本地通知或者广播,将事件告知应用程序。
通知栏消息如何响应用户点击事件
PushService 在发出通知栏消息的时候,会根据开发者调用
PushService.setDefaultPushCallback(context, clazz)
或者PushService.subscribe(context, "channel", clazz)
设置的回调类,设置通知栏的响应类。在回调类的 onCreate 函数中开发者则可以通过如下代码获取推送消息的具体数据:
自定义 Receiver
如果你想推送消息,但不显示在 Android 系统的通知栏中,而是执行应用程序预定义的逻辑,你需要在你的 Android 项目中的
AndroidManifest.xml
中声明你自己的 Receiver:其中
com.avos.avoscloud.PushDemo.MyCustomReceiver
是你的 Android 的 Receiver 类。而<action android:name="com.avos.UPDATE_STATUS" />
需要与 push 的 data 中指定的action
相对应。你的 Receiver 可以按照如下方式实现:
同时,要求发送推送的请求也做相应更改,例如:
注意,如果你使用自定义的 Receiver,发送的消息必须带 action,并且其值在自定义的 Receiver 配置的
<intent-filter>
列表里存在,比如这里的'com.avos.UPDATE_STATUS'
,请使用自己的 action,尽量不要跟其他应用混淆,推荐采用域名来定义。混合推送
自 Android 8.0 之后,系统权限控制越来越严,第三方推送通道的生命周期受到较大限制,同时国内主流厂商也开始推出自己独立的推送服务。因此我们提供「混合推送」的方案来提升推送到达率,具体请参考《Android 混合推送开发指南》。
让 PushService 前台运行
对于高版本的 Android OS 系统来说,后台 Service 受到越来越严格的限制,为了尽量保证 PushService 的生命周期,让 PushSevice 成为前台 Service(foreground Service)来运行也是一个可以考虑的选择。
为了支持这一选项,从 6.4.0 版本开始,我们在
realtime-android
library 中,给 PushService 增加了一个新的配置项,以便开发者自己选择是否让 PushService 在前台运行:PushService 默认是始终在后台运行的,如果切换到前台运行,从我们测试的结果来看,PushService 可以保持长时间不被系统杀死。设置前台运行的示例代码如下: