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
参数统一配置在下图所示位置，且云打包后 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 常见问题 ，查看是否能解决。
