在 Ionic + Angular 应用中使用 Firebase 推送通知

Web 框架: Angular 支持平台: iOS, Android

应用开发者为用户提供的最常见功能之一就是推送通知。在本教程中，我们将逐步介绍在 iOS 和 Android 上实现 Firebase 云消息推送 所需的所有步骤。

为了注册和监听来自 Firebase 的推送通知，我们将在 Ionic + Angular 应用中使用 Capacitor 推送通知 API。

环境依赖

使用 Capacitor 构建和部署 iOS 与 Android 应用需要进行一些环境配置。请先 按照此处的说明安装必要的 Capacitor 依赖项，然后再继续。

要在 iOS 上测试推送通知，Apple 要求您拥有 付费的 Apple 开发者账户 和一台 物理 iOS 设备。

如果遇到问题或控制台提示包版本过时或已弃用，请确保您使用的是最新稳定版本的 Node、Android Studio 和 Xcode。

此外，我们使用 Firebase 实现推送通知，因此如果您使用了其他依赖 Firebase SDK 的 Cordova 插件，请确保它们已更新至最新版本。

准备 Ionic Capacitor 应用

如果您已有现成的 Ionic 应用，请跳过此部分。如果没有，我们先来创建一个 Ionic 应用。

在您常用的终端中，安装最新版本的 Ionic CLI：

npm install -g @ionic/cli

接下来，使用 CLI 基于 空白 模板创建一个新的 Ionic Angular 应用，命名为 capApp：

ionic start capApp blank --type=angular

当提示是否将新应用与 Capacitor 集成时，输入 y 并按回车。这会将 Capacitor 和 Capacitor CLI 添加到我们的新应用中。

应用创建成功后，切换到新创建的项目目录：

cd capApp/

最后运行 npx cap init，填写应用信息：

npx cap init
? App name: CapApp
? App Package ID: com.mydomain.myappname

构建应用并添加平台

在向项目添加任何原生平台之前，必须至少构建应用一次。Web 构建会创建 Capacitor 所需的 Web 资源目录（Ionic Angular 项目中的 www 文件夹）。

ionic build

接下来，为我们的应用添加 iOS 和 Android 平台。

npx cap add ios
npx cap add android

运行这些命令后，会在项目根目录下创建 android 和 ios 文件夹。这些是完全独立的原生项目产物，应视为 Ionic 应用的一部分（建议提交到版本控制）。

使用 Capacitor 推送通知 API

首先，我们需要安装 Capacitor 推送通知插件：

npm install @capacitor/push-notifications
npx cap sync

然后，在接入 Firebase 之前，我们需要确保应用能够通过 Capacitor 推送通知 API 注册推送通知。我们还会添加 alert（您也可以使用 console.log 语句代替）来显示设备上应用打开时接收到的通知负载内容。

在您的应用中，打开 home.page.ts 文件，添加 import 语句和 const 来使用 Capacitor 推送 API：

import {
  ActionPerformed,
  PushNotificationSchema,
  PushNotifications,
  Token,
} from '@capacitor/push-notifications';

接着，添加 ngOnInit() 方法，其中包含一些用于注册和监听推送通知的 API 方法。我们还会在几个事件中添加 alert() 来监控运行状态：

export class HomePage implements OnInit {

ngOnInit() {
    console.log('初始化 HomePage');

    // 请求推送通知权限
    // iOS 会提示用户并返回是否授予权限
    // Android 会直接授予权限而不提示
    PushNotifications.requestPermissions().then(result => {
      if (result.receive === 'granted') {
        // 向 Apple / Google 注册以通过 APNS/FCM 接收推送
        PushNotifications.register();
      } else {
        // 显示错误信息
      }
    });

    // 注册成功后，我们应该能够接收通知
    PushNotifications.addListener('registration',
      (token: Token) => {
        alert('推送注册成功，令牌: ' + token.value);
      }
    );

    // 设置存在问题，推送将无法工作
    PushNotifications.addListener('registrationError',
      (error: any) => {
        alert('注册错误: ' + JSON.stringify(error));
      }
    );

    // 如果应用在设备上处于打开状态，则显示通知负载内容
    PushNotifications.addListener('pushNotificationReceived',
      (notification: PushNotificationSchema) => {
        alert('收到推送: ' + JSON.stringify(notification));
      }
    );

    // 点击通知时调用的方法
    PushNotifications.addListener('pushNotificationActionPerformed',
      (notification: ActionPerformed) => {
        alert('推送操作执行: ' + JSON.stringify(notification));
      }
    );
}

以下是 home.page.ts 的完整实现代码：

import { Component, OnInit } from '@angular/core';

import {
  ActionPerformed,
  PushNotificationSchema,
  PushNotifications,
  Token,
} from '@capacitor/push-notifications';

@Component({
  selector: 'app-home',
  templateUrl: 'home.page.html',
  styleUrls: ['home.page.scss'],
})
export class HomePage implements OnInit {
  ngOnInit() {
    console.log('初始化 HomePage');

    // 请求推送通知权限
    // iOS 会提示用户并返回是否授予权限
    // Android 会直接授予权限而不提示
    PushNotifications.requestPermissions().then(result => {
      if (result.receive === 'granted') {
        // 向 Apple / Google 注册以通过 APNS/FCM 接收推送
        PushNotifications.register();
      } else {
        // 显示错误信息
      }
    });

    PushNotifications.addListener('registration', (token: Token) => {
      alert('推送注册成功，令牌: ' + token.value);
    });

    PushNotifications.addListener('registrationError', (error: any) => {
      alert('注册错误: ' + JSON.stringify(error));
    });

    PushNotifications.addListener(
      'pushNotificationReceived',
      (notification: PushNotificationSchema) => {
        alert('收到推送: ' + JSON.stringify(notification));
      },
    );

    PushNotifications.addListener(
      'pushNotificationActionPerformed',
      (notification: ActionPerformed) => {
        alert('推送操作执行: ' + JSON.stringify(notification));
      },
    );
  }
}

完成这些后，您需要生成新的构建并让 Capacitor 知晓更改。可以通过以下命令实现：

ionic build
npx cap copy
```## 在 Firebase 上为应用创建项目

在将 Firebase Cloud Messaging 连接到你的应用并发送推送通知之前，你需要在 Firebase 上创建一个项目。

前往 [Firebase 控制台](https://console.firebase.google.com/)，点击 **添加项目** 按钮。

为项目命名，接受 Firebase 服务条款，然后点击 **创建项目** 继续。系统会自动为你生成一个项目 ID。

## Android

### 将 Firebase 与 Android 应用集成

本节内容大致遵循 [使用 Firebase 控制台设置 Firebase 的官方文档](https://firebase.google.com/docs/android/setup?authuser=0)。下面会提供与 Capacitor 相关的具体说明。

进入你的 Firebase 项目的项目概览页面，在顶部点击 **Android** 图标以添加一个新的 Android 应用。

![在 Firebase 控制台中添加新的 Android 应用](../../../../static/img/v4/docs/guides/firebase-push-notifications/add-android-app.png)

接下来会要求你提供一些关于应用的信息。

- 你的 **Android 包名** 应与 `capacitor.config.json` 文件中的 **appId** 匹配
- 我们在这个 Capacitor 应用 ID 中使用了 `com.mydomain.myappname`，所以这里我们也用这个。
- 昵称和调试签名证书是可选的

然后点击 **注册应用** 按钮。

### 下载并使用 `google-services.json` 文件

接下来的提示会要求你下载 `google-services.json` 文件。这个文件包含了你的 Capacitor 应用从 Android 连接 Firebase 所需的信息。

将 `google-services.json` 文件下载到本地计算机。然后将该文件移动到你的 Capacitor Android 项目目录中，具体位置是 `android/app/` 目录下。

![Android 的 Google Services JSON 文件位置](../../../../static/img/v4/docs/guides/firebase-push-notifications/google-services-location-android.png)

我们不需要向项目中 _添加_ 任何依赖项，因为 Capacitor 项目在其 `build.gradle` 文件中已经自动包含了一个 `firebase-messaging` 的版本。

## iOS

### 前提条件

iOS 推送通知的设置比 Android 要复杂得多。你必须拥有一个 [付费的 Apple 开发者账户](https://developer.apple.com/)，_并且_ 在能够测试 iOS 应用的推送通知之前，需要完成以下事项：

1. 在 Apple 开发者门户中为你的 iOS 应用 [设置正确的开发或生产证书及预配描述文件](https://help.apple.com/xcode/mac/current/#/dev60b6fbbc7)
2. 在 Apple 开发者门户中为开发或生产环境 [创建 APNS 证书或密钥](https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/establishing_a_certificate-based_connection_to_apns)
3. 在 Xcode 中确保你的应用 [已启用推送通知功能](https://help.apple.com/xcode/mac/current/#/dev88ff319e7)
4. 根据 [环境设置](/main/getting-started/environment-setup.md) 文档中的指南，准备好一台物理 iOS 设备

### 将 Firebase 与我们的原生 iOS 应用集成

这部分与上面的 Android 部分非常相似，但有一些关键区别。

首先，进入你的 Firebase 项目的 **项目概览** 页面。如果你一直按照本指南操作，你会在页面顶部看到一个已列出的 Android 应用。

要向你的 Firebase 项目添加 iOS 应用，请点击 **添加应用** 按钮并选择 **iOS** 平台。

接下来会要求你提供一些关于应用的信息。

- 你的 **iOS 包标识符** 应与 `capacitor.config.json` 文件中的 **appId** 匹配
- 我们在这个 Capacitor 应用 ID 中使用了 `com.mydomain.myappname`，所以这里我们也用这个。
- 应用昵称和应用商店 ID 是可选的

然后点击 **注册应用** 按钮。

### 将 `GoogleService-Info.plist` 文件添加到你的 iOS 应用

_注意：这 **不是** 你 Android 应用使用的那个文件。_

下载提供的 `GoogleService-Info.plist` 文件到本地计算机。

然后你需要打开 Xcode...

```bash
npx cap open ios

... 并按照 Firebase 的指示将 .plist 文件移动到你的 Xcode 项目中，确保将其添加到所有目标。

通过 CocoaPods 添加 Firebase SDK

iOS 上的推送通知 API 使用了 CocoaPods（一个 iOS 依赖管理系统），我们需要告诉 CocoaPods 使用 Firebase。

为此，我们需要修改 Podfile，该文件可以在 Xcode 的 Pods 目录下找到：

我们需要将 Firebase 添加到为我们的 App 目标提供的 CocoaPods 中。为此，在你的 target 'App' 部分添加 pod Firebase/Messaging，像这样：

target 'App' do
  capacitor_pods
  # 在此处添加你的 Pods
  pod 'Firebase/Messaging' # 添加这一行
end

你的 Podfile 看起来应该像这样：

require_relative '../../node_modules/@capacitor/ios/scripts/pods_helpers'

platform :ios, '13.0'
use_frameworks!

# 避免 Xcode 缓存 Pods 的解决方法，该问题要求
# 在安装新的 Cordova 插件后执行 Product -> Clean Build Folder
# 需要 CocoaPods 1.6 或更新版本
install! 'cocoapods', :disable_input_output_paths => true

def capacitor_pods
  pod 'Capacitor', :path => '../../node_modules/@capacitor/ios'
  pod 'CapacitorCordova', :path => '../../node_modules/@capacitor/ios'
end

target 'App' do
  capacitor_pods
  # 在此处添加你的 Pods
  pod 'Firebase/Messaging'
end

post_install do |installer|
  assertDeploymentTarget(installer)
end

更新项目

现在我们需要确保我们的 iOS 项目已更新并安装了正确的 Firebase CocoaPod。

注意：这部分可能需要一些时间，因为 CocoaPods 需要下载所有相关的文件/依赖项。

npx cap update ios
```### 添加初始化代码

要在 iOS 应用启动时连接到 Firebase，需要在 `AppDelegate.swift` 文件中添加以下内容。

首先，在文件顶部添加 `import` 语句：

```swift
import Firebase

……然后在 AppDelegate.swift 文件的 application(didFinishLaunchingWithOptions) 方法中，为 Firebase 添加配置方法到初始化代码：

FirebaseApp.configure()

接着，需要添加以下两个方法来正确处理推送注册事件：

func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
  Messaging.messaging().apnsToken = deviceToken
  Messaging.messaging().token(completion: { (token, error) in
    if let error = error {
        NotificationCenter.default.post(name: .capacitorDidFailToRegisterForRemoteNotifications, object: error)
    } else if let token = token {
        NotificationCenter.default.post(name: .capacitorDidRegisterForRemoteNotifications, object: token)
    }
  })
}

func application(_ application: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: Error) {
  NotificationCenter.default.post(name: .capacitorDidFailToRegisterForRemoteNotifications, object: error)
}

完成后的 AppDelegate.swift 文件应大致如下所示：

import UIKit
import Capacitor
import Firebase

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {

  var window: UIWindow?


  func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    // Override point for customization after application launch.
    FirebaseApp.configure()
    return true
  }

  func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
    Messaging.messaging().apnsToken = deviceToken
    Messaging.messaging().token(completion: { (token, error) in
      if let error = error {
          NotificationCenter.default.post(name: .capacitorDidFailToRegisterForRemoteNotifications, object: error)
      } else if let token = token {
          NotificationCenter.default.post(name: .capacitorDidRegisterForRemoteNotifications, object: token)
      }
    })
  }

  func application(_ application: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: Error) {
    NotificationCenter.default.post(name: .capacitorDidFailToRegisterForRemoteNotifications, object: error)
  }

将 APNS 证书或密钥上传到 Firebase

如果从一开始就遵循了指南，你应该已经在 Apple 开发者门户创建了 Apple APNS 证书或 APNS 认证密钥。在 Firebase 能够与 APNS 通信并向应用发送推送通知之前，你需要将其中一项上传到 Firebase。

要上传证书或认证密钥，请从 项目概览 页面：

1. 点击你的 iOS 应用程序，然后点击 Settings 齿轮图标。
2. 在设置页面，点击 Cloud Messaging 标签页。
3. 在 iOS 应用配置 标题下，使用提供的 Upload 按钮上传你的认证密钥或证书。

发送测试通知

现在来到最有趣的部分——验证来自 Firebase 的推送通知在 Android 和 iOS 上是否正常工作！

我们需要在 Android 或 iOS 上启动应用，以便 home.page.ts 页面能够注册并接收通知。

要在 Android Studio 中打开你的 Android 项目：

npx cap open android

要在 Xcode 中打开你的 iOS 项目：

npx cap open ios

项目打开后，使用 Android Studio 或 Xcode 的 Run 功能将应用侧载到你的设备上。应用应在首页启动。

注意：在 iOS 上，你会看到一个弹窗，要求你允许应用接收通知——请务必选择 允许通知！

如果你的应用成功注册，并且你遵循了上面的代码，你应该会看到一个带有成功消息的提示！

现在我们来测试设备是否收到通知。要发送通知，请在 Firebase 中进入项目面板 Grow 标题下的 Cloud Messaging 部分。

接下来，选择 New Notification 按钮。

创建通知时，你只需指定以下信息：

1. 通知的文本内容
2. 标题（仅限 Android，iOS 可选）
3. 目标（可以是用户群组或主题；建议直接定位 iOS 或 Android 应用本身，见下图）

4. 调度时间（保持为 "Now"）

此时，你可以 Review 你创建的通知，然后选择 Publish 来发送通知。

如果你的应用设置正确，你会在主屏幕上看到一条弹窗，显示你在 Firebase 中编写的推送通知。然后你可以点击通知，并根据我们上面的代码，收到 pushActionPerformed 事件的 alert。