推送通知

推送通知 API 提供了设备注册、接收服务器通知以及处理响应的方法。与 本地通知 API 不同，后者主要用于离线场景下的本地通知调度和处理。

启用推送通知功能

在 iOS 平台上，您需要先在项目中启用推送通知功能才能使插件正常工作。进入应用项目的 Capabilities 部分，将 Push Notifications 从 OFF 切换到 ON 状态。

此操作会为应用添加推送功能并在项目中创建授权文件。

对于 Android 平台，只需从 Firebase 控制台下载项目的 google-services.json 文件，并放置到 项目名/android/app 目录下即可。

推送通知图标

在 Android 平台上，需要在 AndroidManifest.xml 文件中配置带有正确名称的推送通知图标：

<meta-data android:name="com.google.firebase.messaging.default_notification_icon" android:resource="@mipmap/push_icon_name" />

若未指定图标，Android 会使用应用图标。但推送图标要求是透明背景上的白色像素图案，而应用图标通常不符合此要求，会导致显示为白色方块或圆形。因此建议为推送通知单独提供图标。

您可以使用 Android Studio 的图标生成工具来创建推送通知图标。

禁用推送通知插件

如果项目中未使用推送通知功能，在提交应用到 iTunes Connect 时，Apple 会发送邮件提示存在 缺少推送通知授权 的问题。这是因为 Capacitor 内置了推送通知注册和获取令牌的代码。

Apple 发送此邮件只是为了确认您没有错误地忘记启用推送功能，如果确实不使用推送通知插件，可以安全忽略该提示。

若希望避免接收此类邮件，可以通过移除项目 Build Settings 中 Active Compilation Conditions 下的 USE_PUSH 来禁用推送通知插件。

前台推送通知显示方式

在 iOS 平台上，您可以通过在 capacitor.config.json 中配置 presentationOptions 数组来定义应用处于前台时推送通知的显示方式。

可选值包括：

• badge：更新应用图标上的角标计数（默认值）
• sound：收到推送时设备会播放铃声/震动
• alert：以原生对话框形式显示推送通知

如果不需要任何上述效果，可以传入空数组。此时仍会触发 pushNotificationReceived 事件并携带推送信息。

"plugins": {
  "PushNotifications": {
    "presentationOptions": ["badge", "sound", "alert"]
  }
}

• register()
• requestPermission()
• getDeliveredNotifications()
• removeDeliveredNotifications(...)
• removeAllDeliveredNotifications()
• createChannel(...)
• deleteChannel(...)
• listChannels()
• addListener(...)
• addListener(...)
• addListener(...)
• addListener(...)
• removeAllListeners()
• 接口

示例教程

在 Ionic Angular 应用中使用 Firebase 推送通知

API

register()

register() => Promise<void>

注册应用以接收推送通知。 将触发携带推送令牌的注册事件， 或在出现问题时触发注册错误事件。 不会请求用户通知权限，需先使用 requestPermission()。

---

requestPermission()

requestPermission() => Promise<NotificationPermissionResponse>

在 iOS 上会提示用户允许显示通知 并返回权限授予状态。 Android 无此类提示，默认返回已授权。

返回值:

Promise<NotificationPermissionResponse>

---

getDeliveredNotifications()

getDeliveredNotifications() => Promise<PushNotificationDeliveredList>

获取通知中心当前可见的所有通知。

返回值:

Promise<PushNotificationDeliveredList>

---

removeDeliveredNotifications(...)

removeDeliveredNotifications(delivered: PushNotificationDeliveredList) => Promise<void>

从通知中心移除指定的通知。

参数	类型	描述
delivered	PushNotificationDeliveredList	待移除的通知列表。

---

removeAllDeliveredNotifications()

removeAllDeliveredNotifications() => Promise<void>

清除通知中心所有已送达的通知。

---

createChannel(...)

createChannel(channel: NotificationChannel) => Promise<void>

在 Android O 及以上版本(API 26+)创建通知渠道。

参数	类型	描述
channel	NotificationChannel	要创建的渠道

---

deleteChannel(...)

deleteChannel(channel: NotificationChannel) => Promise<void>

在 Android O 及以上版本(API 26+)删除通知渠道。

参数	类型	描述
channel	NotificationChannel	要删除的渠道

---

listChannels()

listChannels() => Promise<NotificationChannelList>

在 Android O 及以上版本(API 26+)列出所有可用通知渠道。

返回值:

Promise<NotificationChannelList>

---

addListener(...)

addListener(eventName: 'registration', listenerFunc: (token: PushNotificationToken) => void) => PluginListenerHandle

当推送通知注册成功时触发的事件。 提供推送通知令牌。

参数	类型	描述
eventName	"registration"	注册事件
listenerFunc	(token: PushNotificationToken) => void	携带推送令牌的回调函数

返回值:

PluginListenerHandle

---

addListener(...)

addListener(eventName: 'registrationError', listenerFunc: (error: any) => void) => PluginListenerHandle

当推送通知注册失败时触发的事件。 提供注册错误信息。

参数	类型	描述
eventName	"registrationError"	注册错误事件
listenerFunc	(error: any) => void	携带注册错误的回调函数

返回值:

PluginListenerHandle

---

addListener(...)

addListener(eventName: 'pushNotificationReceived', listenerFunc: (notification: PushNotification) => void) => PluginListenerHandle

当设备收到推送通知时触发的事件。

参数	类型	描述
eventName	"pushNotificationReceived"	推送通知接收事件
listenerFunc	(notification: PushNotification) => void	携带接收到的通知的回调函数

返回值:

PluginListenerHandle

---

addListener(...)

addListener(eventName: 'pushNotificationActionPerformed', listenerFunc: (notification: PushNotificationActionPerformed) => void) => PluginListenerHandle

当用户对推送通知执行操作时触发的事件。

参数	类型	描述
eventName	"pushNotificationActionPerformed"	推送通知操作执行事件
listenerFunc	(notification: PushNotificationActionPerformed) => void	携带通知操作信息的回调函数

返回值:

PluginListenerHandle

---

removeAllListeners()

removeAllListeners() => void

移除本插件所有原生事件监听器。

---

Interfaces

NotificationPermissionResponse

属性	类型
granted	boolean

PushNotificationDeliveredList

属性	类型
notifications	PushNotification[]

PushNotification

属性	类型	描述
title	string	通知标题
subtitle	string	通知副标题
body	string	通知正文
id	string	通知ID
badge	number	角标数
notification	any	原生通知对象
data	any	附加数据
click_action	string	点击动作
link	string	链接地址
group	string	仅Android：设置通知分组标识符，类似iOS的threadIdentifier
groupSummary	boolean	仅Android：将本通知设为分组摘要（需与group属性配合使用）

NotificationChannel

属性	类型
id	string
name	string
description	string
sound	string
importance	1 | 2 | 5 | 4 | 3
visibility	0 | 1 | -1
lights	boolean
lightColor	string
vibration	boolean

NotificationChannelList

属性	类型
channels	NotificationChannel[]

PluginListenerHandle

属性	类型
remove	() => void

PushNotificationToken

属性	类型
value	string

PushNotificationActionPerformed

属性	类型
actionId	string
inputValue	string
notification	PushNotification