# jpush-react-native: JPush integration for React Native apps

> jpush-react-native is JPush's official React Native plugin for Android and iOS, with JavaScript APIs backed by native modules. Its setup requires explicit native linking, Android manifest placeholders or Gradle configuration, and iOS workspace changes.

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

- Repository: https://github.com/jpush/jpush-react-native
- Website: http://docs.jiguang.cn
- Stars: 1,380 · Forks: 349
- Language: Java
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/jpush-jpush-react-native

## What jpush-react-native connects to React Native

jpush-react-native solves the native integration problem for applications that need JPush push notification behavior inside a React Native codebase. The repository describes it as JPush's official React Native plugin for Android and iOS. Its package metadata identifies `index.js` as the JavaScript entry point and `index.d.ts` as the TypeScript declaration file. The package targets React Native applications from version `0.50` and newer, while `jcore-react-native` is a peer dependency at `>= 2.3.7`.

The plugin is not a standalone notification product. It is a bridge between JavaScript calls and JPush native modules, so adoption depends on an existing JPush account and application credentials. The Android configuration expects an application ID, a JPush app key, and a channel. On iOS, the instructions point developers to the `.xcworkspace` file, not only the `.xcodeproj` file. That distinction matters because the native library integration can be incomplete if an application edits the wrong Xcode project.

The README also says to run the example project successfully before integrating the package into a production application. That is a practical project-specific check. It does not claim that the plugin works across every React Native version, every Xcode version, or every notification permission configuration.

## The jpush-react-native native module boundary

The repository layout places the JavaScript interface in `index.js`, native Android code under `android/`, and native iOS code under `ios/`. The package metadata declares separate native projects for both JPush and JCore. The README directs Android users to add `implementation project(':jpush-react-native')` and `implementation project(':jcore-react-native')`, then link both directories from `setting.gradle`. This indicates a bridge structure rather than a server-side or JavaScript-only implementation.

The documented Android configuration uses `manifestPlaceholders` to pass `JPUSH_APPKEY` and `JPUSH_CHANNEL` into the application. For plugin versions before `3.2.6`, the README also requires two `AndroidManifest.xml` metadata entries using `${JPUSH_CHANNEL}` and `${JPUSH_APPKEY}`. From version `3.2.6` onward, that manifest configuration is no longer required according to the README. Version handling therefore matters during upgrades: a setup copied from an older integration guide may contain native configuration that the current documentation no longer asks for.

The iOS package contains `RCTJCoreModule.xcodeproj` and `RCTJPushModule.xcodeproj`. The manual path requires adding those files, enabling `Push Notification`, adding header search paths, and linking `UserNotifications.framework`, `libRCTJCoreModule.a`, and `libRCTJPushModule.a`. The plugin therefore exposes native state and notification functionality, but the repository does not document a single cross-platform setup that removes platform-specific work.

## Installing jpush-react-native and linking native code

Install the package from the React Native project root. The README gives the following command and saves the dependency in `package.json`.

```bash
npm install jpush-react-native --save
```

Because `jcore-react-native` is a peer dependency, install it separately when the project does not already contain it.

```bash
npm install jcore-react-native --save
```

After installation, the README asks developers to enter the root directory and run the React Native linker.

```bash
react-native link
```

The README also documents package-specific linking.

```bash
react-native link jpush-react-native
react-native link jcore-react-native
```

These commands are intended to connect the JavaScript packages to the native projects. The documentation does not explain which React Native release first made automatic linking available, nor does it provide a rollback command. After linking, Android developers must inspect `build.gradle` and `setting.gradle`, while iOS developers must use the `.xcworkspace` file and run the CocoaPods command documented for that platform.

## Android and iOS configuration requirements

Android integration starts with manifest placeholders in `build.gradle`. Replace the example package name, app key, and channel with the values for the application.

```gradle
android {
      defaultConfig {
            applicationId "yourApplicationId"
            manifestPlaceholders = [
                    JPUSH_APPKEY: "yourAppKey",
                    JPUSH_CHANNEL: "yourChannel"
            ]
      }
}
```

The repository also requires the two native project dependencies.

```gradle
dependencies {
      implementation project(':jpush-react-native')
      implementation project(':jcore-react-native')
}
```

For older plugin versions, the README shows `AndroidManifest.xml` metadata entries. The current README states that these entries are not needed from version `3.2.6` onward, and the listed recent release is `3.2.8`.

On iOS, the README says to open the `.xcworkspace` under the `ios` directory. For a CocoaPods setup, the documented command is:

```bash
pod install
```

If CocoaPods was already used, the README gives this preparation command:

```bash
pod deintegrate
```

The manual alternative requires adding both `RCTJCoreModule.xcodeproj` and `RCTJPushModule.xcodeproj`, enabling `Push Notification`, adding two header search paths, and linking the listed frameworks and static libraries. The README does not document signing, provisioning, notification permission prompts, or production certificate setup.

## Using the Android vendor-channel command API

The documented JavaScript API includes an Android-specific command for requesting subscription vendor notification channels. The README states that JPush Android SDK `6.2.0` introduced support. Its current scope is narrow: the feature supports Xiaomi devices that already have the Xiaomi channel integrated and registered. The application must be in the foreground and the screen must be lit.

The example registers a listener, requests up to three approved Xiaomi channel IDs, and removes the listener when the page is destroyed.

```javascript
const commandListener = result => {
  if (result.command === 2012) {
    const channelResults = result.openChannelResult
      ? JSON.parse(result.openChannelResult)
      : [];
    console.log(result.commandResult, result.platform, channelResults);
  }
};

JPush.addCommandEventListener(commandListener);
JPush.requestSubscribeChannel(["YOUR_XIAOMI_CHANNEL_ID"]);
```

The callback uses `command === 2012`. `commandResult` value `0` means the system dialog opened and returned a user result. Negative values distinguish unsupported SDK versions, authentication failures, foreground or screen-state violations, frequency limits, cancellation, and missing notification permission. `openChannelResult` is a JSON string, so the example parses it before logging it. The documented frequency limits are one dialog attempt within 30 seconds and two attempts per month for the same channel.

This API is not a general vendor-channel manager. The documentation limits it to registered Xiaomi channels, approved subscription channel IDs, foreground execution, and a maximum of three channel IDs per request. The repository does not document equivalent iOS behavior.

## Limitations, licensing, and maintenance signals

The main limitation is integration depth. jpush-react-native requires changes in Gradle, `setting.gradle`, Android manifests for older versions, CocoaPods or manual Xcode setup, and application-specific credentials. The README does not document automated link verification, rollback, production signing, permission-denied recovery, or behavior when a native linker is incompatible with the React Native version in use. The example project's success is the main practical validation step named by the documentation.

The repository metadata presents conflicting licensing information. The repository description identifies the project as MIT, while `package.json` declares `"license": "ISC"` and includes an MIT `LICENSE` file at the repository root. That discrepancy should be resolved with the project owner before redistribution or compliance review. This is a repository metadata issue, not legal advice.

The repository is not archived. Its last push was on 2026-07-29, and version `3.2.8` was released on 2026-07-29. That indicates a recent change at the time represented by the repository data, but the README does not promise a release cadence or long-term compatibility policy. Upgrade cost includes checking the `3.2.6` manifest change, reviewing native project links, and confirming that both the JavaScript package and `jcore-react-native` remain compatible.

## Conclusion

Adopt jpush-react-native when a React Native application already depends on JPush and can maintain separate Android and iOS native setup. Do not choose it for a JavaScript-only integration or for projects that need documented rollback behavior, which the README does not cover. Verify the intended React Native version, the required jcore-react-native dependency, the Android configuration for the installed plugin version, and the iOS workspace before migration.

## FAQ

### How do I install jpush-react-native in a React Native project?

Run `npm install jpush-react-native --save`. Install `jcore-react-native` as well if the project does not already have it, then use the React Native linker as described in the README.

### What is the difference between jpush-react-native and jcore-react-native?

`jpush-react-native` provides the JPush React Native plugin, while `jcore-react-native` is a required peer dependency for the JCore native module. The README requires both packages to be linked on Android and included in the iOS native setup.

### Does jpush-react-native require AndroidManifest.xml configuration?

The README shows metadata configuration for older plugin versions but states that it is not needed from version `3.2.6` onward. The Gradle configuration and native project dependencies are still part of the documented Android integration.

## Sources

- [jpush/jpush-react-native on GitHub](https://github.com/jpush/jpush-react-native)
- [License: MIT](https://github.com/jpush/jpush-react-native/blob/master/LICENSE)
- [Project website](http://docs.jiguang.cn)
- [README](https://github.com/jpush/jpush-react-native/blob/master/README.md)
- [Releases](https://github.com/jpush/jpush-react-native/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-react-native