@cordova-ohos/jpush-phonegap-plugin
v5.9.1
Published
Cordova JPush Plugin
Readme
jpush-phonegap-plugin
本项目基于 [email protected] 开发，本文档重点阐述其在 OpenHarmony（OHOS）系统中的具体应用。
简介
jpush-phonegap-plugin 是极光推送（JPush）官方提供的 Cordova 插件，为跨平台（Android/iOS/OHOS）移动应用提供稳定、高效的推送通知能力。支持自定义消息、通知栏样式定制、推送状态监听等核心功能，助力开发者快速实现全场景消息触达。
插件概述
作为极光推送生态的核心插件，jpush-phonegap-plugin 基于极光推送的 har 包的基础能力，提供以下核心功能：
消息类型全覆盖：支持通知消息、自定义消息（纯数据透传）
精准触达：支持别名、标签、注册 ID 等多维度目标定位
状态可视化：提供推送注册、消息接收、点击等全链路事件监听
调试友好：内置调试模式，实时反馈服务注册及消息处理状态
该插件已广泛应用于电商、社交、工具等各类应用，经过亿级设备验证，具备高可靠性和兼容性。
支持平台
Android：API 19 及以上（Android 4.4+）
iOS：10.0 及以上
OHOS：5.0+
前置准备
使用插件前需完成极光推送开发者平台配置，步骤如下：
下载安装
从 npm 安装（推荐）
OHOS 平台安装无需指定 APP_KEY 参数，APP_KEY 在 PluginRegisterHandle 传入，请参考 OHOS 配置说明
# 安装 hcordova
npm install -g hcordova
# 直接安装最新版本
hcordova plugin add jpush-phonegap-plugin
# 指定 OHOS 平台
hcordova plugin add jpush-phonegap-plugin --platform ohos
# 指定版本安装（OHOS 平台）
hcordova plugin add [email protected] --platform ohos从 GitCode 仓库安装
如需使用开发中的最新功能，可从 GitHub 仓库安装：
# 仅支持 OHOS 平台
hcordova plugin add https://gitcode.com/CPF-Cordova/jpush-phonegap-plugin.git --platform ohos
# 指定标签/分支安装
hcordova plugin add https://gitcode.com/CPF-Cordova/jpush-phonegap-plugin.git@develop --platform ohos离线安装（本地包）
适用于无网络环境，先下载插件包到本地，再执行离线安装：
# 下载插件包到本地（示例路径：~/Downloads/jpush-phonegap-plugin）
# 执行离线安装
hcordova plugin add ~/Downloads/jpush-phonegap-plugin --platform ohos安装后验证
安装完成后，可通过以下命令验证插件是否成功添加到项目中：
# 查看已安装的插件列表，若包含本插件 ID 则表示插件已成功安装
hcordova plugin list卸载
卸载时需先移除当前插件，再移除依赖的核心库：
# 卸载主插件
hcordova plugin remove jpush-phonegap-plugin
# 指定平台卸载
hcordova plugin remove jpush-phonegap-plugin --platform ohos约束与限制
兼容性
支持：
| 项目 | 版本/信息 | |-----|--------| | SDK | API12+ | | IDE | DevEco Studio: 5.0+ | | ROM | 5.1+ | | Emulator | OpenHarmony 6.0+ |
在以下版本中已测试通过：
| 项目 | 版本/信息 | |-----|--------| | @cordova-ohos/ohos | 14.0.1-ohos-14.0.1 | | SDK | 5.0.0(12) | | IDE | DevEco Studio: 6.0.13.200 | | ROM | 5.1.0.120 SP3 | | Emulator | OpenHarmony 6.0.1(21) |
使用示例
以下示例展示完整封装了成函数，实现 API 的各种功能：
var message = "";
function jPushInit() {
window.JPush.init();
document.addEventListener("jpush.receiveRegistrationId", function(event) {
// 注册 ID 并不是每次都回调，需要注册 ID 在 init 完后，调用 jPushGetRegistrationID 获取 ID
console.log("Received registration ID:" + JSON.stringify(event));
});
document.addEventListener("jpush.receiveMessage", function(event) {
console.log("Received push message:" + JSON.stringify(event));
});
document.addEventListener("jpush.receiveInAppMessageClick", function(event) {
console.log("Clicked push message:" + JSON.stringify(event));
});
}
function jPushGetRegistrationID() {
window.JPush.getRegistrationID(function(rid) {
document.getElementById("jPushRid2").innerHTML = rid;
});
}
function jPushStop() {
window.JPush.stopPush(function(rid) {
document.getElementById("jPushStop").innerHTML = rid;
});
}
function jPushResume() {
window.JPush.resumePush(function(rid) {
document.getElementById("jPushResume").innerHTML = rid;
});
}
function jPushIsPushStopped() {
window.JPush.isPushStopped(function(result) {
document.getElementById("jPushIsPushStopped").innerHTML = result;
});
}
function jPushAddTags() {
window.JPush.addTags( { 'sequence': 5, 'tags': ['tag1', 'tag2'] }, function(result) {
document.getElementById("jPushAddTags").innerHTML = JSON.stringify(result);
},function(){
});
}
function jPushDelTags() {
window.JPush.deleteTags( { 'sequence': 6, 'tags': ['tag1', 'tag2'] }, function(result) {
document.getElementById("jPushDelTags").innerHTML = JSON.stringify(result);
},function(){
});
}
function jPushSetTags() {
window.JPush.setTags( { 'sequence': 7, 'tags': ['tag1', 'tag2'] }, function(result) {
document.getElementById("jPushSetTags").innerHTML = JSON.stringify(result);
},function(){
});
}
function jPushCheckTagBindState() {
window.JPush.checkTagBindState( { 'sequence': 8, 'tag':'tag1' }, function(result) {
document.getElementById("checkTagBindState").innerHTML = JSON.stringify(result);
},function(){
});
}
function jPushGetAllTags() {
window.JPush.getAllTags( { 'sequence': 9}, function(result) {
document.getElementById("getAllTags").innerHTML = JSON.stringify(result);
},function(){
});
}
function jPushCleanTags() {
window.JPush.cleanTags( { 'sequence': 10}, function(result) {
document.getElementById("cleanTags").innerHTML = JSON.stringify(result);
},function(){
});
}
function jPushSetAlias() {
window.JPush.setAlias( { 'sequence': 11, 'alias':'alias1' }, function(result) {
document.getElementById("setAlias").innerHTML = JSON.stringify(result);
},function(){
});
}
function jPushGetAlias() {
window.JPush.getAlias( { 'sequence': 12}, function(result) {
document.getElementById("getAlias").innerHTML = JSON.stringify(result);
},function(){
});
}
function jPushDeleteAlias() {
window.JPush.deleteAlias( { 'sequence': 13}, function(result) {
document.getElementById("deleteAlias").innerHTML = JSON.stringify(result);
},function(){
});
}
function jPushSetMobileNumber() {
window.JPush.setMobileNumber( { 'sequence': 14, 'mobileNumber':'13800138000' }, function(result) {
document.getElementById("setMobileNumber").innerHTML = JSON.stringify(result);
},function(){
});
}
function jPushSetBadgeNumber() {
window.JPush.setBadgeNumber(5);
}
var msgId = "fdfdfdf";
function jPushClearNotificationById() {
window.JPush.clearNotificationById(msgId);
}
function jPushClearAllNotification() {
window.JPush.clearAllNotification();
}使用说明
OHOS 配置
1 修改项目中的 oh-package.json5 文件
在 dependencies 中加入极光推送 jg/push 的依赖项：
{
"name": "entry",
"version": "1.0.0",
"description": "Please describe the basic information.",
"main": "",
"author": "",
"license": "",
"dependencies": {
"@jg/push": "^1.3.1",
"@cordova-ohos/ohos": "file:../cordova"
}
}2 配置工程级 build-profile.json5
在工程级（最外层）build-profile.json5 中，配置 "useNormalizedOHMUrl": true：
"products": [
{
"name": "default",
"signingConfig": "default",
"compatibleSdkVersion": "5.0.0(12)",
"buildOption": {
"strictMode": {
"caseSensitiveCheck": true,
"useNormalizedOHMUrl": true
}
}
}
]3 修改 EntryAbility 代码
添加极光推送插件在 ArkTS 侧监听和初始化：
export default class EntryAbility extends UIAbility {
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
// 添加如下代码，注册 Jpush 监听插件
// JPush/JPushAction，动态导入 JPush 插件
// EntryAbility JPush 插件的入口函数
// YOUR_APP_KEY 为 app 的 APP_KEY，在 Jpush 的开放平台获取
PluginRegisterHandle(this, want, "JPush/JPushAction", "EntryAbility", "YOUR_APP_KEY");
}
onNewWant(want: Want): void {
// 添加如下代码，注册 Jpush 监听插件
// JPush/JPushAction，动态导入 JPush 插件
// EntryAbility JPush 插件的入口函数
// YOUR_APP_KEY 为 app 的 APP_KEY，在 Jpush 的开放平台获取
PluginRegisterHandle(this, want, "JPush/JPushAction", "EntryAbility", "YOUR_APP_KEY");
}
}API 文档
插件通过全局对象 window.JPush 暴露 API，所有异步操作通过回调函数返回结果。API 调用需在 deviceready 事件触发后执行。具体使用示例见「使用示例」章节。
1 初始化与基础配置
1.1 初始化推送服务
/**
* 初始化极光推送服务
* 需在 deviceready 事件后调用
*/
window.JPush.init();1.2 开启/关闭调试模式
/**
* 开启调试模式（开发环境推荐开启）
* @param {Boolean} enabled - 是否启用调试
*/
window.JPush.setDebugMode(true);
// 关闭调试模式（生产环境必需关闭）
window.JPush.setDebugMode(false);1.3 获取注册 ID
/**
* 获取设备注册 ID（唯一标识设备，用于单点推送）
* @param {Function} successCallback - 成功回调（参数：注册 ID）
* @param {Function} errorCallback - 失败回调（参数：错误信息）
*/
window.JPush.getRegistrationID(
(registrationId) => {
console.log("设备注册 ID：", registrationId);
// 建议将 registrationId 上传至业务服务器
},
(error) => {
console.error("获取注册 ID 失败：", error);
}
);2 推送目标管理
2.1 设置别名（单点推送）
/**
* 设置别名（每个设备仅可设置一个别名，常用于用户 ID 绑定）
* @param {Number} sequence - 请求序列号（用于匹配请求与响应）
* @param {String} alias - 别名（支持字母、数字、下划线）
*/
window.JPush.setAlias( { 'sequence': 11, 'alias':'alias1' }, function(result) {
// 设置成功
},function(){
// 设置失败
});2.2 设置标签（批量推送）
/**
* 设置标签（每个设备可设置多个标签，用于群体推送）
* @param {Number} sequence - 请求序列号
* @param {Array<String>} tags - 标签数组
*/
window.JPush.setTags( { 'sequence': 7, 'tags': ['tag1', 'tag2'] }, function(result) {
// 设置成功
},function(){
// 设置失败
});3 消息监听
3.1 监听注册 ID
/*
* 监听注册的 ID
* registrationId：string // 注册 ID
*/
document.addEventListener("jpush.receiveRegistrationId", function(event) {
// 注册 ID 并不是每次都回调，需要注册 ID 在 init 完后，调用 jPushGetRegistrationID 获取 ID
console.log("收到注册 ID:" + JSON.stringify(event));
});3.2 监听通知消息接收
/**
* 监听通知消息接收事件
* 消息字段如下：
* msgId?: string // 通知 id
* title?: string // 通知标题
* content?: string // 通知内容
* contentType?: string // 通知内容类型
* extras?: Record<string, Object> // 通知自定义键值对
* ttl?: number // 后台下发的信息过期时间，单位秒
* stime?: number // 后台下发时间，毫秒
* channel?: number // 数据来源通道 0:厂商通道 1:极光通道（开始支持的版本：JPush OpenHarmony SDK v1.3.0）
*/
document.addEventListener("jpush.receiveMessage", function(event) {
console.log("收到推送信息："+JSON.stringify(event));
});3.3 监听通知消息点击
/**
* 监听通知消息点击事件
* 消息字段如下：
* msgId?: string // 通知 id
* title?: string // 通知标题
* content?: string// 通知内容
* extras?: Record<string, Object>// 自定义数据
* channel?: number // 数据来源通道 0:厂商通道 1:极光通道（开始支持的版本：JPush OpenHarmony SDK v1.3.0）
*/
document.addEventListener("jpush.receiveInAppMessageClick", function(event) {
message += "点击推送信息："+JSON.stringify(event)+"<br>";
document.getElementById("jPushRid1").innerHTML = message;
});4 推送服务控制
4.1 停止推送服务
/**
* 停止推送服务（停止后无法接收推送，需调用 resumePush 恢复）
*/
window.JPush.stopPush();4.2 恢复推送服务
/**
* 恢复推送服务
*/
window.JPush.resumePush();4.3 检查推送服务状态
/**
* 检查推送服务是否已开启
* @param {Function} callback - 回调函数（参数：是否开启）
*/
window.JPush.isPushStopped((isStopped) => {
if (isStopped) {
console.log("推送服务已停止，正在恢复...");
window.JPush.resumePush();
}
});目录结构
jpush-phonegap-plugin # [根目录] 极光推送插件项目根目录
├── src # [源码目录] 存放原生平台代码
│ └── main # [主目录] 主代码目录
│ ├── cpp # [C++ 目录] C++ 原生代码目录
│ │ └── JPush # [C++ 模块] 极光推送核心逻辑文件夹
│ │ ├── JPushPlugin.cpp # [C++ 实现] 插件主逻辑，负责与极光 SDK 交互（初始化、注册、收消息）
│ │ └── JPushPlugin.h # [C++ 声明] 插件接口定义
│ └── ets # [ArkTS 目录] ArkTS/ETS 代码目录
│ └── components # [组件目录] 存放 UI 组件
│ └── JPush # [TS 模块] 推送相关的 UI 组件文件夹
│ └── JPushAction.ets # [ETS 文件] 处理推送点击事件或展示相关 UI 的组件
├── www # [前端目录] 存放 JS 接口文件
│ └── JPushPlugin.js # [JS 接口] 供前端调用的 JavaScript 接口文件
├── .gitignore # [配置] Git 版本控制忽略文件配置
├── LICENSE # [文本] 开源许可证文件
├── OAT.xml # [配置] 门禁配置文件
├── package.json # [配置] NPM 包配置文件
├── plugin.xml # [配置] Cordova/PhoneGap 插件核心配置文件
└── README.md # [文档] 项目说明文档贡献代码
使用过程中发现任何问题都可以提 Issue ，当然也非常欢迎发 PR 共建。
许可证
本插件基于 Apache License 2.0 开源，详见 LICENSE 文件。
官方资源
Android 和 iOS：jpush-phonegap-plugin 官方指南
GitCode 仓库：CPF-Cordova/jpush-phonegap-plugin