跳至主要内容
版本: 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()。

变量​

此插件将使用以下项目变量（在您的应用程序的 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：推送通知将显示在原生对话框中 如果不需要任何选项，可以提供一个空数组。徽章仅适用于 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('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()​

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>

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

参数类型
deliveredDeliveredNotifications

自 1.0.0

removeAllDeliveredNotifications()​

removeAllDeliveredNotifications() => Promise<void>

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

自 1.0.0

createChannel(...)​

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

创建通知频道。

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

参数类型
channelChannel

自 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 上，您第一次使用该函数时，它将提示用户进行推送通知权限，并根据用户选择返回已授予或已拒绝。在随后的调用中，它将获取权限的当前状态，而无需再次提示。

**返回：** 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​

属性类型描述Default自
idstring通道标识符。1.0.0
namestring此通道对用户的友好名称（呈现给用户）。1.0.0
descriptionstring此通道的描述（呈现给用户）。1.0.0
soundstring应为发布到此通道的通知播放的声音。重要性至少为 3 的通知通道应该有声音。声音文件的文件名应相对于 android 应用 res/raw 目录指定。1.0.0
importanceImportance发布到此通道的通知的中断级别。31.0.0
visibilityVisibility发布到此通道的通知的可见性。此设置用于发布到此通道的通知是否出现在锁屏上，如果出现在锁屏上，是否以缩略形式显示。1.0.0
lightsboolean发布到此通道的通知是否应该在支持它的设备上显示通知灯。1.0.0
lightColorstring发布到此通道的通知的灯光颜色。仅在灯光在此通道上启用且设备支持的情况下才支持。支持的颜色格式为 #RRGGBB 和 #RRGGBBAA。1.0.0
vibrationboolean发布到此通道的通知是否应该振动。1.0.0

ListChannelsResult​

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

PermissionStatus​

属性类型描述自
receivePermissionState接收通知的权限状态。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
notificationPushNotificationSchema执行操作的通知。1.0.0

类型别名​

Importance​

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

1 | 2 | 3 | 4 | 5

Visibility​

通知可见性。有关更多详细信息，请参阅 Android 开发者文档

-1 | 0 | 1

PermissionState​

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

内容

编辑此页面