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 在线时才能收到消息
所有的厂商参数都是在下图所示位置配置，配置完成后，必须进行云打包， app 端才会生效

Android 多厂商开通：个推与主流安卓厂商合作融合了厂商推送 SDK，在后台配置 “厂商推送设置” 、并云打包后，可以同时使用 “离线推送”，能提高在安卓厂商设备上的消息到达率。
- 目前华为、荣耀、魅族、oppo（测试环境）不要求上架应用商店；vivo 、小米、oppo（正式环境）必须上架应用商店后才可使用离线厂商推送。
iOS 推送证书生成：iOS 支持的推送通知功能，从苹果开发者官网导出证书并配置在后台的 “厂商推送设置” 后，可以同时使用 “离线推送”，能提高在 iOS 设备上的消息到达率。
- iOS 使用推送无需上架 Appstore
鸿蒙Next 开通：纯血鸿蒙(HarmonyOS Next)系统的推送，配置鸿蒙Next 参数并进行云打包。

1.3 云打包

uni-app 框架App端

打开 HBuilderX (3.5.1及其以上版本)，双击项目中的 “manifest.json” 文件，选择“App 模块配置”，向下找到“Push(消息推送)”，勾选后，点击 “uniPush” 下面配置。

注意：如果是 APP 集成推送，云打包请一定要勾选“离线推送”。如果不勾选“离线推送”，则打的包是小程序 SDK（小程序 SDK无法在 app 上稳定使用），且仅支持发在线透传消息，不会有通知栏展示。

uni-app x 框架的App端

标准基座不包含uni-push模块，如果需要使用此模块，应当在提交云打包时，项目代码中包含uni-push相关客户端api。点此了解 uni-app x的摇树机制

所以在开发调试时，需要先写一段包含uni-push相关客户端api代码，再打一个自定义基座。

例如先添加如下代码：

uni.getPushClientId({  
    success: (res) => {  
        let push_clientid = res.cid  
        console.log('客户端推送标识cid:',push_clientid)  
    },  
    fail(err) {  
        console.log(err)  
    }  
})

注意：此时由于运行的标准基座中，不包含uni-push模块，如果运行会报错，不用着急继续往下操作

点击菜单栏的【发行】-【原生APP-云打包】然后再弹出的窗口中勾选【制作自定义调试基座】- 点击【打包】
打包成功后，点击菜单栏的【运行】-【运行到手机或模拟器】-【运行到 Android App 基座】然后再弹出的窗口中勾选【使用自定义基座运行】-【运行】
接下来即可使用 uni-push 相关客户端 api

必须操作：云打包

必须填写自己的包名，进行云打包，下一步获取的才是属于自己应用的 cid。否则无法推送
云打包可以选择”正式包“和”自定义基座包“，开发测试建议使用 ”自定义基座包“。

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": "通知栏显示的内容",  
        "settings": {  
            //消息有效期设置，单位毫秒，-1表示不设离线。默认是 2 小时，取值范围：-1 ～ 3 * 24 * 3600 * 1000(3天)之间  
            "ttl":86400000  
        },  
        "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"   
              }    
        }  
    })  
};

注意：非OPPO、VIVO软件商店官方渠道下载的应用，厂商不提供公信消息服务。
vivo、oppo 对接离线推送时，可以暂时发送测试消息，额外需要分别在 vivo 开放平台、 oppo开放平台录入测试用户（regid 对应个推cid 绑定的 device token，可以从个推后台的“故障排查”中查询 cid 信息获取）。

在线消息无额度限制。离线推送各厂商的限额（包含 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, // 内容  
        "settings": obj.settings, // 消息有效期  
        "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": "通知内容 ",  
    "settings": {  
        //消息有效期设置，单位毫秒，-1表示不设离线。默认是 2 小时，取值范围：-1 ～ 3 * 24 * 3600 * 1000(3天)之间  
        "ttl": 86400000  
        },  
    "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')  
    }  
}

如果要在receive回调里面，自己创建通知栏消息展示，可以调用 createMessage

先跟着示例代码简单体验，详细的 uni.onPushMessage API介绍详情参考