跳到主要内容
版本：v6

@capacitor/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​

推送通知 API 使用 Firebase Cloud Messaging SDK 来处理通知。请参阅在 Android 上设置 Firebase Cloud Messaging 客户端应用并按照说明创建 Firebase 项目并注册您的应用程序。无需将 Firebase SDK 添加到您的应用或编辑应用清单 - 推送通知插件已为您提供。唯一需要的是将您 Firebase 项目的 google-services.json 文件添加到应用的模块（应用级）目录中。

Android 13 需要权限检查才能接收推送通知。当目标 SDK 为 33 时，您需要相应地调用 checkPermissions() 和 requestPermissions()。

From Android 15 onwards, users can install an app in the Private space. Users can lock their private space at any time, which means that push notifications are not shown until the user unlocks it.

It is not possible to detect if an app is installed in the private space. Therefore, if your app shows any critical notifications, inform your users to avoid installing the app in the private space.

For more information about the behavior changes of your app related to the private space, refer to Android documentation.

变量​

此插件将使用以下项目变量（在应用的 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：

  1. 首先检查传入的通知是否设置了 channelId。 从 FCM 仪表板或通过其 API 发送推送通知时，可以指定 channelId。
  2. 然后检查 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" />
  1. 最后它将使用 Firebase SDK 为我们提供的回退 channelId。 FCM 提供了一个具有基本设置的默认通知渠道。此渠道将在收到第一条推送消息时由 Firebase SDK 创建。

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

前台推送通知的外观​

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

属性类型描述始于
presentationOptionsPresentationOption[]这是一个可以组合的字符串数组。数组中的可能值为： - 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 上，有各种系统和应用状态会影响推送通知的传递：

  • 如果设备已进入低电耗模式，您的应用可能会受到功能限制。为了增加通知被接收的机会，请考虑使用 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()​

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

返回值： 

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>

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

提供推送通知令牌。

参数类型
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​

属性类型描述始于
notificationsPushNotificationSchema[]通知屏幕上可见的通知列表。1.0.0

PushNotificationSchema​

属性类型描述始于
titlestring通知标题。1.0.0
subtitlestring通知副标题。1.0.0
bodystring通知的主要文本负载。1.0.0
idstring通知标识符。1.0.0
tagstring通知标签。仅适用于 Android（来自推送通知）。4.0.0
badgenumber显示应用图标徽章的数字。1.0.0
notificationany它不会被返回。1.0.0
dataany推送通知负载中包含的任何附加数据。1.0.0
click_actionstring用户打开通知时要执行的操作。仅适用于 Android。1.0.0
linkstring通知中的深层链接。仅适用于 Android。1.0.0
groupstring设置通知分组的组标识符。仅适用于 Android。功能类似于 iOS 上的 threadIdentifier。1.0.0
groupSummaryboolean将此通知指定为关联 group 的摘要。仅适用于 Android。1.0.0

Channel​

属性类型描述默认始于
idstring渠道标识符。1.0.0
namestring此渠道的用户友好名称（呈现给用户）。1.0.0
descriptionstring此渠道的描述（呈现给用户）。1.0.0
soundstring应为此渠道发布的通知播放的声音。重要性至少为 3 的通知渠道应具有声音。声音文件的文件名应相对于 Android 应用 res/raw 目录指定。1.0.0
importance
Importance
发布到此渠道的通知的中断级别。
3
1.0.0
visibility
Visibility
发布到此渠道的通知的可见性。此设置用于确定发布到此渠道的通知是否出现在锁屏上，以及是否以编辑形式出现。1.0.0
lightsboolean发布到此渠道的通知是否应显示通知灯（在支持的设备上）。1.0.0
lightColorstring发布到此渠道的通知的灯光颜色。仅当在此渠道上启用了灯光且设备支持时才受支持。支持的颜色格式为 #RRGGBB 和 #RRGGBBAA。1.0.0
vibrationboolean发布到此渠道的通知是否应振动。1.0.0

ListChannelsResult​

属性类型描述始于
channelsChannel[]您的应用创建的所有渠道的列表。1.0.0

PermissionStatus​

属性类型描述始于
receive
PermissionState
接收通知的权限状态。1.0.0

PluginListenerHandle​

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

Token​

属性类型描述始于
valuestring在 iOS 上包含 APNS 令牌。在 Android 上包含 FCM 令牌。1.0.0

RegistrationError​

属性类型描述始于
errorstring描述注册失败的错误消息。4.0.0

ActionPerformed​

属性类型描述始于
actionIdstring在通知上执行的操作。1.0.0
inputValuestring在通知操作上输入的文本。仅适用于 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'

Contents

编辑此页