uni-push 2.0 快速接入指南
简介
此文档用于帮助开发者快速接入集成 uni-push 2.0 ,若想详细了解可以查看 uni-push 2.0 业务文档 。
名词解释
名词 | 解释 |
---|---|
通知消息 | 指定通知标题和内容后,由个推 SDK 自动处理在系统通知栏中展示通知栏消息,同时响铃或震动提醒用户(响铃和震动受手机系统的设置状态影响)。 |
透传消息 | 即自定义消息,消息体格式客户可以自己定义,如纯文本、json 串等。透传消息个推只传递数据,不做任何处理,客户端接收到透传消息后需要自己去做后续动作处理,如通知栏展示、弹框等。 |
ClientId | 个推业务层中的对外用户标识,用于标识客户端身份,由第三方客户端获取并保存到第三方服务端,是个推 SDK 的唯一识别号,简称 CID、cid。 |
在线推送 | app 在前台打开运行时,通过个推渠道下发消息。 |
离线推送 | app在后台、锁屏、进程关闭时,通过厂商渠道下发消息。若未集成 android 多厂商、未配置 ios 推送证书,则该机型无法使用离线推送。 |
消息下发流程
一、客户端集成
1.1 开通 uni-push 2.0 推送服务
unipush 内部封装好了个推及主流厂商 SDK,开发者在使用前必须开通相关服务。
使用 HBuilder 账号登录 开发者中心 ,创建应用、填写应用信息。
1.2 开通离线厂商推送服务
若未完成开通离线厂商推送,只有在 app 在线时才能收到消息
-
Android 多厂商开通:个推与主流安卓厂商合作融合了厂商推送 SDK,在后台配置 “厂商推送设置” 、并云打包后,可以同时使用 “离线推送”,能提高在安卓厂商设备上的消息到达率。
- 目前华为、荣耀、魅族、oppo(测试环境)不要求上架应用商店;vivo 、小米、oppo(正式环境)必须上架应用商店后才可使用离线厂商推送。
-
iOS 推送证书生成:iOS 支持的推送通知功能,从苹果开发者官网导出证书并配置在后台的 “厂商推送设置” 后,可以同时使用 “离线推送”,能提高在 iOS 设备上的消息到达率。
- iOS 使用推送无需上架 Appstore
-
鸿蒙Next 开通:纯血鸿蒙(HarmonyOS Next)系统的推送,配置鸿蒙Next 参数并进行云打包。
所有的厂商参数都是在下图所示位置配置,配置完成后,需要进行云打包, app 端才会生效:
1.3 云打包
打开 HBuilderX (3.5.1及其以上版本),双击项目中的 “manifest.json” 文件,选择“App 模块配置”,向下找到“Push(消息推送)”,勾选后,点击 “uniPush” 下面配置。
注意:如果云打包不勾选“离线推送”,则打的包是小程序 SDK,仅支持发在线透传消息,不会有通知栏展示。
云打包可以选择”正式包“和”自定义基座包“,开发测试建议使用 ”自定义基座包“。
1.4 集成验证
1.4.1 客户端获取 cid
假如我要给“张三”打电话,那就需要知道对方的电话标识,即电话号码是多少。 同理,要给某个客户端推送消息,也需要知道该设备的客户端推送标识。
启动 app 后成功获取 cid 则说明云打包 “在线推送” 成功,支持在线推送。
先跟着示例代码简单体验,详细的uni.getPushClientId API介绍 详情参考 代码示例:
// uni-app客户端获取push客户端标记,代码可以实现在App.vue中
uni.getPushClientId({
success: (res) => {
let push_clientid = res.cid
console.log('客户端推送标识cid:',push_clientid)
},
fail(err) {
console.log(err)
}
})
1.4.2 校验厂商离线推送是否集成成功
输入上方获取的 cid ,查询到对应的 Device Token 则说明云打包 “离线推送” 成功,同时支持离线推送。
如果未查询到 device token,则只能 “在线推送” 。若需要使用 “离线推送” 请重新检查 ”1.2 开通离线厂商推送服务“ 。
二、服务端推送消息
注意:使用 uni-push 2.0,服务端不支持用个推 api 推送,只能用 dcloud 提供的 服务端(云函数)推送 。
2.1 云函数创建
注意:扩展库依赖 3 张 opendb 表:opendb-tempdata
,opendb-device
,uni-id-device
。公测版 uniCloud,执行扩展库会自动创建。如果你使用的是 uniCloud 正式版需要自己在 uniCloud
的 web控制台 创建这3张表。
示例如下:
2.2 云函数执行
在云函数文件目录右键(或按快捷键ctrl + r)-> 上传并运行云函数
,此时你的客户端将收到推送消息(应用关闭时为通知栏消息,在线时代码监听到推送消息)。
云函数中调用uni-cloud-push扩展库的sendMessage方法,向客户端推送消息
// 简单的使用示例
'use strict';
const uniPush = uniCloud.getPushManager({appId:"__UNI__XXXXXX"}) //注意这里需要传入你的应用appId
exports.main = async (event, context) => {
return await uniPush.sendMessage({
"push_clientid": "xxx", //填写上一步在uni-app客户端获取到的客户端推送标识push_clientid
"force_notification":true, //填写true,客户端就会对在线消息自动创建“通知栏消息”。
"title": "通知栏显示的标题",
"content": "通知栏显示的内容",
"payload": {
"text":"体验一下uni-push2.0"
},
"category": {
//HarmonyOS NEXT系统(纯血鸿蒙、非安卓鸿蒙)的消息分类,要给鸿蒙设备推送时才必传
"harmony":"MARKETING"
},
"options":{
"HW": {
// 值为int 类型。1 表示华为测试消息,华为每个应用每日可发送该测试消息500条。此 target_user_type 参数请勿发布至线上。
"/message/android/target_user_type":1
} ,
"HO": {
//值为int 类型。1 表示测试推送,不填默认为0。荣耀每个应用每日可发送该测试消息1000条。此测试参数请勿发布至线上。
"/android/targetUserType": 1
} ,
"VV": {
//值为int 类型。0 表示正式推送;1 表示测试推送,不填默认为0。此 pushMode 参数请勿发布至线上。
"/pushMode":1
} ,
"XM": {
//新小米消息分类下,私信公信id都必须要传,否则请求小米厂商接口会被拦截
"/extra.channel_id": "填写小米平台申请的渠道id"
}
}
})
};
若使用vivo测试推送( "/pushMode":1 ),额外需要先在 vivo 开放平台 录入测试用户。华为不需要录入。
在线消息无额度限制。离线推送各厂商的限额(包含 extra.channel_id 如何申请),详见: 厂商通道限额
HarmonyOS NEXT系统(纯血鸿蒙、非安卓鸿蒙)的消息分类,harmony取值参考 云端通知category取值
如果你希望当应用在线时,也通过“通知栏消息”来提醒用户;可以通过以下两种方式实现:
- 监听到消息内容后,根据业务需要自己判断是否要创建“通知栏消息”,需要就调用创建本地消息API uni.createPushMessage手动创建通知栏消息。
- 服务端执行推送时,传递参数
force_notification:true
,客户端就会自动创建“通知栏消息”(此时你监听不到消息内容),当用户点击通知栏消息后,APP才能监听到消息内容。
先跟着示例代码简单体验,详细的 uniPush.sendMessage API介绍 详情参考
检查确认当前 app 的通知栏权限开启后,则可以开始进行推送测试。
2.2.1 测试在线推送,打开 app 在前台时进行推送
2.2.2 测试离线推送,关闭 app 进程时进行推送
2.2.3 手机成功收到消息展示
恭喜您,如果您已经成功收到 在线 和 离线 的消息展示,那说明已经集成推送成功啦!
2.3 云函数 URL 化 (可选)
在 uniCloud 的云函数中,加载扩展库 uni-cloud-push
,直接调用相关 API,无需额外的服务端配置。
传统服务器开发者(例如:Java、php、python等)需要把这个 云函数URL化 后变成 http 接口,再由代码调用这个 http 接口。
云函数URL化 步骤简介----------->
1,上传步骤云函数代码
2,云函数URL化
3,api 工具测试请求(单推示例)
4,云函数代码示例
// 简单的使用示例
'use strict';
const uniPush = uniCloud.getPushManager({
appId: "你的__UNI__开头的AppId"
})
exports.main = async (event) => {
let obj = JSON.parse(event.body)
const res = await uniPush.sendMessage({
"push_clientid": obj.cids, // 设备id,支持多个以数组的形式指定多个设备,如["cid-1","cid-2"],数组长度不大于1000
"title": obj.title, // 标题
"content": obj.content, // 内容
"payload": obj.payload, // 数据
"category": obj.category, // HarmonyOS NEXT系统(纯血鸿蒙、非安卓鸿蒙)的消息分类,要给鸿蒙设备推送时才必传
"force_notification": true, //填写true,客户端就会对在线消息自动创建“通知栏消息”,不填写则需要客户端自己处理。
"request_id": obj.request_id ,//请求唯一标识号,10-32位之间;如果request_id重复,会导致消息丢失
"options":obj.options //消息分类,没申请可以不传这个参数
})
return res;
};
注意:如果推送时不传入 cid,则发送的是全推(给所有用户推)消息。全推每分钟不能超过5次,10分钟内不能推重复消息体 。 通过返回值中的 taskid 几个首字母可以判断是什么推送。RASS:单推、 RASL:批量推、 RASA:全推
5,postman请求示例
{
"request_id": "212320028909901111",
"cids": "此处填写自定义打包获取的clientid参数",
"title": "通知标题",
"content": "通知内容 ",
"options": {
"HW": {
// 值为int 类型。1 表示华为测试消息,华为每个应用每日可发送该测试消息500条。此 target_user_type 参数请勿发布至线上。
"/message/android/target_user_type": 1
},
"HO": {
//值为int 类型。1 表示测试推送,不填默认为0。荣耀每个应用每日可发送该测试消息1000条。此测试参数请勿发布至线上。
"/android/targetUserType": 1
},
"VV": {
//值为int 类型。0 表示正式推送;1 表示测试推送,不填默认为0。此 pushMode 参数请勿发布至线上。
"/pushMode": 1
},
"XM": {
//新小米消息分类下,私信公信id都必须要传,否则请求小米厂商接口会被拦截
"/extra.channel_id": "填写小米平台申请的渠道id"
}
},
"category": {
//HarmonyOS NEXT系统(纯血鸿蒙、非安卓鸿蒙)的消息分类,要给鸿蒙设备推送时才必传
"harmony":"MARKETING"
},
//payload是点击通知栏消息后,传给客户端click回调的自定义参数
"payload": {
"data1": 1,
"data2": 2
}
}
三、客户端接收消息
3.1 客户端监听推送消息
如果您需要对接收到的消息进行自定义处理,可以再阅读一下本文开头的 “消息下发流程图”。
客户端监听推送消息的代码,需要在收到推送消息之前被执行。所以应当写在应用一启动就会触发的 应用生命周期 onLaunch
中。
示例代码:
//文件路径:项目根目录/App.vue
export default {
onLaunch: function() {
console.log('App Launch')
uni.onPushMessage((res) => {
// 监听通知栏消息的点击
if(res.type == 'click'){
// 如果需要跳转app内指定页面,则自己实现下方的跳转代码。
uni.navigateTo({
//页面路径示例值:/pages/pushinfo/pushinfo
url:'指定页面路径'
})
}
// 监听在线推送消息,若云函数设置了 "force_notification":true,则不会触发此 receive。
if(res.type == 'receive'){
console.log("接收到的消息内容",res.payload);
}
})
},
onShow: function() {
console.log('App Show')
},
onHide: function() {
console.log('App Hide')
}
}
先跟着示例代码简单体验,详细的 uni.onPushMessage API介绍 详情参考
四、注意事项
4.1 合规上架
app 若需要上架应用商店,须配置 隐私弹窗 提示用户。
4.2 帮助中心
当您在集成推送服务遇到问题时:
先仔细阅读此接入指南及对应的集成文档,查看是否有遗漏。
阅读 uni-push2.0 常见问题 ,查看是否能解决。