JPush UniApp UTS 插件完全参考手册：API、事件与厂商通道一网打尽

时光足迹2026-06-29 15:24

前两篇讲了 iOS 证书配置和 uni-app 代码实战，这篇是工具书性质的完整参考手册------涵盖 JPush UTS 插件的所有 API、事件系统、厂商通道配置和平台差异。当你不记得某个 API 的参数、某个错误码的含义、或者某个事件在哪个平台能用时，直接来这查。

一、插件架构总览

先搞清楚整个插件体系长什么样：

csharp 复制代码 
uni_modules/
├── jg-jpush-u/                  # 主模块（核心推送功能）
│   └── utssdk/
│       ├── interface.uts        # 跨平台类型定义
│       ├── app-ios/             # iOS 实现（Swift/UTS）
│       ├── app-android/         # Android 实现（Java/UTS）
│       └── app-harmony/         # HarmonyOS 实现（ArkTS/UTS）
│
├── jg-jpush-u-huawei/           # 华为厂商通道
├── jg-jpush-u-honor/            # 荣耀厂商通道
├── jg-jpush-u-fcm/              # FCM（Google）厂商通道
├── jg-jpush-u-xiaomi/           # 小米厂商通道
├── jg-jpush-u-vivo/             # Vivo 厂商通道
├── jg-jpush-u-oppo/             # OPPO 厂商通道
├── jg-jpush-u-meizu/            # 魅族厂商通道
└── jg-jpush-u-nio/              # 蔚来厂商通道

依赖关系：

  • 主模块 jg-jpush-u：独立运行，提供全部推送能力
  • 子模块（厂商通道） ：依赖主模块存在，仅负责 Android 厂商通道的 Maven 依赖和注册触发，逻辑极简（每个子模块的 init() 就是一行 console.log）
  • 所有子模块的 readme 首句都写着：「这个插件是依附 jg-jpush-u 插件而存在」

二、快速开始

2.1 导入

javascript 复制代码 
// 主模块
import {
  init,              // Android / HarmonyOS
  initPush,          // iOS
  setDebug,
  setChannel,        // Android / HarmonyOS
  getRegistrationId,
  setEventCallBack,
  setAlias, deleteAlias, getAlias,
  setTags, addTags, deleteTags, cleanTags, getAllTags,
  setBadgeNumber, resetBadge, getBadgeNumber,
  requestPermission,           // 仅 Android
  isNotificationEnabled,       // 仅 Android
  goToAppNotificationSettings, // 仅 Android
  stopPush, resumePush,        // Android / HarmonyOS
  isPushStopped,               // Android / HarmonyOS
} from '@/uni_modules/jg-jpush-u';

// 厂商通道（按需引入，用别名避免 init 命名冲突）
import { init as initHuawei } from '@/uni_modules/jg-jpush-u-huawei';
import { init as initXiaomi } from '@/uni_modules/jg-jpush-u-xiaomi';
// ... 其他厂商同理

2.2 三端初始化对比

这是整个插件最核心的差异点，弄错一步就全挂：

javascript 复制代码 
const platform = uni.getSystemInfoSync().platform;

if (platform === 'ios') {
  // iOS：必须用 initPush，参数为对象
  initPush({
    appkey: 'your_app_key',
    channel: 'default',
    isProduction: false,    // false = Sandbox 开发环境, true = Production 生产环境
    advertisingId: '',      // IDFA，可为空字符串
  });
} else {
  // Android / HarmonyOS：用 init
  init();  // appKey 可选，也可在 config.json 中预配
}

iOS initPush 的 isProduction 参数影响什么？

它决定了 APNs 连接哪个服务器：

  • false → api.sandbox.push.apple.com（开发环境）
  • true → api.push.apple.com（生产环境）

⚠️ 这个值必须和极光控制台上传的证书环境匹配。代码中通常写 !isDebug，即调试时走 Sandbox、正式包走 Production。

2.3 标准初始化顺序

javascript 复制代码 
// ① 先注册事件回调（必须在 init 之前！）
setEventCallBack({ callback: handlePushEvent });

// ② 开启调试模式（开发时建议开启）
setDebug(true);

// ③ 初始化 SDK
if (uni.getSystemInfoSync().platform === 'ios') {
  initPush({ appkey, channel, isProduction: false, advertisingId: '' });
} else {
  init();
}

// ④ [仅 Android] 请求通知权限
// #ifdef APP-ANDROID
requestPermission();
// #endif

💡 为什么回调必须在 init 之前？ 插件内部有事件缓存机制（EventCallbackManager），如果回调未设置时 SDK 产生事件，事件会被缓存。设置回调后会立即重放缓存事件，确保冷启动的 onRegister 不丢失。

三、完整 API 参考

3.1 初始化与配置

API iOS Android HarmonyOS 说明
init(appKey?) --- ✅ ✅ SDK 初始化，appKey 可后设
initPush(param) ✅ --- --- iOS 初始化，参数为 InitPushParams 对象
setDebug(boolean) ✅ ✅ ✅ 开发时建议开启
setChannel(string) --- ✅ ✅ 设置发布渠道
setAppKey(string) --- --- ✅ HarmonyOS 专用，在 init 后设置

InitPushParams 类型定义：

typescript 复制代码 
type InitPushParams = {
  appkey: string;           // 极光控制台 AppKey
  channel: string;          // 渠道标识，如 'default'
  isProduction: boolean;    // 是否生产环境
  advertisingId: string;    // IDFA，可为 ''
}

3.2 推送控制

API iOS Android HarmonyOS 说明
stopPush() --- ✅ ✅ 停止推送服务
resumePush() --- ✅ ✅ 恢复推送服务
isPushStopped() --- ✅ ✅ 查询推送是否已停止
getPushStatus(callback) ✅ --- --- iOS 查询推送状态
setBackgroundEnable(boolean) ✅ --- --- iOS 后台长连接
setKeepLongConnInBackground(boolean) --- ✅ --- Android 后台长连接

3.3 RegistrationID

API iOS Android HarmonyOS
getRegistrationId() 同步返回 string 同步返回 string 🔴 异步返回 Promise<string>

⚠️ HarmonyOS 要特别注意 ：getRegistrationId() 返回值是 Promise，必须 await 或 .then() 获取，不像 iOS/Android 直接拿到字符串。

3.4 别名与标签

所有操作通过事件回调返回结果，sequence 用于区分不同调用：

API 三端支持 结果事件
setAlias(sequence, alias) ✅ onAliasOperatorResult
deleteAlias(sequence) ✅ onAliasOperatorResult
getAlias(sequence) ✅ onAliasOperatorResult
setTags(sequence, tags[]) ✅ onTagOperatorResult
addTags(sequence, tags[]) ✅ onTagOperatorResult
deleteTags(sequence, tags[]) ✅ onTagOperatorResult
cleanTags(sequence) ✅ onTagOperatorResult
getAllTags(sequence) ✅ onTagOperatorResult
checkTagBindState(sequence, tag) ✅ onTagOperatorResult
setMobileNumber(sequence, number) ✅ onMobileNumberOperatorResult

💡 最佳实践 ：用 Date.now() % 100000 作为 sequence，足够区分不同调用。

3.5 角标

API iOS Android HarmonyOS
setBadgeNumber(n) ✅ ✅ ✅
resetBadge() ✅ --- ---
getBadgeNumber() ✅ --- ---

3.6 通知权限（仅 Android）

API 说明
requestPermission() 请求通知权限
requestRequiredPermission() Android 13+ POST_NOTIFICATIONS 权限
isNotificationEnabled() 检查通知是否已启用
goToAppNotificationSettings() 跳转到系统通知设置页

3.7 清除通知

API iOS Android HarmonyOS
clearNotificationAll() --- ✅ ✅
clearNotificationById(id) --- ✅ ✅
clearNotificationByMsgId(msgId) --- --- ✅

四、事件系统

4.1 事件注册

javascript 复制代码 
setEventCallBack({
  callback: (event) => {
    const { eventName, eventData } = event;
    console.log('JPush event:', eventName, eventData);
  }
});

4.2 事件类型一览

eventName 触发时机 iOS Android HarmonyOS eventData
onRegister SDK 注册成功，返回 rid ✅ ✅ ✅ registrationId 字符串
onConnected 连接状态变化 ✅ ✅ ✅ "true" / "false"
onClickMessage 用户点击通知 ✅ ✅ ✅ JSON 字符串
onNotifyMessageArrived 通知到达（前台） ✅ ✅ --- JSON 字符串
onCustomMessage 收到自定义消息 ✅ ✅ ✅ JSON 字符串
onTagOperatorResult 标签操作完成 ✅ ✅ ✅ {sequence, tags, errorCode}
onAliasOperatorResult 别名操作完成 ✅ ✅ ✅ {sequence, alias, errorCode}
onMobileNumberOperatorResult 手机号操作完成 ✅ ✅ ✅ {sequence, errorCode}
onCommandResult 命令执行结果 --- ✅ ✅ JSON
onNotificationSettingsCheck 通知设置检查 --- ✅ --- JSON
onMultiActionClicked 多按钮通知点击 --- ✅ --- JSON
onInAppMessageShow 应用内消息展示 --- ✅ --- JSON
onInAppMessageClick 应用内消息点击 --- ✅ --- JSON
onVoipMessage VoIP 消息 --- ✅ ✅ JSON

4.3 关键事件数据结构

onClickMessage（通知点击）--- 最常用的事件：

json 复制代码 
{
  "extras": { "type": "order_detail", "id": "123" },
  "notificationExtras": { "recordId": "456" },
  "title": "订单通知",
  "content": "您的订单已发货"
}

💡 extras 是服务端推送时设置的自定义参数，notificationExtras 是极光控制台配置的附加字段。业务跳转信息通常放在 extras 中。

onAliasOperatorResult：

json 复制代码 
{
  "sequence": 12345,
  "alias": "user_abc",
  "errorCode": 0
  // errorCode = 0 表示成功
}

五、厂商通道配置

5.1 为什么需要厂商通道？

Android 系统中，App 被杀死后，极光的长连接也会断开。此时推送消息需要通过华为/小米/OPPO/vivo 等手机厂商的系统级推送通道送达。厂商通道的作用就是提高 App 离线时的推送到达率。

5.2 模块清单

子模块 版本 特殊要求
华为 (huawei) 1.2.3 agconnect-services.json + 签名指纹 + 华为 Maven 仓库
荣耀 (honor) 1.2.3 HONOR_APPID + 荣耀 Maven 仓库
FCM (Google) 1.2.3 google-services.json + Google Services 插件
小米 (xiaomi) 1.2.3 XIAOMI_APPKEY + XIAOMI_APPID
Vivo 1.2.3 VIVO_APPKEY + VIVO_APPID
OPPO 1.2.3 OPPO_APPKEY + OPPO_APPID + OPPO_APPSECRET
魅族 (meizu) 1.2.3 MEIZU_APPKEY + MEIZU_APPID
蔚来 (nio) 1.2.3 NIO_APPID + 签名指纹

5.3 使用步骤

javascript 复制代码 
// 1. 在 HBuilderX 插件市场安装对应厂商通道插件

// 2. 在应用入口引入并初始化
// #ifdef APP-ANDROID
import { init as initHuawei } from '@/uni_modules/jg-jpush-u-huawei';
import { init as initXiaomi } from '@/uni_modules/jg-jpush-u-xiaomi';
import { init as initOppo }   from '@/uni_modules/jg-jpush-u-oppo';
import { init as initVivo }   from '@/uni_modules/jg-jpush-u-vivo';

initHuawei();
initXiaomi();
initOppo();
initVivo();
// #endif

// 3. 在极光控制台配置对应厂商的 AppKey/AppID/AppSecret

// 4. 在各厂商开发者平台申请推送权限并下载配置文件

💡 厂商通道的 init() 是无参函数，实际推送通道注册由 JPush Android SDK 内部自动完成。init() 调用只是一个触发入口。

六、平台差异速查表

功能领域 iOS Android HarmonyOS
初始化方法 initPush(obj) init(appKey?) init(context?)
AppKey 传入 initPush 参数中 init 参数或 config.json setAppKey() 单独设置
通知权限弹窗 自动（initPush 内部） 手动 requestPermission() setUserRequestNotificationPermission()
getRegistrationId 同步字符串 同步字符串 🔴 异步 Promise
停止/恢复推送 ❌ ✅ ✅
清除通知 ❌ ✅ ✅
角标读取 ✅ ❌ ❌
角标设置 ✅ ✅ ✅
getAllTags ✅ 不分页 ✅ 不分页 getTags(seq, curr) 分页
后台长连接 setBackgroundEnable setKeepLongConnInBackground ❌
权限检测 ❌ isNotificationEnabled() ❌
跳转设置页 ❌ goToAppNotificationSettings() ❌

七、错误码速查

错误码 含义
0 操作成功
6002 连接超时（SDK 连不上 JPush 服务器，排查：证书/网络/环境）
6003 参数错误
6005 alias 字符串不合法（必须有效 UTF-8，最多 40 字节）
6007 别名绑定超限（最多 10 个）
6008 tag 无效（大小超限或为空）
6011 短时间内操作过于频繁
6013 alias 为空
6014 tag 为空
6015 alias 过长
6018 tag 数量超限（最多 1000 个）
6022 alias 未设置（deleteAlias 时 alias 不存在）

八、常见问题 FAQ

Q1：iOS 调用 requestPermission() 报错？

根因 ：iOS 插件根本没有这个方法。iOS 通知权限由 initPush 内部自动触发。必须用条件编译：

javascript 复制代码 
// #ifdef APP-ANDROID
requestPermission();
// #endif

Q2：iOS getRegistrationId() 始终为空？

完整排查链路：

  1. Provisioning Profile 是否包含 Push Notifications 能力？
  2. 极光控制台是否上传了 iOS 推送证书（.p8 或 .p12）？
  3. isProduction 参数与证书环境是否匹配？
  4. 是否在真机上测试？（模拟器不支持推送）
  5. 用户是否拒绝了通知权限？（系统设置中检查）

详见本系列下篇的 4 轮排查过程。

Q3：HarmonyOS 的 getRegistrationId() 为什么是 Promise？

鸿蒙系统的 API 设计全部采用异步模型，getRegistrationId() 也不例外。必须用 await：

javascript 复制代码 
const rid = await getRegistrationId();

Q4：厂商通道 init 需要传什么参数？

不需要。子模块的 init() 都是无参函数，实际推送通道注册由 JPush SDK 内部完成。

Q5：setEventCallBack 为什么必须在 init 之前？

插件内部使用 EventCallbackManager，回调未设置时 SDK 产生的事件会被缓存（如冷启动的 onRegister）。设置回调后会立即重放缓存事件，确保事件不丢失。

Q6：插件文档没提 iOS 证书配置？

官方 iOS_Integration_Guide.md 只说了「登录极光控制台 → 创建应用 → 记录 AppKey」，完全没有提证书配置。实际上 iOS 推送必须完成 Apple Developer 侧的整套证书配置，缺失任何一步都不会正常工作。详见本系列上篇。

总结

这份手册覆盖了 JPush UTS 插件的：

  • 15+ API 及其三端支持情况
  • 14 种事件类型及触发时机
  • 8 个厂商通道的配置要求
  • 12 项平台差异的快速对照
  • 11 种错误码的含义
  • 6 个高频 FAQ

建议配合上篇（证书配置）和中篇（代码实战）一起使用，形成「配置 → 实现 → 参考」的完整知识闭环。

标签：uni-app 极光推送 JPush UTS插件 API参考 跨端开发 HarmonyOS

相关推荐
时光足迹1 小时前
极光推送全攻略（下）：uni-app 代码实现与 iOS 排查实战
vue.js·ios·uni-app
时光足迹1 小时前
极光推送全攻略（上）：被iOS证书折磨了三天，我写了一份前端也能看懂的避坑指南
前端·ios·uni-app
疯狂的魔鬼2 小时前
一个"懂分寸"的文本省略组件是怎样炼成的
前端·vue.js·设计
裕波2 小时前
AI 正在重写应用开发。Vue 与 Vite，给出新的答案。
javascript·vue.js
妙码生花2 小时前
现代前端的极致性能 icon 加载方案（死磕成功版）
前端·vue.js·typescript
用户2136610035726 小时前
Vue2脚手架工程化与Axios集成
前端·vue.js
用户83134859306986 小时前
Cesium实现黄昏效果：按钮一键控制打开/关闭黄昏效果，滑块拖动实时控制黄昏浓烈度
vue.js·cesium
Cobyte7 小时前
21.Vue Vapor 组件的实现原理
前端·javascript·vue.js
橙某人7 小时前
LogicFlow 工作流撤销与重做：从「全量快照」到「命令模式」🎯
前端·vue.js
热门推荐
012026年6月AI大模型全景报告：GPT-5.6、Claude Opus 4.8、Gemini 3.5，中美AI三足鼎立谁主沉浮？022026年6月AI行业全景：从百模大战到Agent元年，这30天发生了什么？032026 年 AI 编程工具终极横评：Cursor vs Claude Code vs Copilot vs Windsurf04飞书长连接_事件订阅（接收消息，审批任务状态变更）05Trae国际版与国内版深度测评：AI原生IDE的双生花06【AI】2026 年具身智能模型和世界模型总结07GitHub 镜像站点08Claude Code、Codex、Cursor三分天下：2026年AI编程Agent生态全景剖析092026年AI架构实战：彻底解决OpenAI接口超时与封号，Python调用GPT-5.2/Sora2企业级架构详解（附源码+压测报告）102026 AI 编程工具终极实战指南：Cursor vs Claude Code vs Copilot，开发者该怎么选？