版本：v6

@capacitor/push-notifications

Push Notifications API 提供对原生推送通知的访问能力。

安装

npm install @capacitor/push-notifications@latest-6
npx cap sync

iOS

在 iOS 上，你必须启用推送通知功能。请参阅设置功能了解如何启用该功能。

启用推送通知功能后，请将以下代码添加到你的应用 AppDelegate.swift 文件中：

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)
}

Android

Push Notification API 使用 Firebase Cloud Messaging SDK 来处理通知。请参考在 Android 上设置 Firebase Cloud Messaging 客户端应用并按照说明创建 Firebase 项目并注册你的应用。你不需要将 Firebase SDK 添加到你的应用中，也不需要编辑应用清单文件——Push Notifications 插件会为你处理这些。唯一需要的就是将你的 Firebase 项目的 google-services.json 文件添加到应用的模块（应用级）目录中。

Android 13 要求进行权限检查才能接收推送通知。当目标 SDK 版本为 33 时，你需要相应地调用 checkPermissions() 和 requestPermissions() 方法。

从 Android 15 开始，用户可以在私密空间中安装应用。用户可以随时锁定他们的私密空间，这意味着在用户解锁之前，推送通知将不会显示。

无法检测应用是否安装在私密空间中。因此，如果你的应用显示任何关键通知，请告知用户避免在私密空间中安装该应用。

有关与应用私密空间相关的行为更改的更多信息，请参阅 Android 文档。

变量

此插件将使用以下项目变量（在你的应用 variables.gradle 文件中定义）：

firebaseMessagingVersion：com.google.firebase:firebase-messaging 的版本（默认值：23.3.1）

推送通知图标

在 Android 上，应将具有适当名称的推送通知图标添加到 AndroidManifest.xml 文件中：

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

如果未指定图标，Android 将使用应用图标，但推送图标应该是透明背景上的白色像素。由于应用图标通常不是这样设计的，因此会显示白色方块或圆圈。因此，建议为推送通知提供单独的图标。

Android Studio 有一个图标生成器，你可以用它来创建推送通知图标。

推送通知渠道

从 Android 8.0（API 级别 26）及更高版本开始，支持并推荐使用通知渠道。SDK 将按以下顺序为传入的推送通知派生 channelId：

首先，它将检查传入的通知是否设置了 channelId。 无论是通过 FCM 控制台发送推送通知，还是通过其 API 发送，都可以指定 channelId。
然后，它将检查 AndroidManifest.xml 中可能提供的给定值。 如果你希望创建并使用自己的默认渠道，请将 default_notification_channel_id 设置为你的通知渠道对象的 ID，如下所示；当传入的消息未明确设置通知渠道时，FCM 将使用此值。

<meta-data
    android:name="com.google.firebase.messaging.default_notification_channel_id"
    android:value="@string/default_notification_channel_id" />

最后，它将使用 Firebase SDK 为我们提供的备用 channelId。 FCM 开箱即用地提供了一个具有基本设置的默认通知渠道。Firebase SDK 将在收到第一条推送消息时创建此渠道。

警告使用选项 1 或 2 时，你仍然需要在代码中创建一个通知渠道，其 ID 与所选选项中使用的 ID 匹配。你可以为此使用 createChannel(...)。如果不这样做，SDK 将回退到选项 3。

应用在前台时的推送通知外观

你可以配置应用在前台时推送通知的显示方式。

属性	类型	描述	自
`presentationOptions`	`PresentationOption[]`	这是一个可以组合的字符串数组。数组中的可能值有： - `badge`：更新应用图标上的徽章计数（默认值） - `sound`：收到推送通知时设备会响铃/振动 - `alert`：推送通知以原生对话框形式显示如果不需要任何选项，可以提供空数组。badge 仅适用于 iOS。	1.0.0

示例

在 capacitor.config.json 中：

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

在 capacitor.config.ts 中：

/// <reference types="@capacitor/push-notifications" />

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    PushNotifications: {
      presentationOptions: ["badge", "sound", "alert"],
    },
  },
};

export default config;

静默推送通知 / 纯数据通知

iOS

本插件不支持 iOS 静默推送（Remote Notifications）。我们建议使用原生代码方案来处理这类通知，详见向应用推送后台更新

Android

本插件支持纯数据通知，但如果应用已被终止，将不会调用 pushNotificationReceived。要处理这种情况，你需要创建一个继承 FirebaseMessagingService 的服务，详见处理 FCM 消息

常见问题

在 Android 上，有多种系统和应用状态可能影响推送通知的送达：

如果设备已进入 Doze 模式，你的应用功能可能受限。要提高通知接收成功率，可考虑使用 FCM 高优先级消息
开发环境和生产环境存在行为差异。建议在 Android Studio 之外的环境测试应用。详见此处

示例

import { PushNotifications } from '@capacitor/push-notifications';

const addListeners = async () => {
  await PushNotifications.addListener('registration', token => {
    console.info('注册令牌：', token.value);
  });

  await PushNotifications.addListener('registrationError', err => {
    console.error('注册错误：', err.error);
  });

  await PushNotifications.addListener('pushNotificationReceived', notification => {
    console.log('收到推送通知：', notification);
  });

  await PushNotifications.addListener('pushNotificationActionPerformed', notification => {
    console.log('推送通知操作已执行', notification.actionId, notification.inputValue);
  });
}

const registerNotifications = async () => {
  let permStatus = await PushNotifications.checkPermissions();

  if (permStatus.receive === 'prompt') {
    permStatus = await PushNotifications.requestPermissions();
  }

  if (permStatus.receive !== 'granted') {
    throw new Error('用户拒绝了权限！');
  }

  await PushNotifications.register();
}

const getDeliveredNotifications = async () => {
  const notificationList = await PushNotifications.getDeliveredNotifications();
  console.log('已送达的通知', notificationList);
}

API

register()
unregister()
getDeliveredNotifications()
removeDeliveredNotifications(...)
removeAllDeliveredNotifications()
createChannel(...)
deleteChannel(...)
listChannels()
checkPermissions()
requestPermissions()
addListener('registration', ...)
addListener('registrationError', ...)
addListener('pushNotificationReceived', ...)
addListener('pushNotificationActionPerformed', ...)
removeAllListeners()
接口
类型别名

register()

register() => Promise<void>

注册应用以接收推送通知。

此方法将触发 'registration' 事件并返回推送令牌，若出现问题则触发 'registrationError'。它不会向用户请求通知权限，请先使用 requestPermissions()。

自： 1.0.0

unregister()

unregister() => Promise<void>

取消应用的推送通知注册。

在 Android 上会删除 Firebase 令牌，在 iOS 上会取消 APNS 注册。

自： 5.0.0

getDeliveredNotifications()

getDeliveredNotifications() => Promise<DeliveredNotifications>

获取通知屏幕上可见的通知列表。

返回：

Promise<DeliveredNotifications>

自： 1.0.0

removeDeliveredNotifications(...)

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

从通知屏幕移除指定通知。

参数	类型
`delivered`	`DeliveredNotifications`

自： 1.0.0

removeAllDeliveredNotifications()

removeAllDeliveredNotifications() => Promise<void>

从通知屏幕移除所有通知。

自： 1.0.0

createChannel(...)

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

创建通知渠道。

仅适用于 Android O 或更高版本（SDK 26+）。

参数	类型
`channel`	`Channel`

自： 1.0.0

deleteChannel(...)

deleteChannel(args: { id: string; }) => Promise<void>

删除通知渠道。

仅适用于 Android O 或更高版本（SDK 26+）。

参数	类型
`args`	`{ id: string; }`

自： 1.0.0

listChannels()

listChannels() => Promise<ListChannelsResult>

列出可用的通知渠道。

仅适用于 Android O 或更高版本（SDK 26+）。

返回：

Promise<ListChannelsResult>

自： 1.0.0

checkPermissions()

checkPermissions() => Promise<PermissionStatus>

检查接收推送通知的权限。

在 Android 12 及以下版本中，状态始终为 granted，因为始终可以接收推送通知。如需检查用户是否允许显示通知，请使用 local-notifications 插件。

返回：

Promise<PermissionStatus>

自： 1.0.0

requestPermissions()

requestPermissions() => Promise<PermissionStatus>

请求接收推送通知的权限。

在 Android 12 及以下版本中，该函数不会提示权限请求，因为这些版本始终可以接收推送通知。

在 iOS 上，首次调用此函数时，会向用户请求推送通知权限，并根据用户的选择返回 granted（已授权）或 denied（已拒绝）。后续调用将直接获取当前权限状态，而不会再次提示用户。

返回值：

Promise<PermissionStatus>

自版本： 1.0.0

addListener('registration', ...)

addListener(eventName: 'registration', listenerFunc: (token: Token) => void) => Promise<PluginListenerHandle>

当推送通知注册顺利完成时触发。

提供推送通知令牌 (token)。

参数	类型
`eventName`	`'registration'`
`listenerFunc`	`(token: Token) => void`

返回值：

Promise<PluginListenerHandle>

自版本： 1.0.0

addListener('registrationError', ...)

addListener(eventName: 'registrationError', listenerFunc: (error: RegistrationError) => void) => Promise<PluginListenerHandle>

当推送通知注册过程出现问题时触发。

提供注册相关的错误信息。

参数	类型
`eventName`	`'registrationError'`
`listenerFunc`	`(error: RegistrationError) => void`

返回值：

Promise<PluginListenerHandle>

自版本： 1.0.0

addListener('pushNotificationReceived', ...)

addListener(eventName: 'pushNotificationReceived', listenerFunc: (notification: PushNotificationSchema) => void) => Promise<PluginListenerHandle>

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

参数	类型
`eventName`	`'pushNotificationReceived'`
`listenerFunc`	`(notification: PushNotificationSchema) => void`

返回值：

Promise<PluginListenerHandle>

自版本： 1.0.0

addListener('pushNotificationActionPerformed', ...)

addListener(eventName: 'pushNotificationActionPerformed', listenerFunc: (notification: ActionPerformed) => void) => Promise<PluginListenerHandle>

当对推送通知执行了操作时触发。

参数	类型
`eventName`	`'pushNotificationActionPerformed'`
`listenerFunc`	`(notification: ActionPerformed) => void`

返回值：

Promise<PluginListenerHandle>

自版本： 1.0.0

removeAllListeners()

removeAllListeners() => Promise<void>

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

自版本： 1.0.0

接口

DeliveredNotifications

属性	类型	描述	自版本
`notifications`	`PushNotificationSchema[]`	通知屏幕上可见的通知列表。	1.0.0

PushNotificationSchema

属性	类型	描述	自版本
`title`	`string`	通知标题。	1.0.0
`subtitle`	`string`	通知副标题。	1.0.0
`body`	`string`	通知的主要文本内容。	1.0.0
`id`	`string`	通知标识符。	1.0.0
`tag`	`string`	通知标签。仅 Android 可用（来自推送通知）。	4.0.0
`badge`	`number`	在应用图标角标上显示的数字。	1.0.0
`notification`	`any`	该字段不返回。	1.0.0
`data`	`any`	推送通知负载中包含的任何附加数据。	1.0.0
`click_action`	`string`	用户点击通知时要执行的操作。仅 Android 可用。	1.0.0
`link`	`string`	通知中的深度链接。仅 Android 可用。	1.0.0
`group`	`string`	设置用于通知分组的群组标识符。仅 Android 可用。在 iOS 上的功能类似于 `threadIdentifier`。	1.0.0
`groupSummary`	`boolean`	将此通知指定为关联 `group` 的摘要。仅 Android 可用。	1.0.0

Channel

属性	类型	说明	默认值	始于
`id`	`string`	频道标识符。		1.0.0
`name`	`string`	频道的用户友好名称（展示给用户）。		1.0.0
`description`	`string`	频道的描述信息（展示给用户）。		1.0.0
`sound`	`string`	发送到此频道的通知应播放的声音。重要性级别至少为 `3` 的通知频道应设置声音。声音文件名应相对于 Android 应用的 `res/raw` 目录指定。		1.0.0
`importance`	`Importance`	发送到此频道的通知的打断级别。	`3`	1.0.0
`visibility`	`Visibility`	发送到此频道的通知的可见性。此设置决定通知是否显示在锁屏界面上，以及显示时是否以脱敏形式呈现。		1.0.0
`lights`	`boolean`	发送到此频道的通知是否应在支持该功能的设备上显示通知灯。		1.0.0
`lightColor`	`string`	发送到此频道的通知的指示灯颜色。仅当该频道启用了指示灯且设备支持时才生效。支持的颜色格式为 `#RRGGBB` 和 `#RRGGBBAA`。		1.0.0
`vibration`	`boolean`	发送到此频道的通知是否应触发振动。		1.0.0

ListChannelsResult

属性	类型	说明	始于
`channels`	`Channel[]`	由你的应用创建的所有频道的列表。	1.0.0

PermissionStatus

属性	类型	说明	始于
`receive`	`PermissionState`	接收通知的权限状态。	1.0.0

PluginListenerHandle

属性	类型
`remove`	`() => Promise<void>`

Token

属性	类型	说明	始于
`value`	`string`	在 iOS 上包含 APNS 令牌，在 Android 上包含 FCM 令牌。	1.0.0

RegistrationError

属性	类型	说明	始于
`error`	`string`	描述注册失败原因的错误信息。	4.0.0

ActionPerformed

属性	类型	说明	始于
`actionId`	`string`	在通知上执行的操作 ID。	1.0.0
`inputValue`	`string`	在通知操作中输入的值。仅 iOS 可用。	1.0.0
`notification`	`PushNotificationSchema`	执行操作的通知对象。	1.0.0

类型别名

Importance

重要性级别。更多详情请参阅 Android 开发者文档

1 | 2 | 3 | 4 | 5

Visibility

通知可见性。更多详情请参阅 Android 开发者文档

-1 | 0 | 1

PermissionState

'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'

安装​

iOS​

Android​

变量​

推送通知图标​

推送通知渠道​

应用在前台时的推送通知外观​

示例​

静默推送通知 / 纯数据通知​

iOS​

Android​

常见问题​

示例​

API​

register()​

unregister()​

getDeliveredNotifications()​

removeDeliveredNotifications(...)​

removeAllDeliveredNotifications()​

createChannel(...)​

deleteChannel(...)​

listChannels()​

checkPermissions()​

requestPermissions()​

addListener('registration', ...)​

addListener('registrationError', ...)​

addListener('pushNotificationReceived', ...)​

addListener('pushNotificationActionPerformed', ...)​

removeAllListeners()​

接口​

DeliveredNotifications​

PushNotificationSchema​

Channel​

ListChannelsResult​

PermissionStatus​

PluginListenerHandle​

Token​

RegistrationError​

ActionPerformed​

类型别名​

Importance​

Visibility​

PermissionState​

Contents

安装

iOS

Android

变量

推送通知图标

推送通知渠道

应用在前台时的推送通知外观

示例

静默推送通知 / 纯数据通知

iOS

Android

常见问题

示例

API

register()

unregister()

getDeliveredNotifications()

removeDeliveredNotifications(...)

removeAllDeliveredNotifications()

createChannel(...)

deleteChannel(...)

listChannels()

checkPermissions()

requestPermissions()

addListener('registration', ...)

addListener('registrationError', ...)

addListener('pushNotificationReceived', ...)

addListener('pushNotificationActionPerformed', ...)

removeAllListeners()

接口

DeliveredNotifications

PushNotificationSchema

Channel

ListChannelsResult

PermissionStatus

PluginListenerHandle

Token

RegistrationError

ActionPerformed

类型别名

Importance

Visibility

PermissionState