版本：v8

@capacitor/push-notifications

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

安装

npm install @capacitor/push-notifications
npx cap sync

iOS 平台

在 iOS 上，您必须启用 Push Notifications 功能。请参阅设置功能了解如何启用该功能。

启用 Push Notifications 功能后，将以下内容添加到您的应用的 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 的版本（默认值：25.0.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 匹配的通知频道。您可以使用 createChannel(...) 来实现。如果不这样做，SDK 将回退到选项 3。

前台时的推送通知外观

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

属性	类型	描述	自版本
`presentationOptions`	`PresentationOption[]`	这是您可以组合的字符串数组。数组中可能的值有：- `badge`：更新应用图标上的徽章计数（默认值）- `sound`：收到推送通知时设备将响铃/振动 - `alert`：在 iOS 上已弃用。请使用 `banner` 和 `list`。在 Android 上，此值仍用于显示通知。- `banner`：推送通知显示为横幅。在 Android 上，默认为与 `alert` 相同的行为。- `list`：推送通知显示在通知中心。在 Android 上，默认为与 `alert` 相同的行为。如果不需要任何选项，可以提供空数组。badge 仅适用于 iOS。	1.0.0

示例

在 capacitor.config.json 中：

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

在 capacitor.config.ts 中：

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

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

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

export default config;

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

iOS

此插件不支持 iOS 静默推送（远程通知）。我们建议使用原生代码解决方案处理这些类型的通知，请参阅向您的应用推送后台更新。

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('Registration token: ', token.value);
  });

  await PushNotifications.addListener('registrationError', err => {
    console.error('Registration error: ', err.error);
  });

  await PushNotifications.addListener('pushNotificationReceived', notification => {
    console.log('Push notification received: ', notification);
  });

  await PushNotifications.addListener('pushNotificationActionPerformed', notification => {
    console.log('Push notification action performed', 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('User denied permissions!');
  }

  await PushNotifications.register();
}

const getDeliveredNotifications = async () => {
  const notificationList = await PushNotifications.getDeliveredNotifications();
  console.log('delivered notifications', notificationList);
}

API 参考

register()
unregister()
getDeliveredNotifications()
removeDeliveredNotifications(...)
removeAllDeliveredNotifications()
createChannel(...)
deleteChannel(...)
listChannels()
checkPermissions()
requestPermissions()
addListener('registration', ...)
addListener('registrationError', ...)
addListener('pushNotificationReceived', ...)
addListener('pushNotificationActionPerformed', ...)
removeAllListeners()
Interfaces
Type Aliases

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>

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

Param	Type
`delivered`	`DeliveredNotifications`

自版本： 1.0.0

removeAllDeliveredNotifications()

removeAllDeliveredNotifications() => Promise<void>

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

自版本： 1.0.0

createChannel(...)

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

创建通知频道。

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

Param	Type
`channel`	`Channel`

自版本： 1.0.0

deleteChannel(...)

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

删除通知频道。

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

Param	Type
`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 及以下，状态始终为已授权，因为您可以始终接收推送通知。如果需要检查用户是否允许显示通知，请使用 local-notifications 插件。

返回： Promise<PermissionStatus>

自版本： 1.0.0

requestPermissions()

requestPermissions() => Promise<PermissionStatus>

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

在 Android 12 及以下，不会提示权限，因为您可以始终接收推送通知。

在 iOS 上，第一次使用此函数时，它将提示用户授予推送通知权限，并根据用户选择返回已授权或已拒绝。在后续调用中，它将获取权限的当前状态，而不会再次提示。

返回： Promise<PermissionStatus>

自版本： 1.0.0

addListener('registration', ...)

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

当推送通知注册成功完成时调用。

提供推送通知令牌。

Param	Type
`eventName`	`'registration'`
`listenerFunc`	`(token: Token) => void`

返回： Promise<PluginListenerHandle>

自版本： 1.0.0

addListener('registrationError', ...)

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

当推送通知注册出现问题完成时调用。

提供包含注册问题的错误。

Param	Type
`eventName`	`'registrationError'`
`listenerFunc`	`(error: RegistrationError) => void`

返回： Promise<PluginListenerHandle>

自版本： 1.0.0

addListener('pushNotificationReceived', ...)

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

当设备收到推送通知时调用。

Param	Type
`eventName`	`'pushNotificationReceived'`
`listenerFunc`	`(notification: PushNotificationSchema) => void`

返回： Promise<PluginListenerHandle>

自版本： 1.0.0

addListener('pushNotificationActionPerformed', ...)

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

当对推送通知执行操作时调用。

Param	Type
`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`	对通知执行的操作。	1.0.0
`inputValue`	`string`	在通知操作上输入的文本。仅适用于 iOS。	1.0.0
`notification`	`PushNotificationSchema`	执行操作所在的通知。	1.0.0

类型别名

Importance

重要性级别。有关更多详细信息，请参阅 Android 开发者文档。

0 | 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​

目录

安装

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