UniPush 2.0 从零到一：手把手实现全平台消息推送

1. UniPush 2.0 入门：理解推送机制与核心概念

第一次接触消息推送功能的开发者，往往会被"透传消息"、"通知消息"、"CID"这些专业术语搞得一头雾水。别担心，我们先从最基础的概念讲起。UniPush 2.0是DCloud推出的多平台推送服务，它能帮你的应用实现安卓、iOS双端的消息推送能力，而且集成过程比原生开发简单得多。

透传消息就像个快递小哥，不管你的应用是在前台运行、后台挂起，甚至被彻底关闭，他都能把消息准确送达。这种消息到达设备后，会触发你的应用代码进行处理，适合需要自定义交互的场景。比如你收到一条即时聊天消息，应用可以根据消息内容弹出特定样式的通知窗口。

通知消息则像个门卫，只有当你应用的大门开着（即应用在前台运行）时才会放行。这种消息通常由系统通知栏直接展示，开发者无法自定义处理逻辑。想象一下天气预报应用，如果应用没在运行，用户就收不到天气变化的提醒，这显然不是我们想要的。

在实际项目中，我建议将两种消息类型结合使用。比如电商应用可以用通知消息提醒"您的订单已发货"，用透传消息实现"您购买的商品降价50元，点击查看"这样的交互式通知。UniPush 2.0的厉害之处在于，它用一套API就统一了安卓和iOS的推送机制，开发者不用再分别对接FCM和APNs了。

2. 开通与配置UniPush 2.0服务

2.1 服务开通步骤

首先登录uni-app官网，进入开发者中心。在左侧菜单找到"UniPush 2.0"服务，点击"立即开通"。这里有个新手常踩的坑：一定要确保你的开发者账号已经完成实名认证，否则开通按钮会是灰色的。我遇到过好几个开发者卡在这步，花了半天时间找原因。

开通后会看到一个配置页面，这里需要填写应用的基本信息。特别注意**包名(Bundle ID)**这个字段，它就像应用的身份证号码：

• iOS平台：必须与Xcode工程中配置的Bundle Identifier完全一致
• 安卓平台：建议采用反向域名格式，如com.yourcompany.appname

2.2 厂商通道配置

想要在华为、小米等国产手机上实现离线推送，必须配置厂商通道。以华为为例：

1. 进入华为开发者联盟网站，创建应用
2. 获取应用的App ID和App Secret
3. 将这些信息回填到UniPush的厂商配置页面

这里有个实用技巧：不同厂商对消息长度限制不同。实测发现，华为EMUI系统下，通知标题超过20个汉字会被截断，而小米MIUI可以显示30个左右。建议在代码中对长消息做自动截断处理，避免显示异常。

3. 获取客户端CID与调试技巧

3.1 集成客户端SDK

在uni-app项目的App.vue文件中，添加以下初始化代码：

onLaunch: function() { const _this = this plus.push.addEventListener('click', function(msg) { console.log('收到推送点击事件：' + JSON.stringify(msg)) }) plus.push.addEventListener('receive', function(msg) { console.log('收到推送消息：' + JSON.stringify(msg)) }) }

这段代码注册了两个事件监听器，分别处理推送消息的接收和点击事件。建议在开发阶段都加上console.log输出，方便调试。

3.2 获取CID的实战经验

CID是Client ID的缩写，相当于设备的唯一标识符。获取CID需要制作自定义基座运行：

1. 在HBuilderX中选择"运行"->"制作自定义基座"
2. 选择iOS或安卓平台
3. 运行项目后，在控制台日志中搜索"cid"即可找到

我遇到过CID获取失败的情况，通常是因为：

• 项目没有正确关联UniPush服务
• 自定义基座制作时证书配置错误
• 设备网络环境屏蔽了推送服务域名

建议在真机上测试，模拟器可能无法正常获取CID。如果遇到问题，可以尝试重启HBuilderX或清除项目缓存。

4. 消息推送全流程实战

4.1 发送测试消息

拿到CID后，回到UniPush控制台：

1. 选择"消息推送"->"透传消息"
2. 在测试设备栏粘贴CID
3. 填写消息标题和内容
4. 点击"测试"按钮

这里有个重要细节：不要点击"确定"按钮，除非你想把测试消息推送给所有用户。我就曾不小心点了确定，结果测试消息发给了线上用户，造成了不必要的困扰。

4.2 安卓Intent格式详解

安卓平台的通知点击动作需要特殊配置，格式固定如下：

intent:#Intent;action=android.intent.action.oppopush;launchFlags=0x14000000;component=你的包名/io.dcloud.PandoraEntry;S.UP-OL-SU=true;S.title=测试标题;S.content=测试内容;S.payload=test;end

其中需要替换的只有"你的包名"这部分。获取包名的方法：

1. 打开项目的manifest.json文件
2. 在"基础配置"中查看"应用标识"

建议把这个Intent模板保存为代码片段，每次推送新消息时只需替换变量即可。

5. 云端服务集成与进阶配置

5.1 关联uniCloud服务空间

要实现服务端推送，需要关联uniCloud服务空间：

1. 登录uniCloud官网，创建服务空间（推荐阿里云版）
2. 安装uni-push云端插件
3. 在uni-app项目中关联该服务空间

这里有个隐藏技巧：创建服务空间时选择离你用户群体最近的区域。比如用户主要在华南，就选深圳地域，可以降低推送延迟。

5.2 服务端推送示例

配置好云函数后，可以用以下Java代码测试推送：

public void sendPushNotification() { HashMap<String, String> data = new HashMap<>(); data.put("title", "订单提醒"); data.put("content", "您的订单已发货"); data.put("push_clientid", "目标设备CID"); String result = HttpKit.post("你的云函数URL", data); System.out.println("推送结果：" + result); }

实际项目中，我建议对推送结果做日志记录，方便排查问题。常见的失败原因包括：

• CID已失效（用户长时间未打开应用）
• 推送频率超过限制
• 消息内容包含敏感词被过滤

6. 上架前必做的合规检查

应用商店对消息推送有严格的合规要求，上架前务必：

1. 添加隐私政策弹窗，明确告知用户会收集CID用于推送
2. 在应用设置中提供推送开关，允许用户关闭
3. iOS应用需要处理用户拒绝通知权限的情况

我在一个电商项目中就遇到过审核被拒的情况，原因是没在首次启动时请求通知权限。后来改成用户首次进入消息中心时才触发权限请求，通过率大幅提升。

测试阶段建议使用开发证书，上架前切换为生产证书。曾经有开发者忘记切换证书，导致线上用户收不到推送，只能紧急发版修复。