推送通知

推送通知 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>

注册应用以接收推送通知。 将触发带有推送令牌的注册事件， 或在出现问题时触发 registrationError。 不会提示用户获取通知权限，请先使用 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 或更新版本（SDK 26+）上创建通知渠道。

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

---

deleteChannel(...)

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

在 Android O 或更新版本（SDK 26+）上删除通知渠道。

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

---

listChannels()

listChannels() => Promise<NotificationChannelList>

在 Android O 或更新版本（SDK 26+）上列出可用的通知渠道。

返回值：

Promise<NotificationChannelList>

---

addListener(...)

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

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

参数	类型	描述
eventName	"registration"	registration。
listenerFunc	(token: PushNotificationToken) => void	带有推送令牌的回调函数。

返回值：

PluginListenerHandle

---

addListener(...)

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

当推送通知注册遇到问题时触发的事件。 提供注册问题的错误信息。

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

返回值：

PluginListenerHandle

---

addListener(...)

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

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

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

返回值：

PluginListenerHandle

---

addListener(...)

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

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

参数	类型	描述
eventName	"pushNotificationActionPerformed"	pushNotificationActionPerformed。
listenerFunc	(notification: PushNotificationActionPerformed) => void	带有通知操作的回调函数。

返回值：

PluginListenerHandle

---

removeAllListeners()

removeAllListeners() => void

移除此插件所有的原生监听器。

---

接口

NotificationPermissionResponse

属性	类型
granted	boolean

PushNotificationDeliveredList

属性	类型
notifications	PushNotification[]

PushNotification

属性	类型	描述
title	string
subtitle	string
body	string
id	string
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