expo-jpush

Expo JPush module for Expo / React Native projects.

API documentation

• Documentation for the latest stable release
• Documentation for the main branch

Installation in managed Expo projects

For managed Expo projects, please follow the installation instructions in the API documentation for the latest stable release. If you follow the link and there is no documentation available then this library is not yet usable within managed projects — it is likely to be included in an upcoming Expo SDK release.

Installation in bare React Native projects

For bare React Native projects, you must ensure that you have installed and configured the expo package before continuing.

Add the package to your npm dependencies

npm install lm-expo-jpush

Configure for Android

Android 8.0+ requires a notification channel_id for notification display. This is different from the JPush install/statistics channel value.

Configure a default client channel in app.json:

[
  "lm-expo-jpush",
  {
    "appKey": "your-jpush-app-key",
    "channel": "dev",
    "android": {
      "notificationChannels": [
        {
          "id": "push_oplus_category_content",
          "name": "内容与营销",
          "importance": "high"
        }
      ],
      "vendorChannels": {
        "oppo": {
          "enabled": true,
          "appKey": "OP-your-oppo-app-key",
          "appId": "OP-your-oppo-app-id",
          "appSecret": "OP-your-oppo-app-secret"
        },
        "vivo": {
          "enabled": true,
          "appKey": "your-vivo-app-key",
          "appId": "your-vivo-app-id"
        },
        "xiaomi": {
          "enabled": true,
          "appKey": "your-xiaomi-app-key",
          "appId": "your-xiaomi-app-id"
        }
      }
    }
  }
]

notificationChannels[].id creates the Android notification channel used by notification.android.channel_id. It does not register the phone with OPPO's system push service by itself. For OPPO background/offline delivery, enable the OPPO vendor channel and provide the OPPO AppKey/AppID/AppSecret values with the OP- prefix required by OPPO/JPush. For vivo background/offline delivery, enable the vivo vendor channel and provide the vivo AppKey/AppID values. For Xiaomi background/offline delivery, enable the Xiaomi vendor channel and provide the Xiaomi AppKey/AppID values.

For local examples, you can keep secrets out of source by enabling OPPO/vivo/ Xiaomi in app.json and passing these environment variables before prebuild/run:

JPUSH_OPPO_APPKEY=OP-your-oppo-app-key
JPUSH_OPPO_APPID=OP-your-oppo-app-id
JPUSH_OPPO_APPSECRET=OP-your-oppo-app-secret
JPUSH_VIVO_APPKEY=your-vivo-app-key
JPUSH_VIVO_APPID=your-vivo-app-id
JPUSH_XIAOMI_APPKEY=your-xiaomi-app-key
JPUSH_XIAOMI_APPID=your-xiaomi-app-id

For example:

JPUSH_OPPO_APPKEY=OP-your-oppo-app-key \
JPUSH_OPPO_APPID=OP-your-oppo-app-id \
JPUSH_OPPO_APPSECRET=OP-your-oppo-app-secret \
JPUSH_VIVO_APPKEY=your-vivo-app-key \
JPUSH_VIVO_APPID=your-vivo-app-id \
JPUSH_XIAOMI_APPKEY=your-xiaomi-app-key \
JPUSH_XIAOMI_APPID=your-xiaomi-app-id \
npx expo run:android --device PJE110

When the OPPO, vivo, or Xiaomi vendor channel is enabled, the config plugin fails prebuild early if any required values are missing. This prevents building an APK whose manufacturer channel manifest values are empty.

With debug: true, a successful OPPO vendor registration should include logs similar to OPushCallback ... registerID and ThirdPushManager uploadRegID with platform=4. If the push strategy is "only manufacturer channel, discard on failure" and no push record is produced, the device usually has no valid manufacturer channel target yet.

When pushing Android notification messages, send the same value as notification.android.channel_id. For OPPO devices, JPush's manufacturer classification also needs the OPPO fields under options.third_party_channel.oppo, for example:

{
  "notification": {
    "android": {
      "alert": "hello",
      "title": "JPush",
      "channel_id": "push_oplus_category_content"
    }
  },
  "options": {
    "classification": 1,
    "third_party_channel": {
      "oppo": {
        "channel_id": "push_oplus_category_content",
        "category": "IM",
        "notify_level": 16
      }
    }
  }
}

When using the JPush web console, set the same channel in both places:

• Android config notification template: 渠道 ID = push_oplus_category_content
• OPPO vendor settings: channel_id = push_oplus_category_content, category = IM, notify_level = 16

If the Android notification template still shows 渠道 ID：--, the Android notification itself is missing channel_id, even when the OPPO vendor settings are filled.

Custom messages are pass-through messages and are not displayed in the system notification tray by the JPush SDK.

Configure for iOS

Run npx pod-install after installing the npm package.

Publish to npm

This repository is configured to publish to the public npm registry:

npm install
npm run build
npm run build:plugin
npm pack --dry-run

After verifying the package contents, bump the version and publish:

npm version patch
npm publish

Contributing

Contributions are very welcome! Please refer to guidelines described in the contributing guide.

prebuild

cd example & npx expo prebuild --platform android

真机调试 exmaple

npx expo run:android --device PJE110