expo-aliyun-push

React Native Expo 阿里云推送插件包。

安装

npx expo install expo-aliyun-push expo-build-properties

配置

所有配置均在 app.config.js 中完成，无需手动修改原生工程。请先安装 expo-build-properties（用于 Android Maven 仓库与 ProGuard 规则）。

proguard-rules.txt

# 阿里云推送
-keepclasseswithmembernames class ** {
    native <methods>;
}
-keepattributes Signature
-keep class sun.misc.Unsafe { *; }
-keep class com.taobao.** {*;}
-keep class com.alibaba.** {*;}
-keep class com.alipay.** {*;}
-keep class com.ut.** {*;}
-keep class com.ta.** {*;}
-keep class anet.**{*;}
-keep class anetwork.**{*;}
-keep class org.android.spdy.**{*;}
-keep class org.android.agoo.**{*;}
-keep class android.os.**{*;}
-keep class org.json.**{*;}
-dontwarn com.taobao.**
-dontwarn com.alibaba.**
-dontwarn com.alipay.**
-dontwarn anet.**
-dontwarn org.android.spdy.**
-dontwarn org.android.agoo.**
-dontwarn anetwork.**
-dontwarn com.ut.**
-dontwarn com.ta.**

# 小米通道
-keep class com.xiaomi.** {*;}
-dontwarn com.xiaomi.**

# 华为通道
-keep class com.huawei.** {*;}
-dontwarn com.huawei.**

# 荣耀通道
-ignorewarnings
-keepattributes *Annotation*
-keepattributes Exceptions
-keepattributes InnerClasses
-keepattributes Signature
-keepattributes SourceFile,LineNumberTable
-keep class com.hihonor.push.**{*;}

# vivo 通道
-keep class com.vivo.** {*;}
-dontwarn com.vivo.**

# OPPO 通道
-keep public class * extends android.app.Service

# GCM/FCM 通道
-keep class com.google.firebase.**{*;}
-dontwarn com.google.firebase.**

app.config.js

/** @type {import("expo/config").ExpoConfig} */
export default {
  expo: {
    name: "my-app",
    slug: "my-app",
    ios: {
      bundleIdentifier: "com.example.myapp",
      // 启用推送能力；生产环境改为 "production"
      entitlements: {
        "aps-environment": "development",
      },
    },
    android: {
      package: "com.example.myapp",
    },
    plugins: [
      [
        "expo-build-properties",
        {
          android: {
            extraProguardRules: /*把上面的proguard-rules.txt的内容放到这里*/,
            extraMavenRepos: [
              "https://maven.aliyun.com/nexus/content/repositories/releases/",
              "https://developer.huawei.com/repo/",
              "https://developer.hihonor.com/repo/",
            ],
          },
        },
      ],
      [
        "expo-aliyun-push",
        {
          // 必填：阿里云推送
          androidAliyunAppKey: "your-android-app-key",
          androidAliyunAppSecret: "your-android-app-secret",
          iosAliyunAppKey: "your-ios-app-key",
          iosAliyunAppSecret: "your-ios-app-secret",

          // 可选：厂商通道（不填则不启用对应通道）
          xiaomiAppId: "",
          xiaomiAppKey: "",
          huaweiAppId: "",
          honorAppId: "",
          vivoAppId: "",
          vivoAppKey: "",
          oppoAppKey: "",
          oppoAppSecret: "",
          meizuAppId: "",
          meizuAppKey: "",
          fcmSendId: "",
          fcmAppId: "",
          fcmProjectId: "",
          fcmApiKey: "",

          // 可选：自定义通知铃声（复制到 android/res/raw 与 ios 工程目录）
          notificationSoundSourcePaths: ["assets/music/ringtong.wav"],

          // 可选：第三方推送配置文件
          extraAndroidThirdPartyPushConfigFiles: {
            "assets/google-services.json": "/app",
            "assets/agconnect-services.json": "/app",
          },
          extraIOSThirdPartyPushConfigFiles: [
            "assets/GoogleService-Info.plist",
          ],
        },
      ],
    ],
  },
};

Config Plugin 配置项说明

配置项	必填	说明
`androidAliyunAppKey`	是	Android 阿里云 AppKey
`androidAliyunAppSecret`	是	Android 阿里云 AppSecret
`iosAliyunAppKey`	是	iOS 阿里云 AppKey
`iosAliyunAppSecret`	是	iOS 阿里云 AppSecret
`xiaomiAppId`	否	小米推送 AppId
`xiaomiAppKey`	否	小米推送 AppKey
`huaweiAppId`	否	华为推送 AppId
`honorAppId`	否	荣耀推送 AppId
`vivoAppId`	否	vivo 推送 AppId
`vivoAppKey`	否	vivo 推送 AppKey
`oppoAppKey`	否	OPPO 推送 AppKey
`oppoAppSecret`	否	OPPO 推送 AppSecret
`meizuAppId`	否	魅族推送 AppId
`meizuAppKey`	否	魅族推送 AppKey
`fcmSendId`	否	Firebase 推送 SendId
`fcmAppId`	否	Firebase 推送 AppId
`fcmProjectId`	否	Firebase 推送 ProjectId
`fcmApiKey`	否	Firebase 推送 ApiKey
`notificationSoundSourcePaths`	否	自定义铃声源文件路径列表，prebuild 时复制到原生工程
`extraAndroidThirdPartyPushConfigFiles`	否	Android 第三方配置文件映射，`key` 为源路径，`value` 为 `"/"` 或 `"/app"`
`extraIOSThirdPartyPushConfigFiles`	否	iOS 第三方配置文件路径列表

厂商通道字段留空或不填时，插件不会启用对应通道。包名须与阿里云控制台一致，否则初始化会失败。

Android 推送角标

华为、荣耀、vivo 厂商通道需在清单中声明角标权限，插件已自动配置。服务端下发规则见官方文档。本地修改角标可使用 setBadgeNumber。

使用

import ExpoAliyunPush from "expo-aliyun-push";
import { useEvent } from "expo";

初始化

`initAliyunPush()`

initAliyunPush(): Promise<void>

初始化阿里云推送 SDK。应在应用启动时调用，且只需调用一次。

返回值： 无。

`initThirdPush()`

initThirdPush(): Promise<void>

初始化第三方厂商推送通道。仅 Android 需要调用，在 initAliyunPush() 之后调用。

返回值： 无。

`getInitialNotification()`

getInitialNotification(): Promise<Record<string, any> | null>

获取初始通知信息。当用户通过点击通知打开应用时，可通过此方法获取该通知的详细信息。应在应用启动时调用一次。

返回值： 通知信息对象（包含 title、summary、ext 等字段），如果不是通过点击通知打开应用则返回 null。

`getDeviceId()`

getDeviceId(): Promise<string>

获取当前设备的推送 DeviceId，用于服务端定向推送。

返回值： 设备 ID 字符串。

日志

`setAliyunLogLevel(logLevel)`

setAliyunLogLevel(logLevel: AliyunPushLogLevel): Promise<string>

设置阿里云推送 SDK 日志级别。

参数	类型	说明
`logLevel`	`'off' \| 'error' \| 'info' \| 'debug'`	日志级别

返回值： 操作结果字符串。

Android 通知通道

`createAndroidNotificationChannel(channelInfo)`

createAndroidNotificationChannel(
  channelInfo: AndroidNotificationChannel,
): Promise<void>

创建 Android 8.0+ 通知通道。推送前需先创建通道，并在阿里云控制台配置相同的 channelId。

参数	类型	必填	说明
`channelInfo.id`	`string`	是	通道 ID，推送时使用
`channelInfo.name`	`string`	是	通道名称（用户可见）
`channelInfo.importance`	`'none' \| 'min' \| 'low' \| 'default' \| 'high' \| 'max'`	否	重要程度，默认 `default`
`channelInfo.description`	`string`	否	通道描述
`channelInfo.group`	`string`	否	通道分组 ID
`channelInfo.allowBubbles`	`boolean`	否	是否允许气泡通知
`channelInfo.enableLights`	`boolean`	否	是否启用指示灯
`channelInfo.lightColor`	`number`	否	指示灯颜色
`channelInfo.showBadges`	`boolean`	否	是否在启动器显示角标
`channelInfo.enableVibration`	`boolean`	否	是否振动
`channelInfo.vibrationPattern`	`number[]`	否	振动模式（毫秒）
`channelInfo.soundPath`	`string`	否	铃声：`res/raw` 资源名（如 `ringtong`）或本地绝对路径
`channelInfo.soundUsage`	`number`	否	`AudioAttributes` Usage，默认系统通知用法
`channelInfo.soundContentType`	`number`	否	`AudioAttributes` ContentType
`channelInfo.soundFlag`	`number`	否	`AudioAttributes` Flags

自定义铃声示例：

// app.config.js 中配置 notificationSoundSourcePaths: ["assets/music/ringtong.wav"]
await ExpoAliyunPush.createAndroidNotificationChannel({
  id: "my-channel",
  name: "My Channel",
  importance: "high",
  description: "带自定义铃声的通道",
  soundPath: "ringtong",
});

返回值： 无。

账号与手机号绑定

`bindAccount(account)`

bindAccount(account: string): Promise<string>

将当前设备绑定到指定账号，用于按账号推送。

参数	类型	说明
`account`	`string`	账号标识

返回值： 操作结果字符串。

`unbindAccount()`

unbindAccount(): Promise<string>

解绑当前设备的账号。

返回值： 操作结果字符串。

`bindPhoneNumber(phoneNumber)`

bindPhoneNumber(phoneNumber: string): Promise<string>

将当前设备绑定到手机号。

参数	类型	说明
`phoneNumber`	`string`	手机号

返回值： 操作结果字符串。

`unbindPhoneNumber()`

unbindPhoneNumber(): Promise<string>

解绑当前设备的手机号。

返回值： 操作结果字符串。

标签与别名

`bindTag(target, tags, alias)`

bindTag(
  target: AliyunTagTarget,
  tags: string[],
  alias: string | undefined | null,
): Promise<string>

为目标绑定标签。

参数	类型	说明
`target`	`'device' \| 'account' \| 'alias'`	绑定目标：本设备 / 本账号 / 别名
`tags`	`string[]`	标签列表
`alias`	`string \| undefined \| null`	当 `target` 为 `alias` 时传入别名

返回值： 操作结果字符串。

`unbindTag(target, tags, alias)`

unbindTag(
  target: AliyunTagTarget,
  tags: string[],
  alias: string | undefined | null,
): Promise<string>

为目标解绑标签。参数同 bindTag。

返回值： 操作结果字符串。

`listTags(target)`

listTags(target: AliyunTagTarget): Promise<string>

查询当前目标已绑定的标签。

参数	类型	说明
`target`	`'device' \| 'account' \| 'alias'`	查询目标

返回值： 标签列表 JSON 字符串。

`addAlias(alias)`

addAlias(alias: string): Promise<string>

为当前设备添加别名。

参数	类型	说明
`alias`	`string`	别名

返回值： 操作结果字符串。

`removeAlias(alias)`

removeAlias(alias: string): Promise<string>

移除当前设备的别名。

参数	类型	说明
`alias`	`string`	要移除的别名

返回值： 操作结果字符串。

`listAlias()`

listAlias(): Promise<string>

查询当前设备已绑定的别名列表。

返回值： 别名列表 JSON 字符串。

角标

`setBadgeNumber(number)`

setBadgeNumber(number: number): Promise<string>

设置应用角标数字。

参数	类型	说明
`number`	`number`	角标数量

返回值： 操作结果字符串。

iOS 前台通知

`setIOSForegroundNotificationOptions(options)`

setIOSForegroundNotificationOptions(
  options: IOSNotificationForegroundOptions[],
): Promise<void>

设置 iOS 应用在前台收到推送时的展示选项。仅 iOS 有效。

参数	类型	说明
`options`	`('sound' \| 'badge' \| 'alert' \| 'list' \| 'banner')[]`	前台通知展示项

返回值： 无。

通知权限

`getNotificationPermissionStatus()`

getNotificationPermissionStatus(): Promise<NotificationPermissionStatus>

获取当前通知权限状态。

返回值： 'granted' | 'denied' | 'undetermined'。

`jumpToNotificationSettings()`

jumpToNotificationSettings(): Promise<void>

跳转到系统通知设置页面。

返回值： 无。

事件

通过 useEvent 或 addListener 监听推送事件：

事件名	回调参数	说明
`onNotification`	`NotificationEventPayload`	收到通知
`onNotificationReceivedInApp`	`NotificationEventPayload`	应用内收到通知
`onNotificationOpened`	`NotificationEventPayload`	用户点击通知打开应用
`onMessage`	`MessageEventPayload`	收到透传消息
`onNotificationClickedWithNoAction`	`NotificationEventPayload`	点击无动作通知
`onNotificationRemoved`	`NotificationRemovedEventPayload`	通知被移除
`onLog`	`LogEventPayload`	阿里云 SDK 日志输出

NotificationEventPayload

字段	类型	说明
`title`	`string`	通知标题
`summary`	`string`	通知摘要
`ext`	`any`	扩展字段

MessageEventPayload

字段	类型	说明
`title`	`string`	消息标题
`content`	`string`	消息内容

NotificationRemovedEventPayload

字段	类型	说明
`messageId`	`string`	被移除通知的消息 ID

LogEventPayload

字段	类型	说明
`tag`	`string`	日志标签
`msg`	`string`	日志内容
`throwable`	`any`	异常信息（如有）
`flag`	`number`	日志标志位

import { useEvent } from "expo";

const onNotification = useEvent(ExpoAliyunPush, "onNotification");

const onLog = useEvent(ExpoAliyunPush, "onLog");

注意事项

本插件仅支持 Android 和 iOS。Web 平台可调用 API，但不会有实际效果。
阿里云推送账号中的包名须与应用 bundleIdentifier / package 一致，否则初始化失败。
iOS 生产包请将 aps-environment 设为 production。

Roadmap

iOS实时活动和灵动岛功能。

联系我

QQ 群：682911244

Name		Name	Last commit message	Last commit date
android		android
example		example
ios		ios
plugin		plugin
src		src
.eslintrc.js		.eslintrc.js
.gitignore		.gitignore
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
README.md		README.md
app.plugin.js		app.plugin.js
bun.lock		bun.lock
expo-module.config.json		expo-module.config.json
package.json		package.json
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation

expo-aliyun-push

安装

配置

Config Plugin 配置项说明

Android 推送角标

使用

初始化

initAliyunPush()

initThirdPush()

getInitialNotification()

getDeviceId()

日志

setAliyunLogLevel(logLevel)

Android 通知通道

createAndroidNotificationChannel(channelInfo)

账号与手机号绑定

bindAccount(account)

unbindAccount()

bindPhoneNumber(phoneNumber)

unbindPhoneNumber()

标签与别名

bindTag(target, tags, alias)

unbindTag(target, tags, alias)

listTags(target)

addAlias(alias)

removeAlias(alias)

listAlias()

角标

setBadgeNumber(number)

iOS 前台通知

setIOSForegroundNotificationOptions(options)

通知权限

getNotificationPermissionStatus()

jumpToNotificationSettings()

事件

注意事项

Roadmap

联系我

About

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

`initAliyunPush()`

`initThirdPush()`

`getInitialNotification()`

`getDeviceId()`

`setAliyunLogLevel(logLevel)`

`createAndroidNotificationChannel(channelInfo)`

`bindAccount(account)`

`unbindAccount()`

`bindPhoneNumber(phoneNumber)`

`unbindPhoneNumber()`

`bindTag(target, tags, alias)`

`unbindTag(target, tags, alias)`

`listTags(target)`

`addAlias(alias)`

`removeAlias(alias)`

`listAlias()`

`setBadgeNumber(number)`

`setIOSForegroundNotificationOptions(options)`

`getNotificationPermissionStatus()`

`jumpToNotificationSettings()`