unipush推送入门：10分钟搞定UniPush在线消息集成

引言

消息推送是提升 App 用户活跃度和留存率的关键能力。对于采用 UniApp 开发的跨端应用，DCloud 官方提供的 UniPush 服务无疑是集成推送功能最高效选择。

本文将以一名开发者的视角，手把手带你完成 从项目初始化到成功接收第一条推送消息 的完整流程。你将学会：

UniPush 的正确接入姿势与核心配置
开发阶段必须使用的自定义调试基座
如何获取设备标识（CID）并进行在线推送测试
避开新手常见"坑点"的实用技巧

技术栈：UniApp + UniPush（华为、小米等厂商推送配置将在下篇介绍）

一、开发环境与项目初始化

1.1 项目创建与模块配置

项目创建：在 HBuilderX 中新建一个 UniApp 项目（过程略）。
启用 UniPush ：打开项目根目录的 manifest.json 文件，进入 "App模块配置" 选项卡，勾选 "Push(消息推送)" 模块，并确保选中 "UniPush" 作为具体服务。

1.2 制作自定义调试基座

为什么必须使用自定义基座？

UniApp 的标准运行基座（标准真机运行包）所使用的 DCloud 公有证书，其推送标识（CID）无法用于正式推送。只有使用你自己 App 的正式证书（或调试证书）打包的自定义基座，才能获得真实、有效的 CID。

制作步骤：

在 HBuilderX 顶部菜单，选择 运行 -> 运行到手机或模拟器 -> 制作自定义调试基座。
在弹出的界面中，你需要为 Android 平台提供应用签名证书。
- 证书生成 ：可以使用在线工具如 香蕉云编 快速生成调试证书（.keystore 文件），妥善保存密码及别名信息。
- 证书填写：将生成的证书文件路径、密码、别名等信息，准确填入 HBuilderX 的对应输入框。
点击 "打包" ，等待云端完成自定义基座的制作。

如何使用：

制作完成后，运行项目时，务必在运行菜单中选择"自定义调试基座" ，而非"运行标准基座"。只有运行在自定义基座上，后续的推送测试才有效。

二、 UniPush 服务开通与配置

推送能力依赖于 DCloud 的后台服务，因此需要在开发者中心完成配置。

进入开发者中心 ：访问 DCloud 开发者中心，在 "应用列表" 中找到你的项目。
配置应用信息：
- 如果未创建，请先为你的 App 创建一个应用。
- 进入应用详情，在 "各平台信息" 中配置 Android 平台信息。
- 这里需要填写的包名、应用签名 ，必须与上一步制作自定义基座时使用的证书信息完全一致。你可以在"香蕉云编"等工具生成证书的页面找到对应的 MD5 或 SHA1 签名。

三、核心代码实现与在线推送测试

3.1 获取设备推送标识 (CID)

CID 是 UniPush 服务识别每台设备的唯一 ID。在客户端，我们使用 uni.getPushClientId API 获取。

关键注意事项（时序问题）：

推送服务初始化需要时间，应用启动后立即调用此 API 可能返回空值。一个稳健的做法是延时获取或在监听事件中获取。

推荐实现方案：

javascript 复制代码

// 在 App.vue 的 onLaunch 中，或首个页面的 onLoad 中调用
function initUniPush() {
  // 方案1：延时获取（简单直接）
  setTimeout(() => {
    uni.getPushClientId({
      success: (res) => {
        const cid = res.cid;
        console.log('设备推送标识CID:', cid);
        // 重要：将 CID 发送到你的业务服务器进行关联存储
        // uploadCidToServer(cid);
        
        // 可通过 Vuex 或全局事件更新 UI 状态
        uni.$emit('push-cid-ready', cid);
      },
      fail: (err) => {
        console.error('获取CID失败:', err);
        // 处理失败逻辑，如重试
      }
    });
  }, 3000); // 延迟 3 秒，可根据实际情况调整

  // 方案2：监听事件（更精准）
  // uni.onPushMessage((res) => {...}); // 接收推送消息
  // 也可以在服务初始化成功的事件中获取CID
}

3.2 发送你的第一条推送

登录 DCloud 后台 ：进入你的应用，找到 "UniPush" 功能模块。
创建推送：
- 点击 "在线推送" 或 "推送消息" 。
- 推送方式选择 "单播（CID）" ，将上一步获取的 CID 填入。
- 填写推送标题、内容。内容应尽量模拟真实场景（如"欢迎使用"、"订单已发货"），避免使用"test"、"aaaa"等测试文本，以防被系统或厂商通道误判为骚扰信息而拦截。
- 点击发送。

验证结果：
- 发送后，在 "推送记录" 中可以查看状态。显示"已接收"即表示推送已成功抵达客户端。
- 确保你的 App 正处于前台运行 或后台存活状态。此时，你应该能在设备上收到通知栏消息。

四、总结与注意事项

至此，你已经完成了 UniPush 在线推送的核心流程。我们来总结一下关键点：

✅ 正确流程 ：创建项目 → 启用模块 → 制作自定义基座（关键！） → 平台配置 → 获取CID → 后台推送。

⚠️ 核心要点：

调试必须用自定义基座：这是获得有效 CID 的前提。
CID 获取有时序：使用延时或监听事件确保获取成功。
信息一致：开发者中心配置的包名、签名需与打包证书一致。
推送内容需"真实" ：避免纯测试内容被过滤。
在线推送的局限性 ：目前实现的是"在线推送"，即 App 进程存活（前台或后台）才能接收。要实现 App 完全关闭后仍能接收（离线推送），需要集成各大手机厂商的推送通道（华为、小米、OPPO、vivo 等）