jpush-expo-plugin

极光推送 (JPush) Expo 配置插件，兼容 Expo SDK 49+。

安装

``bash


使用 npm

npm install jpush-expo-plugin jpush-react-native jcore-react-native

使用 yarn

yarn add jpush-expo-plugin jpush-react-native jcore-react-native

使用 pnpm

pnpm add jpush-expo-plugin jpush-react-native jcore-react-native
`

配置

$3

在 app.json 或 app.config.js 中添加插件：

app.json

`json
{
"expo": {
"plugins": [
[
"jpush-expo-plugin",
{
"appKey": "你的极光AppKey",
"channel": "developer-default"
}
]
]
}
}
`

app.config.js / app.config.ts

`js
export default {
expo: {
plugins: [
[
'jpush-expo-plugin',
{
appKey: '你的极光AppKey',
channel: 'developer-default',
production: false,
enableEntitlements: true,
},
],
],
},
};
`

$3

`bash
npx expo prebuild
`

$3

`bash


Android

npx expo run:android

iOS

npx expo run:ios
`

插件参数

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| appKey | string | 是 | - | 极光控制台获取的 AppKey |
| channel | string | 是 | - | 渠道名称，用于统计分发渠道 |
| production | boolean | 否 | false | iOS 是否使用生产环境（App Store 发布时设为 true） |
| enableEntitlements | boolean | 否 | true | iOS 是否自动配置推送权限 |

代码中使用

$3

`typescript
import { useEffect } from 'react';
import JPush from 'jpush-react-native';

export default function App() {
useEffect(() => {
// 初始化极光推送
JPush.init({
appKey: '你的极光AppKey',
channel: 'developer-default',
production: false,
});

// 获取 RegistrationID
JPush.getRegistrationID((result) => {
console.log('RegistrationID:', result.registerID);
});
}, []);

return (
// your app
);
}
`

$3

`typescript
import { useEffect } from 'react';
import { Platform } from 'react-native';
import JPush from 'jpush-react-native';

export default function App() {
useEffect(() => {
initJPush();
return () => {
// 清理监听器
JPush.removeListener();
};
}, []);

const initJPush = () => {
// 初始化
JPush.init({
appKey: '你的极光AppKey',
channel: 'developer-default',
production: false,
});

// 获取 RegistrationID
JPush.getRegistrationID((result) => {
console.log('RegistrationID:', result.registerID);
});

// 监听收到推送通知
JPush.addNotificationListener((notification) => {
console.log('收到通知:', notification);
// notification 结构:
// {
// messageID: string,
// title: string,
// content: string,
// extras: object,
// badge: number (iOS),
// ring: string (Android),
// notificationEventType: 'notificationArrived' | 'notificationOpened'
// }
});

// 监听自定义消息
JPush.addCustomMessageListener((message) => {
console.log('收到自定义消息:', message);
});

// 监听本地通知
JPush.addLocalNotificationListener((notification) => {
console.log('收到本地通知:', notification);
});

// iOS: 请求通知权限
if (Platform.OS === 'ios') {
JPush.requestNotificationAuthorization((result) => {
console.log('通知权限:', result);
});
}
};

// 设置别名（用于指定用户推送）
const setAlias = (alias: string) => {
JPush.setAlias({
alias: alias,
sequence: Date.now(),
});
};

// 删除别名
const deleteAlias = () => {
JPush.deleteAlias({
sequence: Date.now(),
});
};

// 设置标签（用于分组推送）
const setTags = (tags: string[]) => {
JPush.setTags({
tags: tags,
sequence: Date.now(),
});
};

// 添加标签
const addTags = (tags: string[]) => {
JPush.addTags({
tags: tags,
sequence: Date.now(),
});
};

// 删除标签
const deleteTags = (tags: string[]) => {
JPush.deleteTags({
tags: tags,
sequence: Date.now(),
});
};

// 清空所有标签
const cleanTags = () => {
JPush.cleanTags({
sequence: Date.now(),
});
};

// 设置角标数字 (iOS)
const setBadge = (badge: number) => {
JPush.setBadge({
badge: badge,
appBadge: badge,
});
};

return (
// your app
);
}
`

$3

`typescript
// hooks/useJPush.ts
import { useEffect, useCallback } from 'react';
import { Platform } from 'react-native';
import JPush from 'jpush-react-native';

interface JPushConfig {
appKey: string;
channel: string;
production?: boolean;
}

interface NotificationCallback {
onNotificationArrived?: (notification: any) => void;
onNotificationOpened?: (notification: any) => void;
onCustomMessage?: (message: any) => void;
}

export function useJPush(config: JPushConfig, callbacks?: NotificationCallback) {
useEffect(() => {
// 初始化
JPush.init({
appKey: config.appKey,
channel: config.channel,
production: config.production ?? false,
});

// 监听通知
JPush.addNotificationListener((notification) => {
if (notification.notificationEventType === 'notificationArrived') {
callbacks?.onNotificationArrived?.(notification);
} else if (notification.notificationEventType === 'notificationOpened') {
callbacks?.onNotificationOpened?.(notification);
}
});

// 监听自定义消息
JPush.addCustomMessageListener((message) => {
callbacks?.onCustomMessage?.(message);
});

// iOS 请求权限
if (Platform.OS === 'ios') {
JPush.requestNotificationAuthorization(() => {});
}

return () => {
JPush.removeListener();
};
}, []);

const setAlias = useCallback((alias: string) => {
JPush.setAlias({ alias, sequence: Date.now() });
}, []);

const deleteAlias = useCallback(() => {
JPush.deleteAlias({ sequence: Date.now() });
}, []);

const setTags = useCallback((tags: string[]) => {
JPush.setTags({ tags, sequence: Date.now() });
}, []);

const getRegistrationID = useCallback(() => {
return new Promise((resolve) => {
JPush.getRegistrationID((result) => {
resolve(result.registerID);
});
});
}, []);

return {
setAlias,
deleteAlias,
setTags,
getRegistrationID,
};
}
`

使用 Hook:

`typescript
import { useJPush } from './hooks/useJPush';

export default function App() {
const { setAlias, setTags, getRegistrationID } = useJPush(
{
appKey: '你的极光AppKey',
channel: 'developer-default',
production: false,
},
{
onNotificationArrived: (notification) => {
console.log('通知到达:', notification);
},
onNotificationOpened: (notification) => {
console.log('通知被点击:', notification);
// 处理通知点击，如跳转页面
},
onCustomMessage: (message) => {
console.log('自定义消息:', message);
},
}
);

// 登录后设置别名
const handleLogin = async (userId: string) => {
setAlias(userId);
};

return (
// your app
);
}
`

插件配置说明

$3

插件会自动完成以下配置：

- 添加权限：POST_NOTIFICATIONS、VIBRATE、RECEIVE_BOOT_COMPLETED
- 在 AndroidManifest.xml 中添加 JPUSH_APPKEY 和 JPUSH_CHANNEL
- 在 build.gradle 中配置 manifestPlaceholders

$3

插件会自动完成以下配置：

- 在 Info.plist 中添加 remote-notification 后台模式
- 在 Entitlements 中配置 aps-environment（开发/生产）

$3

1. 在 Apple Developer 控制台启用 Push Notifications 功能
2. 创建并下载 APNs 证书或密钥
3. 在 极光控制台 上传证书或配置密钥
4. 发布到 App Store 时，将 production 设置为 true

常见问题

$3

1. 确认已在 Apple Developer 启用推送功能
2. 确认已上传 APNs 证书到极光控制台
3. 检查 production 参数是否正确（开发用 false，生产用 true）
4. 真机测试，模拟器不支持推送

$3

1. 确认 appKey 和 channel 配置正确
2. 检查是否有厂商通道配置（华为、小米、OPPO 等）
3. 确认应用未被系统杀死

$3

`typescript
JPush.getRegistrationID((result) => {
console.log('RegistrationID:', result.registerID);
});
`

$3

正常配置即可，EAS Build 会自动执行 prebuild 并应用插件配置。

`bash
eas build --platform all
``

相关链接

- 极光推送官网
- 极光推送文档
- jpush-react-native
- Expo Config Plugins

License

MIT