与其他推送的初始化方法一样,我们在 Application#onCreate 方法中进行 vivo 推送的初始化:
import cn.leancloud.AVOSCloud;
import cn.leancloud.AVMixPushManager; // 使用 mixpush-android 的场合
//import cn.leancloud.vivo.AVMixPushManager; // 使用 mixpush-vivo 的场合
public class MyApp extends Application {
// 请替换成您自己的 appId 和 appKey
private static final String LC_APP_ID = "xxx";
private static final String LC_APP_KEY = "xxx";
@Override
public void onCreate() {
super.onCreate();
//开启调试日志
AVOSCloud.setLogLevel(AVLogger.Level.DEBUG);
// AVOSCloud SDK 初始化
AVOSCloud.initialize(this,LC_APP_ID,LC_APP_KEY);
// vivo 推送初始化
// 使用 mixpush-android 的场合,引用 cn.leancloud.AVMixPushManager
// 使用 mixpush-vivo 的场合,引用 cn.leancloud.vivo.AVMixPushManager
AVMixPushManager.registerVIVOPush(this);
AVMixPushManager.turnOnVIVOPush(new AVCallback<Boolean>() {
@Override
protected void internalDone0(Boolean aBoolean, AVException e) {
if (null != e) {
System.out.println("failed to turn on vivo push. cause:");
e.printStackTrace();
} else {
System.out.println("succeed to turn on vivo push.");
}
}
});
}
}
开发者也可以在 onCreate 方法中调用 AVMixPushManager 的其他方法,以使用 vivo 推送的全部客户端功能:
public class AVMixPushManager {
// 判断当前设备是否支持 vivo 推送
public static boolean isSupportVIVOPush(Context context);
// 关闭 vivo 推送
public static void turnOffVIVOPush(final AVCallback<Boolean> callback);
public static void bindVIVOAlias(Context context, String alias, final AVCallback<Boolean> callback);
public static void unbindVIVOAlias(Context context, String alias, final AVCallback<Boolean> callback);
public static String getVIVOAlias(Context context);
public static void setVIVOTopic(Context context, String topic, final AVCallback<Boolean> callback);
public static void delVIVOTopic(Context context, String topic, final AVCallback<Boolean> callback);
public static List<String> getVIVOTopics(Context context);
}
Android 混合推送开发指南
混合推送概述
自 Android 8.0 之后,系统权限控制越来越严,第三方推送通道的生命周期受到较大限制;同时,国内主流厂商也开始推出自己独立的推送服务,而厂商间千差万别的繁杂接口徒增了开发和代码维护的难度。为此,我们推出了混合推送的方案。我们逐一对接国内主流厂商,将它们不同的接口隐藏起来,让开发者通过统一的 API 完成推送任务。这不仅大幅降低了开发复杂度,还保障了主流 Android 系统上的推送到达率。
在混合推送方案里,消息下发时使用的通道不再是 LeanCloud 自己维持的 WebSocket 长连接,而是借用厂商和 OS 层的系统通道进行通信。一条推送消息下发的步骤如下:
整个流程与苹果的 APNs 推送类似,LeanCloud SDK 在客户端基本不会得到调用,消息的下发和展示都依赖厂商客户端的行为。所以如果部分厂商在某些推送中夹带了其他非开发者提交的消息,或者在服务启用的时候,有额外营销性质的弹窗,这都是厂商自己的行为,与 LeanCloud 完全无关,还请大家了解。另外,如果开发者碰到厂商 SDK 的问题,我们也无法深入调查,还请大家自行到厂商的论坛或技术支持渠道咨询解决。
开启了混合推送之后,Installation 表中每一个设备对应的记录,会增加一个 vendor 字段(如果没有这一字段,则说明客户端集成有问题),其值分别为:
HMS
mi
mz
oppo
vivo
fcm
注意,混合推送对接的是厂商各自的推送服务,需要单独配置,不支持混用。 通常情况下,需要提交不同的版本(分别对接厂商的推送服务)到相应厂商的应用商店。 如果希望使用统一版本,那么需要自行判断手机型号,在合适的手机上开启合适的推送。
即时通讯的离线推送
在即时通讯服务中,在 iOS 平台上如果用户下线,是可以启动离线消息推送机制的,对于 Android 用户来说,如果只是使用 LeanCloud 自身推送通道,那么是不存在离线推送的,因为聊天和推送共享同一条 WebSocket 长链接,在即时通讯服务中用户下线了的话,那么推送也必然是不可达的。但是如果启用了混合推送,因为推送消息走的是厂商通道,这一点和 iOS 基本一致,所以这时候 Android 用户就存在离线推送的通知路径了。 也就是说,如果开启了混合推送,那么即时通讯里面的离线推送和静音机制,对使用了混合推送的 Android 用户也是有效的。
下面我们逐一看看如何对接华为、小米、魅族等厂商的推送服务,文档的最后也提及了在海外市场如何对接 Firebase Cloud Messaging 的方法。
混合推送 library 的构成
在 6.5.0 版本之前,我们提供了一个 all-in-one 的混合推送模块,统一支持华为(HMS)、小米、Oppo、Vivo、魅族推送,开发者依赖如下: 'cn.leancloud:mixpush-android:7.2.2@aar'
从 6.5.1 版本开始,我们额外提供了单一厂商的推送 library,以支持不希望全部集成的产品之需求,新 library 与厂商的对应关系如下:
两组 library 的使用方法基本相同,开发者可以根据自己的需要选取合适的 library。有一点需要注意的是,在 6.5.1 及后续版本的 library 中,由于小米、Oppo、Vivo 并没有将他们的 SDK 包发布到公开源供开发者引用,所以如果是使用这几个厂商的推送,需要开发者将对应的 jar/aar 包(下载地址见这里)手动加入工程中。
华为推送-HMS 版本
环境配置
接入 SDK
获取 HMS SDK
从 6.4.4 版本开始,LeanCloud 混合推送已经升级到华为 PushKit V3 版本,开发者可以参考华为官方文档完成 HMS SDK 的接入。其主要步骤有:
配置 HMS SDK 的 maven 仓库地址。
allprojects/repositories
和buildscript/repositories
中增加仓库地址:maven {url 'http://developer.huawei.com/repo/'}
在 android 中配置签名 将生成签名证书指纹步骤中生成的签名文件拷贝到工程的 app 目录下,在 build.gradle 文件中配置签名:
做完这些修改后,Android Studio 右上方出现「Sync Now」链接。点击「Sync Now」等待同步完成。
修改应用 manifest 配置
首先导入
mixpush-android
包,修改build.gradle
文件,在dependencies
中添加依赖:然后配置相关 AndroidManifest,添加 Permission(开发者要将其中的
<包名>
替换为自己的应用的 package):集成最新的 HMS Core Push SDK 版本后要在 AndroidManifest.xml 文件的 application 节点下参照以下步骤注册 Service,用于接收华为推送的消息与令牌。
具体使用
AVOSCloud.initialize
完成初始化之后,进行混合推送 library 的初始化:mixpush-android
的开发者,调用cn.leancloud.AVMixPushManager.registerHMSPush(context, profile)
完成 HMS 推送的初始化。mixpush-hms
的开发者,调用cn.leancloud.hms.AVMixPushManager.registerHMSPush(context, profile)
完成 HMS 推送的初始化。这里参数
profile
的用法可以参考 Android 混合推送多配置区分。onCreate
方法中调用AVMixPushManager.connectHMS(activity)
,确保 HMS SDK 连接成功。 如果开发者不通过 AppGallery Connect 配置文件来集成,我们也提供了AVMixPushManager.connectHMS(activity, huaweiAppId)
来显式指定华为应用 id 完成连接。LeanCloud 云端只有在满足以下全部条件的情况下才会使用华为推送:
提升透传消息到达率
当使用华为推送发透传消息时,如果目标设备上 App 进程被杀,会出现推送消息无法接收的情况。这个是华为 ROM 对透传消息广播的限制导致的,需要引导用户在华为 「权限设置」中对 App 开启自启动权限来避免。
使用特定 activity 响应推送消息
华为推送消息,在用户点击了通知栏信息之后,默认是打开应用,用户也可以指定特定的 activity 来响应推送启动事件,开发者需要在 manifest 文件的 application 中定义如下的 activity:
在目标 activity 的
onCreate
函数中可以从 intent extra data 中通过content
key 可以获得推送内容(JSON 格式,包含 push 消息中所有自定义属性)。一般情况下,这里 intent-filter 的内容都不需要修改。如果同一开发者有多个应用都使用了我们的 HMS 混合推送,或者终端用户安装了多个使用我们的 HMS 混合推送的应用,那么在同一个终端上,LeanCloud 推送消息在通知栏被点击之后,因为多个应用都响应同样的 intent-filter,所以会出现要选择应用来打开的情况。这可以通过在 intent-filter 中配置不一样的
android:host
解决。在 LeanCloud 控制台,增加华为 HMS 推送配置的时候,开发者可以指定自己的 Android Intent Hostname(不指定就使用默认值cn.leancloud.push
),然后在这里的 intent-filter 中填上同样的值,客户端就可以区分不同应用的通知栏消息了。在 HMS 推送中,只能通过自定义
intent
参数来指定响应 activity 的(具体可参考华为文档服务端发送 push 消息)。LeanCloud 云端在调用 HMS 推送接口的时候,会把开发者自定义的属性,使用固定的 intentUri pattern 来封装成intent
数据,其中intentUri
的固定格式为:其中
{host}
就是上面配置的 Android Intent Hostname,默认值为cn.leancloud.push
;XXX
就是开发者自定义参数的 JSON 字符串做了 URL Encode 之后的值,只有这部分内容是开发者可以指定的。在 LeanCloud 后端发送这种推送的例子如下:
LeanCloud 云端最终发送给 HMS Server 的请求中 payload 字段为(其中
{"k1" : "v1","k2" : "v2"}
这个 JSON 串经过了 URLEncode 处理):到目前为止,我们只支持一种 intentUri 格式,所以所有的推送请求都会被同一个 activity 响应。如果开发者需要最终显示不同的页面,可以由这个接收 activity 进行一次转发。
华为推送自定义 Receiver
如果你想推送消息,但不显示在 Android 系统的通知栏中,而是执行应用程序预定义的逻辑,可以 自定义 Receiver。华为混合推送自定义 Receiver 需要继承 AVHMSMessageService,在收到透传消息的回调方法
onMessageReceived
获取推送消息数据。 你的 Receiver 可以按照如下方式实现:AndroidManifest.xml 中把 AVHMSMessageService 替换为你自定义的 MyHuaweiReceiver。
修改 HMS 推送注册函数。特别注意一点,使用自定义 Receiver 的时候,需要调用
AVMixPushManager.registerHMSPush(context, profile, receiverClazz)
或者AVMixPushManager.registerHMSPush(context, receiverClazz)
来完成 HMS 推送的初始化,否则会导致AVMixPushManager.registerHMSPush
调用失败。推送的内容示例如下:
参考 demo
我们提供了一个 最新的华为推送 demo,可供你在接入过程中参考。
小米推送
环境配置
接入 SDK
我们混合推送基于小米 3.7.5 版本 SDK 进行开发。开发者需要首先导入
mixpush-android
包:修改build.gradle
文件,在 dependencies 中添加依赖:然后配置相关 AndroidManifest。添加 Permission:
添加 service 与 receiver。开发者要将其中的
<包名>
替换为自己的应用对应的 package:具体使用
在
AVOSCloud.initialize
之后调用以下函数进行混合推送 library 的初始化:mixpush-android
的开发者,调用cn.leancloud.AVMixPushManager.registerXiaomiPush(context, miAppId, miAppKey, profile)
。mixpush-xiaomi
的开发者,调用cn.leancloud.mi.AVMixPushManager.registerXiaomiPush(context, miAppId, miAppKey, profile)
。这里:
miAppKey
需要的是 AppKey,而在控制台的混合推送配置中 Profile 的第二个参数是 AppSecret,请注意区分,并分别正确填写。profile
的用法可以参考 Android 混合推送多配置区分。LeanCloud 云端只有在满足以下全部条件的情况下才会使用小米推送:
小米推送通知栏消息的点击事件
当小米通知栏消息被点击后,如果已经设置了 自定义 Receiver,则 SDK 会发送一个 action 为
com.avos.avoscloud.mi_notification_action
的 broadcast。如有需要,开发者可以通过订阅此消息获取点击事件,否则 SDK 会默认打开 启动推送服务 对应设置的 Activity。小米推送国际版的使用
MIUI 国际版也可以使用小米推送,LeanCloud 混合推送也进行了支持。与国内版不同的是,国际版的开发者,在
AVOSCloud.initialize
时需要调用以下函数:之后的使用就和国内版本一样了。
魅族推送
环境配置
接入 SDK
首先导入
mixpush-android
包。修改build.gradle
文件,在 dependencies 中添加依赖:然后配置相关 AndroidManifest。添加 Permission:
添加 service 与 receiver。开发者要将其中的
<包名>
替换为自己的应用对应的 package:具体使用
在
AVOSCloud.initialize
之后调用以下函数进行混合推送 library 的初始化:mixpush-android
的开发者,调用cn.leancloud.AVMixPushManager.registerFlymePush(context, flymeId, flymeKey, profile)
。mixpush-meizu
的开发者,调用cn.leancloud.flyme.AVMixPushManager.registerFlymePush(context, flymeId, flymeKey, profile)
。这里参数
profile
的用法可以参考 Android 混合推送多配置区分。注意,LeanCloud 云端只有在以下三个条件都满足的情况下,才会使用魅族推送。
魅族推送通知栏消息的点击事件
当魅族通知栏消息被点击后,如果已经设置了 自定义 Receiver,则 SDK 会发送一个 action 为
com.avos.avoscloud.flyme_notification_action
的 broadcast。如有需要,开发者可以通过订阅此消息获取点击事件,否则 SDK 会默认打开 启动推送服务 对应设置的 Activity。vivo 推送
我们新推出了支持 vivo 手机的混合推送(基于 vivo 2.9.0.0 版本),欢迎感兴趣的开发者试用,也期待大家给我们更多的反馈。
环境配置
要使用 vivo 官方推送服务,需要在 vivo 开发者平台注册一个账号,并创建好应用。 这里假设大家已经完成上述操作,创建好了应用,并获取了
appId
、appKey
和appSecret
(请保存好这几个值,下一步接入的时候会用到。)接入 SDK
当前版本的 SDK 是基于 vivo 官方文档 push SDK 接入文档 封装而来,使用的 vivo push SDK 基线版本是
2.9.0.0
。我们会结合 demo(源码)来解释整个接入流程。首先将 demo 工程 app/libs 目录下的所有 jar 包(如有)拷贝到目标工程的 libs 目录下,然后修改
build.gradle
文件,在dependencies
中添加依赖:接下来配置 AndroidManifest,添加权限声明:
最后在 AndroidManifest 中添加 service 与 receiver(开发者要将其中的
com.vivo.push.app_id
和com.vivo.push.app_key
替换为自己的应用的信息):接下来我们看看代码上要怎么做。
初始化
与其他推送的初始化方法一样,我们在
Application#onCreate
方法中进行 vivo 推送的初始化:开发者也可以在
onCreate
方法中调用 AVMixPushManager 的其他方法,以使用 vivo 推送的全部客户端功能:添加 vivo 推送配置
在应用控制台 - 消息 - 推送 - 设置 页面开启混合推送服务,并且在「vivo 推送配置」一节设置好准备阶段申请好的「vivo appId」、「vivo appKey」和「vivo Secret」,就可以了。
响应通知栏消息的点击事件
与其他厂商的混合推送机制一样,vivo 混合推送也是通过系统通道来下发消息,开发者调用 push API 发送消息时,其流程为:
com.vivo.pushclient.action.RECEIVE
action 的接收器(如前面 AndroidManifest 里定义的MyPushMessageReceiver
类)。应用需要从混合推送 SDK 中的
AVVIVOPushMessageReceiver
类派生出自己的实现类,在void onNotificationMessageClicked(Context var1, UPSNotificationMessage var2)
方法中响应点击事件,以动态改变展示内容。 下面的例子展示了MyPushMessageReceiver
类的简单示例:这样就完成了 vivo 推送的完整流程。
Oppo 推送
LeanCloud 混合推送/Oppo 模块基于 oppo Push SDK v2.1.0 版本,支持 Android 4.4 或以上版本的手机系统,服务支持信息如下:
在接入时,开发者可以参考我们的源码和 demo:
环境配置
在开始接入之前,有两项准备工作:
这里假设大家已经完成上述操作,创建好了应用,并获取了
appKey
、appSecret
和masterSecret
,请保存好这三个值,下一步接入的时候会用到:appKey
和appSecret
。appKey
和masterSecret
。接入 SDK
下载 SDk
build.gradle
文件,在dependencies
中添加依赖:配置 AndroidManifest.xml
注意:oppo 推送服务SDK 2.1.0 版本支持的最低安卓版本为 Android 4.4 系统(
minSdkVersion="19"
)。增加权限列表(如果应用无透传权限,则不用配置)
推送服务组件注册(如果应用无透传权限,则不用配置)
接下来我们看看代码上要怎么做。
初始化
与其他推送的初始化方法一样,我们在
Application#onCreate
方法中进行 oppo 推送的初始化:开发者也可以在
onCreate
方法中调用 AVMixPushManager 的其他方法,以使用 oppo 推送的全部客户端功能,具体可以参看 AVMixPushManager 的接口文档,或参考官方文档-详细 API 说明 来了解具体信息。添加 oppo 推送配置
在应用控制台 - 消息 - 推送 - 设置 页面开启混合推送服务,并且在「oppo 推送配置」一节设置好准备阶段申请好的「oppo app key」和「oppo master secret」,就可以了。
响应通知栏消息的点击事件
与其他厂商的混合推送机制一样,oppo 混合推送也是通过系统通道来下发消息,开发者调用 push API 发送消息时,其流程为:
LeanCloud 混合推送目前只支持默认动作(启动应用),将来会其他选项。
FCM 推送(仅国际版可用)
FCM 推送仅支持部署在 LeanCloud 国际版上的应用使用。
FCM(Firebase Cloud Messaging)是 Google/Firebase 提供的一项将推送通知消息发送到手机的服务。接入时后台需要配置连接 FCM 服务器需要的推送 key 和证书,FCM 相关的 token 由 LeanCloud SDK 来申请。
环境要求
FCM 客户端需要在运行 Android 4.0 或更高版本且安装了 Google Play 商店应用的设备上运行,或者在运行 Android 4.0 且支持 Google API 的模拟器中运行。具体要求参见 在 Android 上设置 Firebase 云消息传递客户端应用。
接入 SDK
首先导入 avoscloud-fcm 包
修改 build.gradle 文件,在 dependencies 中添加依赖:
下载最新的配置文件并加入项目
从 Firebase 控制台下载最新的配置文件(google-services.json),加入 app 项目的根目录下。
修改应用清单
将以下内容添加至您应用的
AndroidManifest
文件中:AVFirebaseMessagingService
的服务。如果您希望在后台进行除接收应用通知之外的消息处理,则必须添加此服务。要接收前台应用中的通知、接收数据有效负载以及发送上行消息等,您必须继承此服务。AVFirebaseInstanceIdService
的服务,用于处理注册令牌的创建、轮替和更新。如果要发送至特定设备或者创建设备组,则必须添加此服务。default_notification_channel_id
设为您的通知渠道对象的 ID(如下所示);如果传入的消息未明确设置通知渠道,FCM 就会使用此值。build.gradle
中设置minSdkVersion 8
或更高版本。这可确保 Android 应用无法安装在不能让其正常运行的环境中。程序初始化
使用 FCM 推送,客户端程序无需做特别的初始化。如果注册成功,
_Installation
表中应该出现 vendor 这个字段为fcm
的新记录。配置控制台(设置 FCM 的 ProjectId 及 私钥文件)
在 Firebase 控制台 > 项目设置 > 服务账号 > Firebase Admin SDK > 生成新的秘钥 可以获得服务端发送推送请求的私钥文件。将此 文件 及 ProjectId 通过 LeanCloud 控制台 > 消息 > 推送 > 设置 > 混合推送,与 LeanCloud 应用关联。
取消混合推送注册
对于已经注册了混合推送的用户,如果想取消混合推送的注册而改走 LeanCloud 自有的 WebSocket 的话,可以调用如下函数:
此函数为异步函数,如果取消成功会有「Registration canceled successfully」的日志输出,万一取消注册失败的话会有类似「unRegisterMixPush error」的日志输出。
错误排查建议
_Installation
表中的相关记录应该具有 vendor 这个字段并且不为空值。华为推送-老版本(deprecated)
华为已经不再支持老版本的推送服务,请大家尽快切换到 HMS 推送。
环境配置
接入 SDK
首先导入
avoscloud-mixpush
包,修改build.gradle
文件,在dependencies
中添加依赖:注:如果是通过 jar 包导入,则需要手动下载 jar 包:华为 Push SDK。
然后配置相关 AndroidManifest,添加 Permission:
再添加 service 与 receiver。开发者要将其中的
<包名>
替换为自己的应用的 package:具体使用
在
AVOSCloud.initialize
时调用registerHuaweiPush(context, profile)
即可。参数profile
的用法可以参考 Android 混合推送多配置区分。LeanCloud 云端只有在满足以下全部条件的情况下才会使用华为推送:
提升透传消息到达率
当使用华为推送发透传消息时,如果目标设备上 App 进程被杀,会出现推送消息无法接收的情况。这个是华为 ROM 对透传消息广播的限制导致的,需要引导用户在华为 「权限设置」中对 App 开启自启动权限来避免。