版本：v8

@capacitor/push-notifications

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

安装

npm install @capacitor/push-notifications
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

推送通知 API 使用 Firebase Cloud Messaging SDK 来处理通知。请参阅在 Android 上设置 Firebase Cloud Messaging 客户端应用并按照说明创建 Firebase 项目和注册应用。

不需要添加 Firebase SDK 到你的应用或编辑应用清单 - 推送通知会为你提供。只需要将 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 匹配的 ID 在代码中创建通知渠道。你可以使用 createChannel(...) 执行此操作。如果不这样做,SDK 将回退到选项 3。

前台推送通知外观

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

Prop	Type	Description	Since
`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 静默推送(远程通知)。我们建议使用原生代码解决方案来处理这些类型的通知,请参阅向应用推送后台更新。

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()
Interfaces
Type Aliases

register()

register() => Promise<void>

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

此方法将使用推送令牌触发 'registration' 事件,如果出现问题则触发 'registrationError'。它不会提示用户授予权限,请先使用 requestPermissions()。

Since: 1.0.0

unregister()

unregister() => Promise<void>

从推送通知中取消注册应用。

这将在 Android 上删除 firebase 令牌,在 iOS 上取消注册 APNS。

Since: 5.0.0

getDeliveredNotifications()

getDeliveredNotifications() => Promise<DeliveredNotifications>

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

Returns:

Promise<DeliveredNotifications>

Since: 1.0.0

removeDeliveredNotifications(...)

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

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

Param	Type
`delivered`	`DeliveredNotifications`

Since: 1.0.0

removeAllDeliveredNotifications()

removeAllDeliveredNotifications() => Promise<void>

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

Since: 1.0.0

createChannel(...)

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

创建通知渠道。

仅适用于 Android O 或更高版本(SDK 26+)。

Param	Type
`channel`	`Channel`

Since: 1.0.0

deleteChannel(...)

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

删除通知渠道。

仅适用于 Android O 或更高版本(SDK 26+)。

Param	Type
`args`	`{ id: string; }`

Since: 1.0.0

listChannels()

listChannels() => Promise<ListChannelsResult>

列出现有的通知渠道。

仅适用于 Android O 或更高版本(SDK 26+)。

Returns:

Promise<ListChannelsResult>

Since: 1.0.0

checkPermissions()

checkPermissions() => Promise<PermissionStatus>

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

在 Android 12 及以下版本,状态始终为已授予,因为你始终可以接收推送通知。如果你需要检查用户是否允许显示通知,请使用本地通知插件。

Returns:

Promise<PermissionStatus>

Since: 1.0.0

requestPermissions()

requestPermissions() => Promise<PermissionStatus>

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

在 Android 12 及以下版本,它不会提示授予权限,因为你始终可以接收推送通知。

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

Returns:

Promise<PermissionStatus>

Since: 1.0.0

addListener('registration', ...)

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

在推送通知注册无问题时完成时调用。

提供推送通知令牌。

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

Returns:

Promise<PluginListenerHandle>

Since: 1.0.0

addListener('registrationError', ...)

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

在推送通知注册有问题时完成时调用。

提供注册问题的错误。

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

Returns:

Promise<PluginListenerHandle>

Since: 1.0.0

addListener('pushNotificationReceived', ...)

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

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

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

Returns:

Promise<PluginListenerHandle>

Since: 1.0.0

addListener('pushNotificationActionPerformed', ...)

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

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

Param	Type
`eventName`	`'pushNotificationActionPerformed'`
`listenerFunc`	`(notification: ActionPerformed) => void`

Returns:

Promise<PluginListenerHandle>

Since: 1.0.0

removeAllListeners()

removeAllListeners() => Promise<void>

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

Since: 1.0.0

Interfaces

DeliveredNotifications

Prop	Type	Description	Since
`notifications`	`PushNotificationSchema[]`	通知屏幕上可见的通知列表。	1.0.0

PushNotificationSchema

Prop	Type	Description	Since
`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

Prop	Type	Description	Default	Since
`id`	`string`	渠道标识符。		1.0.0
`name`	`string`	此渠道的友好名称(呈现给用户)。		1.0.0
`description`	`string`	此渠道的描述(呈现给用户)。		1.0.0
`sound`	`string`	应为发布到此渠道的通知播放的声音。重要性至少为 `3` 的通知渠道应该有声音。应指定声音文件的文件名,相对于 android app `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

Prop	Type	Description	Since
`channels`	`Channel[]`	你的应用创建的所有渠道的列表。	1.0.0

PermissionStatus

Prop	Type	Description	Since
`receive`	`PermissionState`	接收通知的权限状态。	1.0.0

PluginListenerHandle

Prop	Type
`remove`	`() => Promise<void>`

Token

Prop	Type	Description	Since
`value`	`string`	在 iOS 上,它包含 APNS 令牌。在 Android 上,它包含 FCM 令牌。	1.0.0

RegistrationError

Prop	Type	Description	Since
`error`	`string`	描述注册失败的错误消息。	4.0.0

ActionPerformed

Prop	Type	Description	Since
`actionId`	`string`	对通知执行的操作。	1.0.0
`inputValue`	`string`	在通知操作上输入的文本。仅适用于 iOS。	1.0.0
`notification`	`PushNotificationSchema`	执行操作的通知。	1.0.0

Type Aliases

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()​

Interfaces​

DeliveredNotifications​

PushNotificationSchema​

Channel​

ListChannelsResult​

PermissionStatus​

PluginListenerHandle​

Token​

RegistrationError​

ActionPerformed​

Type Aliases​

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

Interfaces

DeliveredNotifications

PushNotificationSchema

Channel

ListChannelsResult

PermissionStatus

PluginListenerHandle

Token

RegistrationError

ActionPerformed

Type Aliases

Importance

Visibility

PermissionState