uni-push 2.0 快速接入指南

简介

此文档用于帮助开发者快速接入集成 uni-push 2.0 ，若想详细了解可以查看 uni-push 2.0 业务文档 。

名词解释

消息下发流程

一、客户端集成

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"  
        },  
        "options":{  
            "HW": {      
                 // 值为int 类型。1 表示华为测试消息，华为每个应用每日可发送该测试消息500条。此 target_user_type 参数请勿发布至线上。      
                  "/message/android/target_user_type":1      
              } ,    
            "VV": {      
                 //值为int 类型。0 表示正式推送；1 表示测试推送，不填默认为0。此 pushMode 参数请勿发布至线上。  
                  "/pushMode":1      
              }    
        }  
    })  
};

若使用vivo测试推送（ "/pushMode":1 ），额外需要先在 vivo 开放平台 录入测试用户。华为不需要录入。

在线消息无额度限制。离线推送各厂商的限额，详见： 厂商通道限额

如果你希望当应用在线时，也通过“通知栏消息”来提醒用户；可以通过以下两种方式实现：

1. 监听到消息内容后，根据业务需要自己判断是否要创建“通知栏消息”，需要就调用创建本地消息API uni.createPushMessage手动创建通知栏消息。
2. 服务端执行推送时，传递参数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.data, // 数据  
        "force_notification": true, // 服务端推送 需要加这一句  
        "request_id": obj.request_id ,//请求唯一标识号，10-32位之间；如果request_id重复，会导致消息丢失  
        "options":obj.options //消息分类，没申请可以不传这个参数  
    })  
    return res;  
};

5，postman请求示例

{  
    "cids":"此处填写自定义打包获取的clientid参数",  
    "title":"url化好聊聊玩",  
    "content":"11900099099 ",  
    "options": {  
        "HW": {  
            // 值为int 类型。1 表示华为测试消息，华为每个应用每日可发送该测试消息500条。此 target_user_type 参数请勿发布至线上。      
            "/message/android/target_user_type": 1  
        },  
        "VV": {  
            //值为int 类型。0 表示正式推送；1 表示测试推送，不填默认为0。此 pushMode 参数请勿发布至线上。  
            "/pushMode": 1  
        }  
    },  
    "data":{  
        "data1":1,  
        "data2":2  
    },  
    "request_id":"212320028909901111"  
}

三、客户端接收消息

3.1 客户端监听推送消息

如果您需要对接收到的消息进行自定义处理，可以再阅读一下本文开头的 “消息下发流程图”。

客户端监听推送消息的代码，需要在收到推送消息之前被执行。所以应当写在应用一启动就会触发的 应用生命周期 onLaunch中。

示例代码：

//文件路径：项目根目录/App.vue  
export default {  
    onLaunch: function() {  
        console.log('App Launch')  
        uni.onPushMessage((res) => {  
            console.log("收到推送消息：",res) //监听推送消息  
        })  
    },  
    onShow: function() {  
        console.log('App Show')  
    },  
    onHide: function() {  
        console.log('App Hide')  
    }  
}

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

四、注意事项

4.1 合规上架

app 若需要上架应用商店，须配置 隐私弹窗 提示用户。

4.2 帮助中心

当您在集成推送服务遇到问题时：

先仔细阅读此接入指南及对应的集成文档，查看是否有遗漏。
阅读 uni-push2.0 常见问题 ，查看是否能解决。