# jpush-phonegap-plugin: JPush push notifications for Cordova apps

> The JPush PhoneGap and Cordova plugin wires the JiGuang push service into a hybrid app for both Android and iOS, with the APP_KEY and CHANNEL installation variables and an Ionic wrapper package. The install path is short, but the plugin carries hard constraints on cordova-android versions, on the app package name matching the key, and on how Android background delivery actually works.

**jpush/jpush-phonegap-plugin** — JPush's officially supported PhoneGap/Cordova plugin (Android & iOS).  极光推送官方支持的 PhoneGap/Cordova 插件（Android & iOS）。

- Repository: https://github.com/jpush/jpush-phonegap-plugin
- Website: https://docs.jiguang.cn
- Stars: 922 · Forks: 351
- Language: JavaScript
- License: MIT
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/jpush-jpush-phonegap-plugin

## The install variable that decides whether registration works

The plugin is the officially supported Cordova and PhoneGap wrapper for the JiGuang push service, covering both Android and iOS. The installation itself is one command, and the important part is the variable you pass.

```shell
cordova plugin add jpush-phonegap-plugin --variable APP_KEY=your_jpush_appkey
```

APP_KEY is mandatory, and it is the Appkey belonging to the package name registered on JPush. The plugin documentation puts a warning at the top of the install section that is worth repeating: the application package name must match the package name of the APP_KEY application on the service, otherwise registration cannot succeed. This is the single most common reason a fresh install receives nothing.

CHANNEL is optional and was added in v3.6.0 for Android only. It exists so that developers can track APK distribution channels, and it defaults to developer-default. You can set both at once when you install.

```shell
cordova plugin add jpush-phonegap-plugin --variable APP_KEY=your_jpush_appkey --variable CHANNEL=your_channel
```

There are two alternative install routes, from a git URL and from a local path, and both take the same variables. The Cordova CLI 5.0 or newer is required for the plugin registry route. The repository itself contains no bundled native SDK packages any more: Android pulls JPush 6.2.0 through Maven and iOS pulls JPush 6.2.0 through CocoaPods, with the companion cordova-plugin-jcore 5.3.2 providing Android and iOS JCore 5.5.0.

## A hard floor at cordova-android 7.0.0

There is a compatibility boundary in the plugin history that catches people upgrading. From v3.4.0 the plugin supports cordova-android 7.0.0, and because that release changed the Android project structure, the plugin is not compatible with earlier cordova-android versions. The documentation says plainly that you must pay attention to this before upgrading.

If you need to integrate a recent plugin with a cordova-android older than 7.0.0, a specific article is referenced for that case. The advice is precise: to install an older version of the plugin, first install the cordova-plugin-jcore at v1.2.0 or below, with v1.1.12 suggested, and only then install the old plugin such as v3.3.2, otherwise you get a runtime error.

The package.json formalises the same constraint on the JavaScript side. The devDependencies list cordova-plugin-jcore at >=5.3.2 <6.0.0, alongside cordova-plugin-device, and the cordova block declares the plugin id jpush-phonegap-plugin with the ios and android platforms. So the current release expects the modern jcore line, and the older plugin expects the old one, and mixing them is what produces errors.

A table linking Cordova Android versions to native versions is linked for working out which combination applies to your project.

## What is inside the plugin and how to explore the API

The top level layout is small and conventional for a Cordova plugin. plugin.xml describes the plugin to the CLI, src/ holds the JavaScript implementation, www/ holds the JavaScript that is copied into the app, hooks/ contains the build hooks, doc/ holds the API documents, example/ contains a demo, and ionic/ contains the Ionic wrapper package and an example.

The API is documented in three files that split by platform rather than by feature. There is a common document for the shared API, an iOS document and an Android document, and each covers the platform specific behaviour of the same calls. This split matters in practice because the two platforms genuinely differ, especially around notification handling.

The demo is a plain HTML and JavaScript application. To use it in your project, copy three things: example/index.html to www/index.html, the contents of example/css to www/css, and the contents of example/js to www/js. That gives you working JavaScript calls against the plugin without writing any native code.

For Ionic users there is a separate npm package, @jiguang-ionic/jpush, which adapts the plugin for ionic-native.

```shell
npm install --save @jiguang-ionic/jpush@1.0.2

# npm install --save @jiguang-ionic/jpush@2.0.1 for ionic4+
```

The import path differs between the two major versions of that wrapper, and both forms are shown in the documentation.

```js
// @jiguang-ionic/jpush@1.0.0+
import { JPush } from '@jiguang-ionic/jpush';

// @jiguang-ionic/jpush@2.0.1+
import { JPush } from '@jiguang-ionic/jpush/ngx';
...
  providers: [
    ...
    JPush,
    ...
  ]
```

## Android background delivery depends on a connection you do not control

The Android FAQ explains why notifications stop arriving after the app is closed, and the answer is not something a plugin can configure around. Android push is implemented over a long connection, so notifications only arrive while that connection is alive. Some third party ROMs restrict auto start for ordinary application services, which means after the app is closed all of its services are killed and cannot restart, and no notification arrives.

The mitigation described is a cross application wake up mechanism. When a user opens another application that also integrates JPush, your application receives push messages at the same time. The official recommendation for an application that needs notifications at any time is to guide the user through settings text that allows the app to auto start, with per model instructions linked from the JPush Android documentation. Implementing your own keep alive is mentioned and explicitly not recommended.

The comparison drawn in the documentation is that large applications such as QQ and WeChat keep receiving notifications after exit because manufacturers add them to the auto start allow list by default and do not kill their services, and that any non large application left unused for a while will stop receiving pushes.

Custom notification sounds are the other platform split. On Android, where each ROM customises notifications differently, the recommendation is to send a custom message from JPush and trigger the notification from the jpush.receiveMessage listener using the Cordova Local-Notification Plugin, with the Cordova Background Mode plugin keeping the application running in the background.

## iOS setup, PushConfig.plist and the Xcode 8 requirement

On iOS the plugin needs a capability enabled before anything works. The install notes say that when debugging an iOS project with Xcode 8 or newer, you must first turn on the Push Notifications switch in the Capabilities section of the project configuration screen.

The PushConfig.plist file in the project carries four fields, and their meanings are documented: Appkey is the application identifier, Channel is the channel identifier, IsProduction marks whether it is a production environment, and IsIDFA indicates whether the SDK is started with IDFA.

Two iOS problems have documented remedies. If pushes are not received in Xcode 10, the instruction is to open the workspace settings and change the build system to Legacy Build System, then uninstall the app and run it again. If packaging fails with an i386 error, the fix is a platform update.

```shell
cordova platform update ios
```

If a newly integrated plugin receives nothing at all, the first step is to configure the certificate and provisioning profile again, following the linked iOS certificate setup guide. For a white screen, a plugin that will not start, or a packaging error about missing files, the documentation gives a short ordered list: upgrade to the latest Xcode, then delete the plugin and reinstall it, using cordova platform add ios first and cordova plugin add afterwards.

One build service is ruled out explicitly. The project is implemented on Cordova, so it cannot be packaged with the PhoneGap Build cloud service, and local packaging is recommended.

## Release history, licence and where support actually comes from

The version numbers tell a story with a gap in it. The listed releases are v6.0.4 from 2026-07-29, then v4.8.5 from 2022-12-23 and v3.8.2 from 2021-07-28. The repository is not archived and the last push was on 2026-07-29, matching the newest tag, so work is happening now even though the intervening 5.x line does not appear in the tag list. The CHANGELOG.md file at the repository root carries the detailed history.

The licence is MIT, credited to JiGuang, and the same terms appear in the package.json, which is also where the author is listed as JiGuang. The homepage points at the JiGuang documentation site, and the project maintains a weibo account and links its community forum.

Support is organised through the project's own channels. The documentation lists two QQ groups, the JPush official documentation and the JiGuang community. For code questions, the guidance is to check the demo and the API documents first, and only then open an issue.

Three sibling plugins are named for adjacent needs: jmessage-phonegap-plugin for instant messaging, cordova-plugin-jsms for SMS verification codes, and cordova-plugin-janalytics for analytics. They are separate repositories rather than features of this one, which is worth knowing before you look for a combined install.

## Conclusion

Adopt the JPush Cordova plugin if you are maintaining a hybrid app that already ships through Cordova and need JiGuang push on both Android and iOS, since the install is a single command and the native SDKs are pulled by Maven and CocoaPods rather than bundled. Do not adopt it for a new project that could use a native SDK directly, and do not expect it to fix background delivery on aggressive Android ROMs, because the documented answer there is a long connection plus vendor cooperation, not a plugin setting. Verify first that your app package name matches the package registered on the JPush console for your APP_KEY, that you are on cordova-android 7.0.0 or later if you use a recent plugin version, and that on iOS you enable the Push Notifications capability in Xcode before debugging with Xcode 8 or newer.

## FAQ

### How do I install the JPush Cordova plugin?

With Cordova CLI 5.0 or newer, run cordova plugin add jpush-phonegap-plugin --variable APP_KEY=your_jpush_appkey. The APP_KEY variable is mandatory and must belong to the application whose package name matches your app, otherwise registration fails.

### Why does my Cordova app stop receiving notifications after being closed on Android?

Android push uses a long connection, and some third party ROMs limit auto start for ordinary application services, killing them when the app exits. The documented mitigations are the cross application wake up mechanism and guiding the user to allow auto start in system settings, with implementing your own keep alive explicitly not recommended.

### Which cordova-android versions does the JPush plugin support?

From v3.6.0 the plugin supports cordova-android 7.0.0, and because that release changed the Android project structure it is not compatible with earlier versions. To use an older plugin you must first install cordova-plugin-jcore at v1.2.0 or below, with v1.1.12 suggested.

### How do I use the JPush plugin with Ionic?

Install the @jiguang-ionic/jpush package, using version 1.0.2 for older Ionic and 2.0.1 for Ionic 4 and later, then import JPush in app.module.ts from @jiguang-ionic/jpush or from @jiguang-ionic/jpush/ngx and add it to the providers list.

## Sources

- [jpush/jpush-phonegap-plugin on GitHub](https://github.com/jpush/jpush-phonegap-plugin)
- [License: MIT](https://github.com/jpush/jpush-phonegap-plugin/blob/master/LICENSE)
- [Project website](https://docs.jiguang.cn)
- [README](https://github.com/jpush/jpush-phonegap-plugin/blob/master/README.md)
- [Releases](https://github.com/jpush/jpush-phonegap-plugin/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/jpush-jpush-phonegap-plugin