HBuilderX 个推：一站式掌控在线 & 离线消息推送全流程

在 HBuilderX 项目中使用个推（Getui）实现在线消息和离线消息的完整流程，主要包含以下步骤：

🧩 一、准备工作

1. 注册个推账号并创建应用

官网：个推开发者中心

创建应用，获取：

AppID

AppKey

AppSecret

MasterSecret（服务端推送用）

2. 配置 HBuilderX 项目

HBuilderX ≥ 3.1.0 支持 unipush 插件（个推）。

打开 HBuilderX，进入项目 manifest.json 配置：

App模块开启

插件安装（如果使用原生插件方式）

如需高级个性化功能，可使用自定义原生插件形式集成个推 SDK，需借助 Android Studio 构建原生插件。

3. 云函数创建

1.使用HBuilderX在项目中创建云函数

2.需要在uniCloud控制台创建对应的函数表格，具体流程请参考个推的uni-push 2.0 快速接入指南 – DCloud问答

🚀 二、客户端代码编写

1. 初始化推送（App启动时）

// 接收到推送消息（包括透传）
plus.push.addEventListener('receive', (msg) => {
    console.log('收到推送内容:', msg);
});

// 用户点击推送通知
plus.push.addEventListener('click', (msg) => {
    console.log('点击推送消息:', msg);
});
// 兼容其他平台点击通知后的处理
uni.onPushMessage((res) => {
    console.log('点击通知后的数据:', res.data);
});

2. 绑定客户端唯一标识（CID）

plus.push.getClientInfoAsync(function(info) {
  const cid = info.clientid;
  console.log("当前设备CID: ", cid);
  // 发送到自己服务端，用于后续消息推送
});

uni.getPushClientId({
     success: (res) => {
     console.log("客户端标识", res.cid);
   },
   fail(err) {
     console.log(err);
   }
});

📬 三、消息类型说明

✅ 在线消息（透传）

实时在线才能收到。

不存储，不展示通知栏，直接走回调。

✅ 离线消息（透传 or 通知）

离线消息由个推缓存，用户上线时下发。

可设置展示通知栏或仅透传。

需配置个推服务端推送接口。

🧾 四、服务端推送消息流程（Node.js 为例）

1. 安装 SDK

npm install @gtdreamer/getui-sdk

2. 推送示例代码（单推）

const GeTui = require("@gtdreamer/getui-sdk");

const getui = new GeTui({
  appId: "你的AppID",
  appKey: "你的AppKey",
  masterSecret: "你的MasterSecret"
});

async function pushMessage(cid, title, content) {
  await getui.pushMessageToSingle({
    cid: cid,
    request_id: Date.now().toString(),
    message: {
      app_message: {
        msgtype: "transmission",
        is_offline: true,
        offline_expire_time: 1000 * 60 * 60, // 离线保留时间（1小时）
        msg_content: {
          transmission: {
            transmission_type: true,
            transmission_content: JSON.stringify({
              title: title,
              content: content
            })
          }
        }
      }
    }
  });
}

📦 五、离线通知栏消息（显示通知）

设置推送类型为 notification，内容类似如下：

msg_content: {
  notification: {
    style: {
      type: 0,
      text: "这是离线通知内容",
      title: "新消息通知"
    },
    transmission_type: true,
    transmission_content: "透传内容"
  }
}

🛠 六、常见问题处理

✅ 总结流程图

HBuilderX 配置个推信息

App 启动初始化推送、监听消息

获取 CID 上传服务端

服务端调用 API 推送消息（在线/离线）

客户端接收消息，通过回调 plus.push.addEventListener("receive") 处理

根据 payload 判断消息类型并展示或跳转页面