capacitor-push-notifications

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Capacitor Push Notifications

Capacitor 推送通知

Set up and use push notifications in Capacitor apps using Firebase Cloud Messaging (FCM) via the

@capacitor-firebase/messaging

plugin.

通过

@capacitor-firebase/messaging

插件，在Capacitor应用中配置并使用Firebase Cloud Messaging（FCM）推送通知。

Prerequisites

前提条件

Capacitor 6, 7, or 8 app.
Node.js and npm installed.
A Firebase project. Create one at Firebase console if needed.
For iOS: A paid Apple Developer Program membership and Xcode installed.
For Android: Android Studio installed.

@capacitor/push-notifications

must not be installed — it conflicts with

@capacitor-firebase/messaging

Capacitor 6、7或8 应用。
已安装Node.js和npm。
一个Firebase项目。如果没有，可以在Firebase控制台创建。
针对iOS：需拥有付费的Apple Developer Program会员资格，并已安装Xcode。
针对Android：已安装Android Studio。

不得安装

@capacitor/push-notifications

——它会与

@capacitor-firebase/messaging

冲突。

Agent Behavior

操作指引原则

Guide step-by-step. Walk the user through the process one step at a time. Never present multiple unrelated questions at once.
Auto-detect before asking. Check the project for platforms (
```
android/
```
,
```
ios/
```
), build tools, framework, and
```
package.json
```
dependencies. Only ask the user when something cannot be detected.
One decision at a time. When a step requires user input, ask that single question, wait for the answer, then continue.
Present clear options. Provide concrete choices (e.g., "Do you want to configure topic subscriptions? (yes/no)") instead of open-ended questions.

分步引导：逐步引导用户完成流程。切勿同时提出多个不相关的问题。
先自动检测再询问：检查项目中的平台目录（
```
android/
```
、
```
ios/
```
）、构建工具、框架以及
```
package.json
```
中的依赖项。只有当无法自动检测到信息时，才向用户询问。
一次一个决策：当步骤需要用户输入时，只提出单个问题，等待用户回答后再继续。
提供明确选项：给出具体的选择（例如："是否要配置主题订阅？(是/否)"），而非开放式问题。

Procedures

操作步骤

Step 1: Analyze the Project

步骤1：分析项目

Auto-detect the following by reading project files — do not ask the user for information that can be inferred:

Platforms: Check which directories exist (
```
android/
```
,
```
ios/
```
). These are the platforms to configure.

Build tool / framework: Check for

vite.config.ts

angular.json

webpack.config.js

next.config.js

, etc.

Capacitor version: Read
```
@capacitor/core
```
version from
```
package.json
```
.
Conflicting plugins: Check if
```
@capacitor/push-notifications
```
is in
```
package.json
```
. If found, warn the user it must be removed before proceeding:
bash
```
npm uninstall @capacitor/push-notifications
```

通过读取项目文件自动检测以下信息——不要向用户询问可通过推断获取的信息：

平台：检查是否存在
```
android/
```
、
```
ios/
```
目录，这些是需要配置的平台。
构建工具/框架：检查是否存在
```
vite.config.ts
```
、
```
angular.json
```
、
```
webpack.config.js
```
、
```
next.config.js
```
等文件。
Capacitor版本：从
```
package.json
```
中读取
```
@capacitor/core
```
的版本。
冲突插件：检查
```
package.json
```
中是否存在
```
@capacitor/push-notifications
```
。如果发现，需警告用户必须先卸载该插件才能继续：
bash
```
npm uninstall @capacitor/push-notifications
```

Step 2: Set Up Firebase

步骤2：配置Firebase

Check if Firebase is already configured in the project:

Android: Check if
```
android/app/google-services.json
```
exists.
iOS: Check if
```
ios/App/App/GoogleService-Info.plist
```
exists.

If Firebase is not configured for a detected platform, read

references/firebase-setup.md

and guide the user through the Firebase setup for each missing platform.

检查项目中是否已配置Firebase：

Android：检查
```
android/app/google-services.json
```
是否存在。
iOS：检查
```
ios/App/App/GoogleService-Info.plist
```
是否存在。

如果某个已检测到的平台未配置Firebase，请阅读

references/firebase-setup.md

并引导用户完成该平台的Firebase配置。

Step 3: Install the Plugin

步骤3：安装插件

bash

npm install @capacitor-firebase/messaging firebase
npx cap sync

bash

npm install @capacitor-firebase/messaging firebase
npx cap sync

Step 4: Configure Android

步骤4：配置Android

Skip if

android/

does not exist.

Read

references/android-setup.md

and apply the Android-specific configuration.

如果

android/

目录不存在则跳过。

阅读

references/android-setup.md

并完成Android专属配置。

Step 5: Configure iOS

步骤5：配置iOS

Skip if

ios/

does not exist.

Read

references/ios-setup.md

and apply the iOS-specific configuration. This includes APNs key/certificate setup,

AppDelegate.swift

modifications, and enabling capabilities.

如果

ios/

目录不存在则跳过。

阅读

references/ios-setup.md

并完成iOS专属配置，包括APNs密钥/证书配置、修改

AppDelegate.swift

以及启用相关功能权限。

Step 6: Configure Web (if applicable)

步骤6：配置Web（如适用）

If the project targets the web (detected via build tool config or user confirmation):

Read

references/web-setup.md

and apply the Web-specific configuration.

如果项目目标平台包含Web（通过构建工具配置或用户确认检测到）：

阅读

references/web-setup.md

并完成Web专属配置。

Step 7: Configure Capacitor Plugin Options

步骤7：配置Capacitor插件选项

Ask the user if they want to customize iOS foreground notification presentation. If yes, update

capacitor.config.json

capacitor.config.ts

json

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

Available options:

badge

sound

alert

criticalAlert

. Default is

["alert", "badge", "sound"]

询问用户是否要自定义iOS前台通知展示方式。如果是，更新

capacitor.config.json

或

capacitor.config.ts

：

json

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

可用选项：

badge

、

sound

、

alert

、

criticalAlert

。默认值为

["alert", "badge", "sound"]

。

Step 8: Add Push Notification Code

步骤8：添加推送通知代码

Read

references/implementation.md

and add the push notification code to the project. Adapt imports and structure to match the user's framework.

The implementation covers:

Requesting permissions
Retrieving the FCM token
Listening for incoming notifications
Handling notification taps

阅读

references/implementation.md

并将推送通知代码添加到项目中。根据用户的框架调整导入语句和代码结构。

实现内容包括：

申请权限
获取FCM令牌
监听传入通知
处理通知点击事件

Step 9: Configure Optional Features

步骤9：配置可选功能

Ask the user which optional features to enable:

Topic subscriptions — Subscribe/unsubscribe to FCM topics (Android/iOS only).
Notification channels — Create custom Android notification channels (Android SDK 26+ only).
Token refresh listener — Listen for FCM token changes.

For each selected feature, read

references/implementation.md

and apply the relevant code.

询问用户要启用哪些可选功能：

主题订阅——订阅/取消订阅FCM主题（仅支持Android/iOS）。
通知渠道——创建自定义Android通知渠道（仅支持Android SDK 26+）。
令牌刷新监听器——监听FCM令牌变化。

对于每个选中的功能，阅读

references/implementation.md

并添加相关代码。

Step 10: Sync and Test

步骤10：同步并测试

Sync the project:
bash
```
npx cap sync
```
Read
```
references/testing.md
```
and guide the user through sending a test notification via the Firebase Console.

同步项目：
bash
```
npx cap sync
```
阅读
```
references/testing.md
```
并引导用户通过Firebase控制台发送测试通知。

Error Handling

错误处理

@capacitor/push-notifications
conflict: The

@capacitor-firebase/messaging

plugin cannot coexist with

@capacitor/push-notifications

. Uninstall the conflicting plugin:

npm uninstall @capacitor/push-notifications && npx cap sync

iOS: No push notifications received: Verify APNs key/certificate is uploaded to Firebase Console. Verify Push Notifications and Background Modes capabilities are enabled. Verify
```
AppDelegate.swift
```
contains the required delegate methods.
iOS:
didRegisterForRemoteNotificationsWithDeviceToken
not called: Ensure the Push Notifications capability is added in Xcode under Signing & Capabilities. Check that the app's bundle ID matches the one registered in Firebase and Apple Developer portal.
Android: No push notifications received: Verify
```
google-services.json
```
is at
```
android/app/google-services.json
```
. Verify the Google services Gradle plugin is applied.
Android: White square notification icon: The notification icon must be white pixels on a transparent background. Application icons with color will render as a white square. Add a dedicated push notification icon.
Web:
getToken()
fails: Ensure the VAPID key is correct. Ensure
```
firebase-messaging-sw.js
```
exists at the root of the domain. Check that the browser supports the Push API.
FCM token is
null
: Ensure
```
requestPermissions()
```
was called and returned
```
granted
```
before calling
```
getToken()
```
. On iOS, verify the device is not a simulator (simulators cannot receive push notifications).
checkPermissions()
returns
denied
: The user has permanently denied notification permissions. Guide them to re-enable via device settings (Settings > App > Notifications).
Android 13+: No permission prompt: On Android 13 (API 33) and above,
```
requestPermissions()
```
must be called explicitly. Earlier Android versions grant notification permission by default.

@capacitor/push-notifications
冲突：

@capacitor-firebase/messaging

插件无法与

@capacitor/push-notifications

共存。请卸载冲突插件：

npm uninstall @capacitor/push-notifications && npx cap sync

。

iOS：未收到推送通知：验证APNs密钥/证书是否已上传至Firebase控制台。验证是否已启用“推送通知”和“后台模式”权限。验证
```
AppDelegate.swift
```
是否包含所需的代理方法。
iOS：
didRegisterForRemoteNotificationsWithDeviceToken
未被调用：确保在Xcode的“签名与功能”中已添加“推送通知”功能。检查应用的Bundle ID是否与Firebase和Apple开发者门户中注册的一致。
Android：未收到推送通知：验证
```
google-services.json
```
是否位于
```
android/app/google-services.json
```
路径下。验证是否已应用Google services Gradle插件。
Android：通知图标显示为白色方块：通知图标必须是透明背景上的白色像素。带颜色的应用图标会显示为白色方块。请添加专用的推送通知图标。
Web：
getToken()
调用失败：确保VAPID密钥正确。确保
```
firebase-messaging-sw.js
```
位于域名根目录。检查浏览器是否支持Push API。
FCM令牌为
null
：确保在调用
```
getToken()
```
之前已调用
```
requestPermissions()
```
且返回
```
granted
```
。在iOS上，验证设备不是模拟器（模拟器无法接收推送通知）。
checkPermissions()
返回
denied
：用户已永久拒绝通知权限。引导用户通过设备设置重新启用（设置 > 应用 > 通知）。
Android 13+：未弹出权限提示：在Android 13（API 33）及以上版本中，必须显式调用
```
requestPermissions()
```
。早期Android版本默认授予通知权限。