capacitor-plugin-jpush
v4.0.1TypeScript
jpush plugin for capacitor3.0+
0/weekUpdated 6 days agoMITUnpacked: 27.6 MB
Published by zhuxian
npm install capacitor-plugin-jpushcapacitor-plugin-jpush
简体中文 | English
一款基于 Capacitor 3.0+ 的极光推送插件，如果有使用上的问题，欢迎提 issue，我会尽力解决，也欢迎贡献你的代码。 如果这个插件帮助到了你，请不要吝啬你的 star，万分感谢！！
- v0.x 版本支持 Capacitor4 及更早版本
- v1.0+ 版本支持 Capacitor5
- v2.0+ 版本支持 Capacitor6
- v3.0+ 版本支持 Capacitor7
- v4.0+ 版本支持 Capacitor8
> 重要更新 ：0.x 版本无需手动初始化极光推送服务，在 capacitor.config.ts中配置了 appKey，应用启动时便会自动注册极光服务。 1.x 版本开始需要手动调用 startJPush 方法注册极光服务。
> 关于产商通道：Android 目前暂未支持产商通道推送, 有兴趣开发的兄弟可以提PR
安装
``bash
npm install capacitor-plugin-jpush
npx cap sync
`
使用
在 capacitor.config.ts 配置你的极光推送 Appkey 等相关信息, 并且确保你的应用包名和极光后台设置的一致:
`ts
///
import { CapacitorConfig } from '@capacitor/cli';
const config: CapacitorConfig = {
plugins: {
JPush: {
// your application appKey on JPush
appKey: '',
channel: '',
},
},
};
export default config;
`
或者在 capacitor.config.json 中配置:
`json`
{
"plugins": {
"JPush": {
"appKey": "",
"channel": ""
}
}
}
$3
目前 IOS 的极光推送版本是 5.0.0，在 iOS 上，您必须启用推送通知功能。 详见 Setting Capabilities 文档如何启用推送功能（如未启用，会导致 JPush 无法注册 deviceToken）。
> 你本机的 Xcode 需要使用 Xcode 14 及以上版本，请注意升级！
在打开了推送通知功能之后, 添加以下代码到 IOS 应用的 AppDelegate.swift 文件:
`swift
import Foundation
func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
NotificationCenter.default.post(name: .capacitorDidRegisterForRemoteNotifications, object: deviceToken)
}
func application(_ application: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: Error) {
NotificationCenter.default.post(name: .capacitorDidFailToRegisterForRemoteNotifications, object: error)
}
// iOS10以上静默推送会走该回调
func application(
_ application: UIApplication,
didReceiveRemoteNotification userInfo: [AnyHashable: Any],
fetchCompletionHandler completionHandler:
@escaping (UIBackgroundFetchResult) -> Void
) {
// 注意调用
NotificationCenter.default.post(
name: Notification.Name(rawValue: "didReceiveRemoteNotification"),
object: userInfo
)
completionHandler(.newData)
}
// 这个函数 capacitor 生成的项目中可能自带, 只需将里面的内容复制过去即可
func applicationDidBecomeActive(_ application: UIApplication) {
NotificationCenter.default.post(name: Notification.Name(rawValue: "didBecomeActiveNotification"), object: nil)
}
`
然后找到极光推送的依赖包文件, 也就是 JPUSHService.h，点击此文件，在编辑器右边窗口找到 Target MemberShip，将 CapacitorPluginJPush 勾选中，并将它的值设置为 Public 如下图所示（如果没有找到该依赖文件，请在你的前端项目先运行命令 npx cap sync ios，如果是 Ionic 项目，则是运行 ionic cap sync ios）:
$3
Android 13 之后系统必须要有推送通知权限才可以收到推送消息，所以你可以通过 checkPermissions() 方法来检查你的应用是否开启了通知权限，如果没有，则可以通过 requestPermissions() 来启用通知权限，如果用户拒绝了，可以通过调用 openNotificationSetting() 方法来打开通知权限设置页面，
在 Android 12 及更老的设备，系统默认启用推送通知权限。
在你安卓应用根目录下找到 variables.gradle 文件，将 compileSdkVersion 和 targetSdkVersion 值设置为 33 ，如果已经是 33 以上 可以忽略此步骤.
代码示例
`ts
import { Capacitor } from '@capacitor/core';
import { JPush } from 'capacitor-plugin-jpush';
const JPushSetup = async () => {
if (Capacitor.isNativePlatform()) {
// 推送事件监听
const receivedEvent = await JPush.addListener('notificationReceived', (data) => {
console.log(data);
});
// 若不需要监听，移除即可
receivedEvent.remove();
JPush.addListener('notificationOpened', (data) => {
console.log(data);
});
// 监听静默推送事件，仅 IOS 支持
JPush.addListener('silentNotification', (data) => {
console.log('silentNotification', data);
});
// 检测是否有通知权限
JPush.checkPermissions().then(async ({ permission }) => {
console.log(permission);
if (permission !== 'granted') {
// 申请通知权限
JPush.requestPermissions().then(async (res) => {
console.log(res.permission);
if (res.permission === 'granted') {
// 初始化极光推送
await JPush.startJPush();
}
});
return;
}
// 初始化极光推送
await JPush.startJPush();
});
}
};
const JPushMethods = async () => {
// 设置推送别名
await JPush.setAlias({
alias: 'alias',
});
// getRegistrationID
const { registrationId } = await JPush.getRegistrationID();
console.log(registrationId);
// ......
};
`
API
* startJPush()
* setDebugMode(...)
* setAlias(...)
* deleteAlias(...)
* addTags(...)
* deleteTags(...)
* cleanTags()
* setBadgeNumber(...)
* removeListeners()
* getRegistrationID()
* checkPermissions()
* requestPermissions()
* openNotificationSetting()
* addListener('notificationReceived', ...)
* addListener('notificationOpened', ...)
* addListener('silentNotification', ...)
* Interfaces
* Type Aliases
$3
`typescript`
startJPush() => Promise
启动极光推送服务，即使没有获取到通知权限，也会进行推送服务初始化
--------------------
$3
`typescript`
setDebugMode(isDebug: boolean) => Promise
开启 debug 模式 log日志
| Param | Type |
| ------------- | -------------------- |
| isDebug | boolean |
--------------------
$3
`typescript`
setAlias(options: AliasOptions) => Promise
设置推送别名，可作为推送消息的目标对象
| Param | Type |
| ------------- | ----------------------------------------------------- |
| options | AliasOptions |
--------------------
$3
`typescript`
deleteAlias(options?: DeleteAlias | undefined) => Promise
删除推送别名
| Param | Type |
| ------------- | --------------------------------------------------- |
| options | DeleteAlias |
--------------------
$3
`typescript`
addTags(options: SetTagsOptions) => Promise
设置推送标签
| Param | Type |
| ------------- | --------------------------------------------------------- |
| options | SetTagsOptions |
--------------------
$3
`typescript`
deleteTags(options: SetTagsOptions) => Promise
删除推送标签
| Param | Type |
| ------------- | --------------------------------------------------------- |
| options | SetTagsOptions |
--------------------
$3
`typescript`
cleanTags() => Promise
--------------------
$3
`typescript`
setBadgeNumber(options?: SetBadgeNumberOptions | undefined) => Promise
设置 APP 角标数字，设为 0 即清空角标
| Param | Type |
| ------------- | ----------------------------------------------------------------------- |
| options | SetBadgeNumberOptions |
--------------------
$3
`typescript`
removeListeners() => Promise
--------------------
$3
`typescript`
getRegistrationID() => Promise<{ registrationId: string; }>
获取设备的注册 ID，若服务重新注册，则返回的 ID 是不一样的
Returns: Promise<{ registrationId: string; }>
--------------------
$3
`typescript`
checkPermissions() => Promise
检查通知权限状态
Returns: Promise<PermissionStatus>
--------------------
$3
`typescript`
requestPermissions() => Promise
申请通知权限
Returns: Promise<PermissionStatus>
--------------------
$3
`typescript`
openNotificationSetting() => Promise
打开推送通知权限设置页面（目前仅安卓支持）
--------------------
$3
`typescript`
addListener(eventName: 'notificationReceived', listenerFunc: (notificationData: ReceiveNotificationData) => void) => Promise
监听推送消息
| Param | Type |
| ------------------ | ---------------------------------------------------------------------------------------------------------- |
| eventName | 'notificationReceived' |
| listenerFunc | (notificationData: ReceiveNotificationData) => void |
Returns: Promise<PluginListenerHandle>
--------------------
$3
`typescript`
addListener(eventName: 'notificationOpened', listenerFunc: (notificationData: ReceiveNotificationData) => void) => Promise
监听消息栏通知被点击
| Param | Type |
| ------------------ | ---------------------------------------------------------------------------------------------------------- |
| eventName | 'notificationOpened' |
| listenerFunc | (notificationData: ReceiveNotificationData) => void |
Returns: Promise<PluginListenerHandle>
--------------------
$3
`typescript`
addListener(eventName: 'silentNotification', listenerFunc: (silentData: SilentData) => void) => Promise
监听静默推送通知，仅 IOS 支持该事件
| Param | Type |
| ------------------ | -------------------------------------------------------------------------- |
| eventName | 'silentNotification' |
| listenerFunc | (silentData: SilentData) => void |
Returns: Promise<PluginListenerHandle>
--------------------
$3
#### AliasOptions
| Prop | Type |
| -------------- | ------------------- |
| alias | string |
| sequence | number |
#### DeleteAlias
| Prop | Type |
| -------------- | ------------------- |
| sequence | number |
#### SetTagsOptions
| Prop | Type |
| ---------- | --------------------- |
| tags | string[] |
#### SetBadgeNumberOptions
| Prop | Type |
| ----------- | ------------------- |
| badge | number |
#### PermissionStatus
| Prop | Type | Description |
| ---------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------- |
| permission | PermissionState | prompt: 首次申请，询问。 prompt-with-rationale： 每次都询问。 granted： 已获取权限。 denied：权限已拒绝。 |
#### PluginListenerHandle
| Prop | Type |
| ------------ | ----------------------------------------- |
| remove | () => Promise<void> |
#### ReceiveNotificationData
| Prop | Type |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| title | string |
| content | string |
| subTitle | string |
| rawData | { [x: string]: any; aps: { alert: { body: string; subTitle: string; title: string; }; badge: number; sound: string; }; } |
#### SilentData
| Prop | Type |
| ----------------- | --------------------------------------------- |
| _j_business | string |
| _j_msgid | string |
| _j_data_ | string |
| _j_uid | string |
| aps` | { 'content-available': number; } |
$3
#### PermissionState
'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'