更新记录

1.0.1（2026-07-21）

• 安卓端补充角标权限

1.0.0（2026-07-20）

• 初始版本

平台兼容性

uni-app(5.13)

uni-app x(5.13)

xwq-jpush

xwq-jpush 是面向 uni-app x 的极光推送 UTS 插件，封装 Android、iOS、HarmonyOS 的基础推送能力。

支持平台

重要说明

• 本插件依赖原生 SDK 和原生配置，运行到标准基座时原生配置或三方 SDK 可能不生效；Android/iOS 真机调试请使用自定义基座或正式云打包。
• initializeJpush() 应在用户同意隐私政策后调用，避免违反极光 SDK 合规要求。
• Android 当前只配置了极光基础通道；如需稳定离线推送，还需要继续接入华为、小米、OPPO、VIVO、荣耀、魅族、FCM 等厂商通道。
• iOS 推送依赖 APNs 能力，必须完成 Apple 证书、Capabilities、deviceToken 转发等配置，否则只能初始化 SDK，不能完整收到远程通知。

目录说明

Android 配置

1. AppKey 和渠道

插件的 AndroidManifest 使用了 ${JPUSH_APPKEY} 和 ${JPUSH_CHANNEL} 占位符。uni-app x 项目需要在项目根目录创建：

nativeResources/android/manifestPlaceholders.json

示例：

{
  "JPUSH_APPKEY": "你的极光 Android AppKey",
  "JPUSH_CHANNEL": "developer-default"
}

当前项目已配置该文件。注意：JPUSH_APPKEY 必须与极光控制台中 Android 应用的包名一致。

2. 基础通道和厂商通道

当前 Android 侧已实现极光基础通道，可以完成在线推送、通知回调、Registration ID、别名、标签和手机号等基础能力。

如果需要 App 被杀死、长期后台或厂商系统限制后台进程时仍稳定收到离线通知，需要继续配置厂商通道。厂商通道通常涉及：

• 对应厂商 SDK 依赖。
• AndroidManifest 中对应 Service、Receiver、Activity、meta-data。
• 厂商后台申请的 AppId、AppKey、AppSecret 等参数。
• 极光后台开启并配置对应厂商 channel。

不要在没有厂商参数时直接全量开启厂商通道，否则可能出现无效依赖、Manifest 冲突或运行时注册失败。

3. 通知权限

Android 13 及以上需要用户授予 POST_NOTIFICATIONS 权限，否则通知可能无法展示。插件 Manifest 已声明权限，业务侧仍需按产品流程引导用户授权。

iOS 配置

1. 本地依赖

iOS 侧依赖已配置为本地依赖，目录为：

uni_modules/xwq-jpush/utssdk/app-ios/Frameworks/

包含：

• jpush-ios-5.6.0.xcframework
• jcore-ios-5.0.1.xcframework
• jpush-extension-ios-2.0.6.xcframework

如 iOS 编译时提示 Swift 找不到 JPUSHService、JPUSHRegisterDelegate 等符号，通常需要检查 xcframework 是否包含可被 Swift 导入的 module map，或补充桥接头配置。

2. AppKey 和渠道

修改：

uni_modules/xwq-jpush/utssdk/app-ios/info.plist

示例：

<key>JPushAppKey</key>
<string>你的极光 iOS AppKey</string>
<key>JPushChannel</key>
<string>App Store</string>

说明：

• JPushAppKey 必填，必须使用极光控制台 iOS 应用的 AppKey。
• JPushChannel 可选，默认可使用 App Store。
• Swift 桥接层会优先读取 JPushAppKey，其次读取 JPUSH_APPKEY。

3. APNs 能力

iOS 远程推送必须在 Apple 开发者后台和 Xcode 能力中完成以下配置：

• 开启 Push Notifications Capability。
• 按需开启 Background Modes 中的 Remote notifications。
• 使用包含推送能力的 Provisioning Profile。
• 极光后台 iOS 应用已配置正确的 APNs 证书或 Auth Key。
• apsForProduction 要与证书环境一致。当前 UTS 入口默认使用开发环境 false，生产包需改为 true 或扩展为可配置参数。

4. AppDelegate 转发

JPush iOS SDK 需要接收 APNs device token 和远程通知 payload。当前插件已提供 Swift 方法，但项目侧仍需要在 AppDelegate 生命周期中转发：

func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
    JPushIOSBridge.registerDeviceToken(deviceToken)
}

func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable: Any], fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
    JPushIOSBridge.handleRemoteNotification(userInfo)
    completionHandler(.newData)
}

不转发 deviceToken 时，iOS 远程通知链路无法完整建立；不转发 userInfo 时，极光统计和插件通知到达回调可能不完整。

HarmonyOS 配置

1. 极光 AppKey 和渠道

修改：

uni_modules/xwq-jpush/utssdk/app-harmony/resources/base/element/string.json

{
  "string": [
    {
      "name": "jpush_appkey",
      "value": "你的极光 HarmonyOS AppKey"
    },
    {
      "name": "jpush_channel",
      "value": "huawei store"
    }
  ]
}

2. HarmonyOS client_id

修改或创建：

harmony-configs/entry/src/main/module.json5

关键配置：

{
  "module": {
    "metadata": [
      {
        "name": "client_id",
        "value": "你的 HarmonyOS 应用 client_id"
      }
    ],
    "requestPermissions": [
      {
        "name": "ohos.permission.INTERNET"
      }
    ]
  }
}

client_id 必须属于当前 app-harmony.distribute.bundleName 对应的 HarmonyOS 应用。

3. 后台和签名要求

HarmonyOS 推送成功依赖以下外部配置：

• AGC/HarmonyOS 平台已给当前应用开通 Push Kit 推送服务。
• AGC/HarmonyOS 应用已配置当前签名证书的 SHA256 指纹。
• 当前运行包的 bundleName 与 AGC/HarmonyOS、极光后台配置一致。
• 极光后台已开启 Harmony channel，并配置同一个包名、AppKey 和厂商通道信息。
• 修改 harmony-configs 或资源文件后，建议清理旧的 unpackage/dist/dev/app-harmony 后重新运行。

引入方式

import {
  addTags,
  checkTagBindState,
  cleanTags,
  deleteAlias,
  deleteTags,
  getAlias,
  getAllTags,
  getRegistrationID,
  goToAppNotificationSettings,
  initializeJpush,
  isNotificationEnabled,
  MessageListener,
  offListenerJpushMessage,
  onListenerJpushMessage,
  setAlias,
  setChannel,
  setLatestNotificationNumber,
  setMobileNumber,
  setPowerSaveMode,
  setPushState,
  setTags
} from '@/uni_modules/xwq-jpush'

推荐调用顺序

1. 页面加载后先调用 onListenerJpushMessage(listener) 注册监听。
2. 再调用 initializeJpush() 初始化极光 SDK。
3. 在 onRegister(id) 回调拿到非空 Registration ID 后，再执行别名、标签、手机号等绑定操作。
4. 页面隐藏或卸载时调用 offListenerJpushMessage()，避免页面对象释放后仍收到回调。

API 说明

initializeJpush(): void

初始化极光推送。

平台差异：

• Android：读取 Manifest meta-data 中的 JPUSH_APPKEY 和 JPUSH_CHANNEL。
• iOS：读取 info.plist 中的 JPushAppKey，默认渠道为 App Store。
• HarmonyOS：读取 resources/base/element/string.json 中的 jpush_appkey 和 jpush_channel。

onListenerJpushMessage(listener: MessageListener): void

注册推送监听器。

offListenerJpushMessage(): void

移除当前监听器。建议在页面 onHide 或 onUnload 中调用。

getRegistrationID(): string

获取缓存的 Registration ID。初始化完成前可能返回空字符串；初始化后会顺带刷新最新 Registration ID，并通过 onRegister 回调返回。

isNotificationEnabled(): boolean

获取缓存的系统通知权限状态。Android/iOS 的权限查询都可能异步刷新，因此当前调用返回的是最近缓存值。

goToAppNotificationSettings(): void

跳转系统应用通知设置页。

setPushState(checked: boolean): void

开启或关闭极光推送。

setAlias(sequence, alias, callback): void

设置别名，覆盖原有别名。

deleteAlias(sequence, callback): void

删除当前别名。

getAlias(sequence, callback): void

查询当前别名。

setTags(sequence, tags, callback): void

覆盖设置标签集合。

addTags(sequence, tags, callback): void

追加标签集合。

deleteTags(sequence, tags, callback): void

删除指定标签集合。

cleanTags(sequence, callback): void

清空全部标签。

getAllTags(sequence, callback): void

查询全部标签。

checkTagBindState(sequence, tag, callback): void

查询指定标签是否绑定。

setMobileNumber(sequence, phone, callback): void

设置手机号。空字符串按极光 SDK 规则处理。

setChannel(channel: string): void

设置渠道名。建议在 initializeJpush() 前调用。

setLatestNotificationNumber(num: number): void

设置角标或最近通知数量。

• Android：调用 setLatestNotificationNumber。
• iOS：设置 applicationIconBadgeNumber 并调用 JPUSHService.setBadge。
• HarmonyOS：映射到 setBadgeNumber。

setPowerSaveMode(enable: boolean): void

设置省电模式。

• Android：转发给极光 Android SDK。
• iOS：极光 iOS SDK 无对应 API，仅返回提示事件。
• HarmonyOS：当前极光 HarmonyOS SDK 无对应 API，仅输出提示。

回调数据说明

所有原生事件最终都会转换为统一结构：

{
  "type": "register",
  "sequence": 0,
  "code": 0,
  "message": "registration id",
  "value": "registration id 或 JSON 字符串"
}

UTS 入口会把不同 type 分发到对应 MessageListener 字段。value 始终按字符串处理；如果是复杂对象，则是 JSON 字符串，业务侧可自行 JSON.parse。

常见 type：

调试建议

• 初始化前先注册监听，避免错过早期回调。
• onRegister 返回非空 Registration ID 表示极光基础注册成功。
• Android 标准基座无法生效原生依赖时，请使用自定义基座。
• iOS 真机运行必须使用签名基座或自定义基座，并完成 APNs 能力配置。
• HarmonyOS 推送 token 获取失败时，优先检查 AGC Push Kit、client_id、签名证书 SHA256、bundleName 和极光后台 Harmony channel。
• 修改平台原生资源后，如仍读取旧配置，清理对应 unpackage/dist/dev/* 后重新运行。

相关文档

• 极光推送 Android SDK 集成指南
• 极光推送 Android SDK API
• 极光推送 iOS SDK 集成指南
• 极光推送 iOS SDK API
• 极光推送 HarmonyOS SDK 集成指南
• 极光推送 HarmonyOS SDK API