您正在浏览的是老版uni-push1.0的文档,仅为旧项目保留。新项目推荐使用更强大的新版uni-push2.0详情查看
从HBuilderX 2.0.3 起,uni-app、5+App、wap2app均支持UniPush
从HBuilderX2.7.10开始,支持谷歌FCM,参考:https://ask.dcloud.net.cn/article/37356
概述
产品介绍
UniPush 是 DCloud 联合个推公司推出的集成型统一推送服务,内建了苹果、华为、小米、OPPO、VIVO、魅族、谷歌 FCM 等手机厂商的系统级推送和个推等第三方推送。
国内Android的Push是一个混乱的世界,因为 Google 的 Push 服务 FCM 被墙,所以一些国内的安卓手机厂商各自做了自己的推送,比如华为、小米、OPPO、VIVO、魅族等,但还有很多国产手机厂商没有提供官方推送方案。三方独立公司如个推,则提供了独立的 push 方案。
在没有 uniPush 以前,如果只使用三方 push,会在很多国产手机上因为节电设置而无法保活 push 进程,导致无法推送。
而如果每个安卓手机的官方 Push SDK 都集成开发一遍,这么多平台,工作量会非常巨大,管理维护也很麻烦。
uniPush 解决了这个难题,开发者只需要开发一次。系统会自动在不同手机上选择最可靠的推送通道发送 push 消息,保障送达率。
UniPush 即降低了开发成本、又提高了 push 送达率,并且免费,是当前推送的最佳解决方案。
常见答疑
有了 unipush,开发者不应该再使用其他 push 方案了。但我们发现很多开发者有误解,导致还在错误使用其他推送。
-
常见误解 1:“uniPush的专业性,和专业的个推、极光等服务可相比吗?”
答:uniPush 是由个推将其本来收费的 vip push 产品,免费提供给了 DCloud 的开发者。它与个推 vip push 的只有 2 个区别:
- 免费
- 账户使用的是 DCloud 开发者账户,而无需再重新注册个推账户。个推是A股上市公司,专业性在推送领域领先。
-
常见误解 2:“uniPush好麻烦,我就喜欢个推、极光这种简单 sdk,不想去各个 rom 厂商去申请一圈”
答:uniPush不建立在申请手机厂商授权的基础上,如果你不申请那些,使用起来和用普通的个推是一样的。但是要特别注意,推送行业的现状就是:不集成rom厂商的推送,就无法在App离线时发送push。。按照普通个推模式使用,后果就是在华为、小米、OPPO、VIVO、魅族上发不了离线消息。 -
常见误解 3:“uniPush的送达率还是不够,是否可以付费来提升送达率,个推是有付费提升送达率的方法的”
答:前文已经说了。个推的付费提升送达率的产品就是 vip push,而uniPush就是个推的 vip Push。DCloud 通过谈判免费给 DCloud的开发者使用了。 -
常见误解 4:开通 uniPush 要实名认证,还得传身份证,开通普通个推不用这么麻烦。
答:此问题之前曾存在,后来已经处理,保持和个推需要的身份信息相同,不再需要身份证。
技术架构
名词解释
名词 | 解释 |
---|---|
通知消息 | 指定通知标题和内容后,由个推SDK自动处理在系统通知栏中展示通知栏消息,同时响铃或震动提醒用户(响铃和震动受手机系统的设置状态影响)。 |
透传消息 | 即自定义消息,消息体格式客户可以自己定义,如纯文本、json 串等。透传消息个推只传递数据,不做任何处理,客户端接收到透传消息后需要自己去做后续动作处理,如通知栏展示、弹框等。 |
ClientId | 个推业务层中的对外用户标识,用于标识客户端身份,由第三方客户端获取并保存到第三方服务端,是个推 SDK 的唯一识别号,简称 CID。 |
在线推送 | app 在前台打开运行时,通过个推渠道下发消息。 |
离线推送 | app在后台、锁屏、进程关闭时,通过厂商渠道下发消息。若未集成 android 多厂商、未配置 ios 推送证书,则该机型无法使用离线推送。 |
更多名词解释参考:个推名词解释
消息推送流程
一、客户端集成
1.1 开通 unipush 推送服务
unipush 内部封装好了个推及主流厂商 SDK,开发者在使用前必须开通相关服务:点此查看如何开通UniPush推送服务 。
完成以上步骤后,ios 支持在线、离线推送;android 仅支持在线推送。
1.2 开通离线厂商推送服务
若需要支持主流 android 厂商客户端接收离线推送,您需要完成 :android 多厂商配置 。
配置好厂商参数后请一定要提交云打包,并且使用“自有证书”打签名包;将云打包后的安装包安装到手机上,再获取cid 进行离线厂商推送测试,不可使用基座方式获取的 cid 进行离线厂商推送测试。
注意事项:
- 目前华为、小米、魅族、oppo(beta环境)不需要发布应用市场上就可使用离线离线推送,vivo 需要上架后才能使用。
1.3 集成验证
1.3.1 cid 获取
在应用安装后第一次运行时应该调用 5+ API 的 plus.push.getClientInfoAsync 方法获取客户端标识。
如果获取的 cid 为空,说明客户端向推送服务器注册还未完成,可以使用 setTimeout 延时重试。
plus.push.getClientInfoAsync((info) => {
let cid = info["clientid"];
});
1.3.2 确认离线厂商是否可用
若不需要使用离线推送,则可忽略此步骤。
在【Uni Push】-【配置管理】-【故障排查】-【 状态查询】中输入CID 查询,看是否会返回 devicetoken 。

若返回 devicetoken :
可以开始进行离线推送测试。
若未返回 devicetoken :
说明当前未正常集成厂商,无法使用离线推送功能。
- 检查后台是否有配置厂商参数(配置完参数需要云打包后生效)
华为(包含荣耀)机型需要额外检查:
- 需要在华为开发者后台配置正确的 sha256 指纹证书
- 云打包用自有证书打正式签名包
- 华为开发者后台包名跟客户端包名需要保持一致
- 厂商推送设置-华为厂商,必须上传agconnect-services.json
- 在华为平台是否开通了华为推送服务
- 保存完参数,需要重新提交云端打包
特别注意
华为厂商平台更换应用包名或者证书时,需要同步更新云端的agconnect-services.json和包名等信息,否则将导致打包失败。
二、服务端推送消息
开发者可通过以下三种方式推送消息,选择其中一种即可。
若您在测试过程中遇到无法收到推送的情况,请先按照 Unipush常见问题 中的排查思路自助排查一下,例如常见问题:安卓离线收不到通知 。
2.1 开发者中心后台Web页面推送
登录 DCloud开发者中心,在“我的应用”列表中选择应用,上方选择“Uni Push”选项,打开消息推送页面。
测试在线通知消息推荐您使用:
测试离线通知消息推荐您使用:
2.2 个推服务端 api 推送
2.2.1 服务端消息下发流程(必读)
-
当 CID 在线(即 app 在前台打开运行)时:
消息通过个推通道下发到客户端,具体到服务端 Rest-V2 代码中,即 push_message 中的 notification(通知) 或 transmission(透传) 内容传递给客户端。
-
当 CID 离线(即 app 在后台、锁屏、进程关闭)时:
有开启对应厂商离线功能的,消息将通过个推侧请求对应厂商侧的服务端,具体到服务端 Rest-V2 代码中,即 push_channel 中的通知内容传递给厂商,实际的消息是经由厂商服务器下发至客户端;若服务端 push_channel 不传值,则无法接收离线消息。
对于没有开启对应厂商功能的,消息将存在个推的离线库中,等待 CID 在线,再通过个推通道下发到客户端。
2.2.2 服务端api使用
个推服务端接口文档可查看:服务端 RestAPI V2 ,支持以下 2 种方式调用,选择其中一种即可,推荐您使用 Http 请求。
服务端集成时首先需要获取 AppId、AppKey、MasterSecret 参数,登录 DCloud开发者中心 ,在“Uni Push”下的“应用配置”页面中获取,如下图所示:
Http 请求:参数详情可查看:服务端 RestAPI V2
参数示例:
{
"request_id": "请填写10到32位的id",
"audience": {
"cid": [
"请输入clientid"
]
},
"settings": {
"ttl": 3600000,
"strategy": {
"default": 1
}
},
"push_message": {
//此格式的透传消息由 unipush 做了特殊处理,会自动展示通知栏。开发者也可自定义其它格式,在客户端自己处理。
"transmission": "{title:\"标题\",content:\"内容\",payload:\"自定义数据\"}"
},
"push_channel": {
"android": {
"ups": {
"notification": {
"title": "安卓离线展示的标题",
"body": "安卓离线展示的内容",
"click_type": "intent",
//注意:intent参数必须按下方文档(特殊参数说明)要求的固定格式传值,intent错误会导致客户端无法收到消息
"intent": "请填写固定格式的intent"
}
}
},
"ios": {
"type": "notify",
"payload": "自定义消息",
"aps": {
"alert": {
"title": "苹果离线展示的标题",
"body": "苹果离线展示的内容"
},
"content-available": 0,
"sound": "default"
},
"auto_badge": "+1"
}
}
}
SDK集成:
个推服务端 SDK 的主要目标是提升开发者在服务端集成个推推送服务的开发效率。 开发者不需要进行复杂编程即可使用个推推送服务的各项常用功能,SDK 可以自动帮您满足调用过程中所需的鉴权、组装参数、发送HTTP请求等非功能性要求,目前仅支持 Java 和 PHP 语言。
在使用以下代码前请先查看 个推服务端 Java SDK ,配置使用最新版 SDK 。若您想查看详细的字段描述,或者想集成 PHP SDK 可查看:服务端 RestAPI V2 。
Java SDK 参数示例:
import com.getui.push.v2.sdk.ApiHelper;
import com.getui.push.v2.sdk.GtApiConfiguration;
import com.getui.push.v2.sdk.api.PushApi;
import com.getui.push.v2.sdk.common.ApiResult;
import com.getui.push.v2.sdk.dto.req.Audience;
import com.getui.push.v2.sdk.dto.req.Settings;
import com.getui.push.v2.sdk.dto.req.message.PushChannel;
import com.getui.push.v2.sdk.dto.req.message.PushDTO;
import com.getui.push.v2.sdk.dto.req.message.PushMessage;
import com.getui.push.v2.sdk.dto.req.message.android.AndroidDTO;
import com.getui.push.v2.sdk.dto.req.message.android.ThirdNotification;
import com.getui.push.v2.sdk.dto.req.message.android.Ups;
import com.getui.push.v2.sdk.dto.req.message.ios.Alert;
import com.getui.push.v2.sdk.dto.req.message.ios.Aps;
import com.getui.push.v2.sdk.dto.req.message.ios.IosDTO;
import java.util.Map;
public class UnipushTest {
public static void main(String[] args) {
GtApiConfiguration apiConfiguration = new GtApiConfiguration();
//填写应用配置,参数在“Uni Push”下的“应用配置”页面中获取
apiConfiguration.setAppId("请填写AppId");
apiConfiguration.setAppKey("请填写AppKey");
apiConfiguration.setMasterSecret("请填写MasterSecret");
apiConfiguration.setDomain("https://restapi.getui.com/v2/");
// 实例化ApiHelper对象,用于创建接口对象
ApiHelper apiHelper = ApiHelper.build(apiConfiguration);
// 创建对象,建议复用。目前有PushApi、StatisticApi、UserApi
PushApi pushApi = apiHelper.creatApi(PushApi.class);
//根据cid进行单推
PushDTO<Audience> pushDTO = new PushDTO<Audience>();
// 设置推送参数,requestid需要每次变化唯一
pushDTO.setRequestId(System.currentTimeMillis() + "");
Settings settings = new Settings();
pushDTO.setSettings(settings);
//消息有效期,走厂商消息必须设置该值
settings.setTtl(3600000);
//在线走个推通道时推送的消息体
PushMessage pushMessage = new PushMessage();
pushDTO.setPushMessage(pushMessage);
//此格式的透传消息由 unipush 做了特殊处理,会自动展示通知栏。开发者也可自定义其它格式,在客户端自己处理。
pushMessage.setTransmission(" {title:\"标题\",content:\"内容\",payload:\"自定义数据\"}");
// 设置接收人信息
Audience audience = new Audience();
pushDTO.setAudience(audience);
audience.addCid("请填写cid");
//设置离线推送时的消息体
PushChannel pushChannel = new PushChannel();
//安卓离线厂商通道推送的消息体
AndroidDTO androidDTO = new AndroidDTO();
Ups ups = new Ups();
ThirdNotification thirdNotification = new ThirdNotification();
ups.setNotification(thirdNotification);
thirdNotification.setTitle("安卓离线展示的标题");
thirdNotification.setBody("安卓离线展示的内容");
thirdNotification.setClickType("intent");
//注意:intent参数必须按下方文档(特殊参数说明)要求的固定格式传值,intent错误会导致客户端无法收到消息
thirdNotification.setIntent("请填写固定格式的intent");
androidDTO.setUps(ups);
pushChannel.setAndroid(androidDTO);
//ios离线apn通道推送的消息体
Alert alert = new Alert();
alert.setTitle("苹果离线通知栏标题");
alert.setBody("苹果离线通知栏内容");
Aps aps = new Aps();
aps.setContentAvailable(0);
aps.setSound("default");
aps.setAlert(alert);
IosDTO iosDTO = new IosDTO();
iosDTO.setAps(aps);
iosDTO.setType("notify");
pushChannel.setIos(iosDTO);
pushDTO.setPushChannel(pushChannel);
// 进行cid单推
ApiResult<Map<String, Map<String, String>>> apiResult = pushApi.pushToSingleByCid(pushDTO);
if (apiResult.isSuccess()) {
// success
System.out.println(apiResult.getData());
} else {
// failed
System.out.println("code:" + apiResult.getCode() + ", msg: " + apiResult.getMsg());
}
}
}
2.2.3 特殊参数说明
2.2.3.1 Intent
鉴于各厂商SDK打开应用自定义页面有多种方式,且有些方式互不兼容,为了保持统一并且方便开发者,个推提供一种标准且唯一的打开App 内自定义页面方式,通过服务端 API 指定 intent 参数。
使用厂商推送下发推送消息必须设置 intent,该数据格式是Android原生Intent对象序列化由来。具体可参考 详情。并且intent须符合以下格式,此格式时在个推定义额基础上二次封装,所以必须以此格式为准。不按此格式设置 intent 可能出现用户点击推送消息无法启动App 的问题,并且离线情况下click事件无法得到响应。
intent 数据格式如下:
intent://io.dcloud.unipush/?#Intent;scheme=unipush;launchFlags=0x4000000;component=io.dcloud.HBuilder/io.dcloud.PandoraEntry;S.UP-OL-SU=true;S.title=测试标题;S.content=测试内容;S.payload=test;end
注意事项:
component=io.dcloud.HBuilder/io.dcloud.PandoraEntry,其中 io.dcloud.HBuilder 为 App 包名,需要替换为自己 App 的包名,与 App 云端打包界面设置的 Android 包名一致。
其它说明:
- S.title=的值为推送消息标题,对应5+ API中 PushMessage 对象的 title 属性值。
- S.content=的值为推送消息内容,对应5+ API中 PushMessage 对象的 content 属性值。
- S.payload=的值为推送消息的数据,对应5+ API中 PushMessage 对象的 payload 属性值。
- launchFlags=0x4000000字段,是为了解决接收多条通知后点击可能无法触发 click 事件的问题。
2.2.3.2 特殊透传消息
UniPush推送服务对透传消息的数据符合以下格式时做了特殊处理,会将如下格式的透传消息,直接在通知栏中展示通知。
注意事项:
- 只适用于安卓,ios 仍需要开发者手动在 receive 透传回调中创建通知;
- 下列格式的透传消息,消息到达时不会进入 receive 回调,只有点击消息激活 App 时触发"click"事件。
{"title": "xxx","content": "xxx","payload": "xxx"}
2.3 uniCloud开发服务器
使用封装好的服务器端开发易用插件,详情可查看:uniPush的uniCloud版【V2】
三、客户端处理推送消息
3.1 支持消息范围
客户端 | 个推通知 | 个推透传 | 厂商通知 | 厂商透传 |
---|---|---|---|---|
android | 支持 | 支持 | 支持 | 不支持 |
ios | 不支持 | 支持 | 支持 | 不支持 |
3.2 客户端 api
3.2.1 消息处理
UniPush 推送服务已经封装好 iOS&Android 平台的原生集成工作,开发者只需要调用 JS 代码处理推送消息的业务逻辑。
若您需要在客户端接收处理推送 UniPush 推送内容,请先阅读了解此对接指南开头的 “消息推送流程”,客户端回调处理可参考:在 uni-app 中使用 UniPush 。
注意事项:
- 由于 ios 系统的限制,ios app 在线时,只能推送透传消息。需要开发者在客户端 receive 透传回调中,接收透传消息并根据自身业务场景进行消息的展示方式处理,默认不处理的话是没有任何展示的,透传消息个推只负责传递。
其它
- 使用条件编译直接调用 5+ Push 接口,参考5+ APP推送开发指南
- uni 的客户端 js api 仍然是 plus.push,之前使用 plus.push 开发的代码仍然可以使用。
3.2.2 应用桌面图标的角标
对于支持角标设置的机型,app 在线推送时可调用 5+ API plus.runtime.setBadgeNumber 设置或清零角标。
Android 平台
不同 ROM 接收推送消息对桌面图标的角标处理逻辑存在差别,安卓厂商离线角标支持情况如下:
-
oppo/魅族,部分手机系统上能设置角标圆点,没有数字角标的功能。
-
小米系统自带离线通知数字角标展示功能,默认+1处理,打开清零。
-
vivo高版本系统自带离线通知数字角标展示功能,默认+1处理,打开清零,低版本没有角标功能。
-
华为角标需服务端api进行字段设置,客户端需要手动设置角标数为0
-
add方式支持版本: EMUI版本8.0.0且推送服务应用版本 8.0.0及以上
-
服务端 rest-v2 设置示例,注意Unipush用户的class的值请固定使用'io.dcloud.PandoraEntry'
{ "android": { "ups": { "notification": { // ...其他push_channel参数略 }, "options": { "HW": { "/message/android/notification/badge/class": "io.dcloud.PandoraEntry", "/message/android/notification/badge/add_num": 1 } } } } }
-
iOS 平台
根据接收到的推送消息处理桌面图标的角标,在uniPush后台的“iOS配置”项中可配置 badge 参数对角标进行设置,可取值:
- “+1”,表示当前角标+1;
- “-1”,表示当前角标-1(角标>=0);
- “3”,表示指定角标值,值必须>=0。
默认(不设置badge参数)则角标数字不变,也可以在应用运行期调用5+ API plus.runtime.setBadgeNumber 动态设置角标数字。
注意事项
推送通道选择逻辑
-
Android平台
APP在线(个推推送通道可用)
推送通知和透传消息都使用个推的推送通道下发推送消息。
APP离线(个推推送通道不可用)
推送通知,使用个推离线推送通道,离线消息会存储在消息离线库,离线时间内APP在线后下发推送消息。
透传消息,如果符合厂商推送的厂商手机(配置了手机厂商推送参数并且在对应厂商的手机上),则使用厂商推送通道下发推送消息;否则使用个推的离线推送通道,离线消息会存储在消息离线库,离线时间内APP在线后下发推送消息。 -
iOS平台
推送通知,uniPush后台管理界面中不支持下发此类型,个推提供的服务端API支持下发推送通知(设置APN参数则通过苹果的APNS通道,否则使用个推通道)。
透传消息,设置APN参数则通过苹果的APNS通道下发推送消息,没有设置APN参数则使用个推的推送通道下发。
Android平台厂商通道
华为厂商通道
在华为手机上必须安装“华为移动服务”才能使用华为的厂商推送通道,首先确保手机上已经安装“华为移动服务”应用。
如果在华为手机应用退出后无法接收到推送消息,需要确保:
- 机型版本要求:华为rom且华为rom版本大于等于 emui4.1, 华为移动服务(可在应用列表或华为应用市场中查看)版本大于等于 2.5.2。
- 需要提交云打包,打自有证书-签名包(包名要确认与华为平台一致)。
- 华为平台【我的项目】-【项目设置】-【常规】中填写“SHA256证书指纹”,点右侧对勾保存证书指纹。
- emui10的华为手机,检查手机通知权限设置,将【营销通知】的权限也打开,不要默认静默,静默的话是需要下拉通知栏才能看到。
- 手机通知栏消息是否有存满,清除已存的通知栏消息看下新的消息是否能展示。
- 清除华为移动服务(HMS Core)(apk(手机设置--应用--应用管理--点击显示系统进程--搜索(华为移动服务)--存储--清空缓存))的缓存
HBuilderX3.0.7 之后,华为除了配置原有的厂商信息之外,需要新增配置 agconnect-services.json文件。
该文件,需要从华为开发者后台--项目设置界面下载
VIVO厂商通道
需要在VIVO应用商店上线才能申请VIVO的厂商推送
注意事项:
- vivo【运营消息】,一个设备一天只能收到5条离线消息
- vivo要求:通知文案中不能带 “包含测试、test字符”、“纯数字”、“纯表情”、“符号”或者“符号+数 字”、“表情+数字”、“表情+符号” 。
- 1个自然日内相同文案的运营消息给同个设备发,vivo会在客户端做去重处理,导致消息不展示
- 支持vivo推送功能HBuilderX最低版2.1.0及以上。
具体请参考图中数据
OPPO厂商通道
需要在OPPO应用商店上线才能申请OPPO的厂商推送
并且有以下要求:
- 机型系统要求:oppo colorOS rom且版本号大于等于3.1
- 检查手机通知权限是否打开,oppo是默认关闭的,将通知权限下的【Default】通道权限也打开。
- 手机系统时间是否正常
小米厂商通道
- 机型版本要求:小米rom且小米服务框架(包名:com.xiaomi.xmsf)版本号⼤于等于 105
- 检查手机通知权限设置,小米有不重要通知功能,部分消息可能会存在通知栏不重要通知里
魅族厂商通道
- 机型版本要求:魅族rom且魅族rom版本⼤于等于5.x
- 检查消息是否存入了魅族手机右上角【魅族消息盒子】中
- 清除缓存:魅族手机在设置 ---> 应用管理 ---> 所有应用 ---> 推送服务 ,点击里面的清除数据,然后再重新安装一下应用。
谷歌FCM通道
需Android手机已经安装GMS,且手机网络可以连通谷歌FCM推送服务器。
详细教程另见:https://ask.dcloud.net.cn/article/37356。
其它厂商通道
如果应用在线可以接收到推送消息,离线时使用厂商通道无法接收到推送消息,可参考UniPush厂商通道常见问题https://ask.dcloud.net.cn/article/36611
最后也可以登录个推官网,或使用微信扫描下面二维码,进行技术咨询
其他相关资源
- 检查应用是否被授予推送权限:https://ext.dcloud.net.cn/plugin?id=594
- 开启关闭推送服务:https://ext.dcloud.net.cn/plugin?id=727
- 自定义推送铃声:https://ext.dcloud.net.cn/plugin?id=7482
- 如何自定义推送通知的图标:https://uniapp.dcloud.net.cn/tutorial/app-push-unipush.html#unipush-icons
FAQ
-
Q:5+app和wap2app需要uniPush怎么办?
A:HBuilderX 2.0.3起,5+app和wap2app也支持了uniPush。
5+app和wap2app升级uniPush不需要改动app前端代码,只需要在HBuilderX中打开manifest.json的“SDK配置”页,在“推送”下勾选“DCloud UniPush”,并点击“配置”,在后台开通unipush服务,配置好厂商推送参数重新提交云端打包即可。后端服务器需要参考第二步对接个推推送服务。 -
Q:离线打包如何配置?
A:Android平台App离线打包-Push
iOS平台App离线打包-Push -
Q:iOS平台如何实现应用启动后不立即弹出“发送通知”系统授权框?
A:参考:https://ask.dcloud.net.cn/article/36955