@cordova-ohos/jpush-phonegap-plugin

v5.9.0

Published

3 months ago

Cordova JPush Plugin

Downloads

410

0High
0Medium
0Low

cordova insomnia ecosystem:cordova cordova-openharmony

jpush-phonegap-plugin

jpush-phonegap-plugin 是极光推送（JPush）官方提供的 Cordova 插件，为跨平台（Android/iOS/OHOS）移动应用提供稳定、高效的推送通知能力。支持自定义消息、通知栏样式定制、推送状态监听等核心功能，助力开发者快速实现全场景消息触达。

1. 插件概述

作为极光推送生态的核心插件，jpush-phonegap-plugin 基于极光推送的har包的基础能力，提供以下核心功能：

消息类型全覆盖：支持通知消息、自定义消息（纯数据透传）
精准触达：支持别名、标签、注册 ID 等多维度目标定位
状态可视化：提供推送注册、消息接收、点击等全链路事件监听
调试友好：内置调试模式，实时反馈服务注册及消息处理状态

该插件已广泛应用于电商、社交、工具等各类应用，经过亿级设备验证，具备高可靠性和兼容性。

2. 前置准备

使用插件前需完成极光推送开发者平台配置，步骤如下：

注册账号：访问极光推送官网注册开发者账号
创建应用：在控制台创建应用，获取唯一标识 APP_KEY
平台配置：

OHOS的配置参考极光推送官网配置相关参数，这里不做详细说明。

3. 安装方式

3.1 基础安装（推荐）

OHOS平台安装无需指定APP_KEY参数，APP_KEY在PluginRegisterHandle传入，请参考OHOS配置说明

# 安装hcordova
npm install -g hcordova

# 直接安装最新版本,说明：
hcordova plugin add jpush-phonegap-plugin

# 指定版本安装

hcordova plugin add [email protected] --platform ohos

3.2 源码安装

如需使用开发中的最新功能，可从 GitHub 仓库安装：

cordova plugin add https://gitcode.com/OpenHarmony-Cordova/jpush-phonegap-plugin.git  --platform ohos

3.3 卸载插件

卸载时需先移除当前插件，再移除依赖的核心库：

# 卸载主插件
hcordova plugin remove jpush-phonegap-plugin

4. OHOS配置

4.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",
    "@magongshou/harmony-cordova": "file:../cordova"
  }
}

4.2 工程级（最外层）build-profile.json5，配置"useNormalizedOHMUrl": true

"products": [
    {
    "name": "default",
    "signingConfig": "default",
    "compatibleSdkVersion": "5.0.0(12)",
    "runtimeOS": "HarmonyOS",
    "buildOption": {
        "strictMode": {
        "caseSensitiveCheck": true,
        "useNormalizedOHMUrl": true
        }
    }
    }
]

4.3. 修改项目中的EntryAbility的代码，添加极光推送插件在ArkTS侧监听和初始化：

export default class EntryAbility extends UIAbility {
   onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
      //添加如下代码，注册Jpush监听插件
      //JPush/JPushAction,动态导入微信插件
      //EntryAbility 微信插件的入口函数
      //5f021e25b536007a2aa2d546为app的APP_KEY，在Jpush的开放平台获取
      PluginRegisterHandle(this, want, "JPush/JPushAction", "EntryAbility", "5f021e25b536007a2aa2d546");
      
   }

   onNewWant(want: Want): void {
      //添加如下代码，注册Jpush监听插件
      //JPush/JPushAction,动态导入微信插件
      //EntryAbility 微信插件的入口函数
      //5f021e25b536007a2aa2d546为app的APP_KEY，在Jpush的开放平台获取
      PluginRegisterHandle(this, want, "JPush/JPushAction", "EntryAbility", "5f021e25b536007a2aa2d546");
   }
}

5. API 文档

插件通过全局对象 window.JPush 暴露 API，所有异步操作通过回调函数返回结果。API 调用需在 deviceready 事件触发后执行。

5.1 初始化与基础配置

5.1.1 初始化推送服务

/**
* 初始化极光推送服务
* 需在 deviceready 事件后调用
*/

window.JPush.init();

5.1.2 开启 / 关闭调试模式

/**

* 开启调试模式（开发环境推荐开启）
* @param {Boolean} enabled - 是否启用调试
*/

window.JPush.setDebugMode(true);
// 关闭调试模式（生产环境必需关闭）
window.JPush.setDebugMode(false);

5.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);
   }
);

5.2 推送目标管理

5.2.1 设置别名（单点推送）

/**

* 设置别名（每个设备仅可设置一个别名，常用于用户ID绑定）
* @param {Number} sequence - 请求序列号（用于匹配请求与响应）
* @param {String} alias - 别名（支持字母、数字、下划线）
*/

window.JPush.setAlias( { 'sequence': 11, 'alias':'alias1' }, function(result) {
    //设置成功
},function(){
    //设置失败
});

5.2.2 设置标签（批量推送）

/**
* 设置标签（每个设备可设置多个标签，用于群体推送）
* @param {Number} sequence - 请求序列号
* @param {Array<String>} tags - 标签数组
*/

window.JPush.setTags( { 'sequence': 7, 'tags': ['tag1', 'tag2'] }, function(result) {
    //设置成功
},function(){
    //设置失败
});

5.3 消息监听

5.3.1 监听注册ID

/*
* 监听注册的ID
* registrationId：string //注册ID
*/
document.addEventListener("jpush.receiveRegistrationId", function(event) {
    //注册ID并不是每次都回调，需要注册ID在init完后，调用jPushGetRegistrationID获取ID
    console.log("收到注册ID:" + JSON.stringify(event));
    
});

5.3.2 监听通知消息接收

/**
*  监听通知消息接收事件
*  消息字段如下：
*  msgId?: string //通知id
*  title?: string //通知标题
*  content?: string //通知内容
*  contentType?: string //通知内容类型
*  extras?: Record<string, Object> //通知自定义键值对
*  ttl?: number //后台下发的信息过期时间，单位秒
*  stime?: number //后台下发时间，毫秒
*  channel?: number //数据来源通道 0:厂商通道 1:极光通道（开始支持的版本：JPush HarmonyOS SDK v1.3.0）
*
*/
document.addEventListener("jpush.receiveMessage", function(event) {
    console.log("收到推送信息："+JSON.stringify(event));
});

5.3.3 监听通知消息点击

/**
* 监听通知消息点击事件
* 消息字段如下：
* msgId?: string //通知id
* title?: string //通知标题
* content?: string//通知内容
* extras?: Record<string, Object>//自定义数据
* channel?: number //数据来源通道 0:厂商通道 1:极光通道（开始支持的版本：JPush HarmonyOS SDK v1.3.0）
*/
document.addEventListener("jpush.receiveInAppMessageClick", function(event) {
    message += "点击推送信息："+JSON.stringify(event)+"<br>";
    document.getElementById("jPushRid1").innerHTML = message;
});

5.4 推送服务控制

5.4.1 停止推送服务

/**
* 停止推送服务（停止后无法接收推送，需调用 resumePush 恢复）
*/
window.JPush.stopPush();

5.4.2 恢复推送服务

/**
* 恢复推送服务
*/

window.JPush.resumePush();

5.4.3 检查推送服务状态

/**
* 检查推送服务是否已开启
* @param {Function} callback - 回调函数（参数：是否开启）
*/

window.JPush.isPushStopped((isStopped) => {
   if (isStopped) {
       console.log("推送服务已停止，正在恢复...");
       window.JPush.resumePush();
   }
});

6. 示例代码

以下示例展示完整封装了成了函数，实现API的各种功能：

var message = "";
function jPushInit() {
    window.JPush.init();
    document.addEventListener("jpush.receiveRegistrationId", function(event) {
        //注册ID并不是每次都回调，需要注册ID在init完后，调用jPushGetRegistrationID获取ID
        message += "收到注册ID:" + JSON.stringify(event)+"<br>";
        document.getElementById("jPushRid1").innerHTML = message;
    });

    document.addEventListener("jpush.receiveMessage", function(event) {
        message += "收到推送信息："+JSON.stringify(event)+"<br>";
        document.getElementById("jPushRid1").innerHTML = message;
    });

    document.addEventListener("jpush.receiveInAppMessageClick", function(event) {
        message += "点击推送信息："+JSON.stringify(event)+"<br>";
        document.getElementById("jPushRid1").innerHTML = message;
    });
}

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.setTags( { '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':'15968845917' }, 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();
}

11. 许可证

本插件采用 Apache 许可证开源，详细许可条款见 LICENSE 文件。

参考资源

Android和iOS：jpush-phonegap-plugin 官方指南
GitCode 仓库：OpenHarmony-Cordova/jpush-phonegap-plugin
极光推送官网配置说明：https://docs.jiguang.cn/jpush/client/HarmonyOS/hmos_guide