向 iOS 应用添加推送通知

1. 简介

上次更新日期：2020 年 1 月 6 日

Firebase Cloud Messaging (FCM) 是一种跨平台消息传递解决方案，可供您免费可靠地发送消息。

使用 FCM，您可以通知客户端应用有新的电子邮件或其他数据有待同步。您可以发送通知消息以再次吸引用户并留住他们。对于即时通讯等用例，一条消息可将最大 4KB 的有效负载传送至客户端应用。

运作方式

FCM 实现包括用于发送和接收的两个主要组件：

1. 一个可信环境，例如 Cloud Functions for Firebase 或用于构建、定位和发送消息的应用服务器。
2. 通过针对特定平台的相应传输服务接收消息的 iOS、Android 或网页 (JavaScript) 客户端应用。

FCM 架构概览

FCM 依赖于下面一组组件来构建、传输和接收消息：

1. 用于编写或构建消息请求的工具。通知编辑器提供基于 GUI 的用于创建通知请求的选项。如需实现对所有消息类型的完全自动化和支持，您必须在支持 Firebase Admin SDK 或 FCM 服务器协议的可信服务器环境中构建消息请求。此环境可以是 Cloud Functions for Firebase、Google App Engine 或您自己的应用服务器。
2. FCM 后端（以及其他函数）接受消息请求，通过主题对消息执行扇出，并生成消息 ID 等消息元数据。
3. 平台级传输层，用于将消息路由到目标设备、处理消息传送，并在适当的情况下应用针对具体平台的配置。该传输层包括：

• 适用于带有 Google Play 服务的 Android 设备的 Android 传输层 (ATL)
• 适用于 iOS 设备的 Apple 推送通知服务 (APNs)
• 适用于 Web 应用的 Web 推送协议

注意：平台级传输层在 FCM 服务之外。路由到平台级传输层的 FCM 消息可能受特定于该平台的条款（而非 FCM 的服务条款）的约束。通过 ATL 的 Android 消息路由受 Google API 服务条款的约束。

4. 用户设备上的 FCM SDK，系统会根据应用的前台/后台状态和任何相关的应用逻辑显示通知或处理消息。

构建内容

在此 Codelab 中，您将通过 FCM 向示例 iOS 应用添加推送通知。

学习内容

• 如何为用户订阅或退订推送消息
• 如何处理传入的推送消息
• 如何显示通知
• 如何响应通知点击

所需条件

• Xcode 11.0 或更高版本
• CocoaPods 1.9.0 或更高版本
• Apple 开发者账号
• 一台用于运行您的应用的 iOS 实体设备
• 具备 Swift 的基础知识

2. 准备工作

下载示例代码

在此 Codelab 中，您将构建自己的测试应用，但如果您想查看并运行现有的示例应用，可以下载快速入门示例代码。

获取示例的方法有两种：

• 克隆 Git 代码库：

$ git clone https://github.com/firebase/quickstart-ios.git

• 下载 ZIP 文件：

如果您将源代码下载为 ZIP 文件，解压后会获得一个根文件夹 quickstart-ios。

下载源代码

创建新应用

按照以下步骤创建您自己的测试应用（以下步骤在 XCode 12.3 中进行了）：

1. 打开 XCode，然后选择创建新的 Xcode 项目。
2. 选择应用，然后点击下一步。

3. 输入 Product Name（产品名称，例如MessagingExample)
4. 选择团队（如果您尚未创建团队，请在 Apple Developer 账号中配置）。
5. 输入组织标识符（例如com.your-name)
6. 输入软件包标识符（例如com.your-name.MessagingExample，它在所有 iOS 应用中应该是唯一的）。
7. 从界面下拉菜单中选择故事板。
8. 在生命周期下拉菜单中选择 UIKit App Delegate。
9. 在语言中选择 Swift。
10. 点击下一步。

创建 APN 密钥并将应用注册到 Firebase 项目时，您需要用到软件包标识符。

3. 配置 APN

创建身份验证密钥

本部分介绍如何为启用推送通知的应用 ID 生成身份验证密钥。如果您已有密钥，则可以使用该密钥，而无需生成新的密钥。

如需创建身份验证密钥，请执行以下操作：

1. 在您的开发者账号中，前往 Certificates, Identifiers & &配置文件，然后导航到密钥。

2. 点击右上角的“添加”按钮 (+)。

3. 输入 APNs 身份验证密钥的说明
4. 在“密钥服务”下，选中“APNs”复选框，然后点击继续。

5. 点击注册，然后点击下载。将密钥保存在安全的地方。此下载是一次性的，此后将无法检索该密钥。

创建应用 ID

应用 ID 是对应用进行唯一标识的标识符。一般由倒序域表示。

1. 前往 Apple 开发者会员中心并登录。
2. 转到 Certificates, Identifiers and Profiles。
3. 前往标识符。
4. 点击 + 按钮以创建新的应用 ID。
5. 选择应用 ID 单选按钮，然后点击继续。

6. 选择应用，然后点击继续。

7. 如需创建新的应用 ID，请执行以下操作：
8. 输入应用 ID 的名称。
9. 输入 Team ID。此值必须与“Membership”标签中的 Team ID 匹配。
10. 在 App ID Suffix（应用 ID 后缀）部分中，选择 显式 App ID（显式应用 ID），然后输入您的 Bundle ID（软件包 ID）。
11. 在 App Services（应用服务）部分，确保已选中 Push Notifications（推送通知）。
12. 点击 Continue，并检查您输入的内容是否正确：
13. Identifier 的值应与 Team ID 和 Bundle ID 的合并值相一致
14. Push Notifications 应设为 Configurable
15. 点击 Register，创建应用 ID。

创建配置文件

要在开发时测试您的应用，您需要一个用于开发的配置文件，授权您的设备运行尚未在 App Store 发布的应用。

1. 前往 Apple 开发者会员中心并登录。
2. 转到 Certificates, Identifiers and Profiles。
3. 在左上角的下拉菜单中，如果未选择 iOS、tvOS、watchOS，请进行选择，然后前往个人资料。
4. 点击 + 按钮创建新个人资料。
5. 选择 iOS 应用开发作为配置文件类型，然后点击继续。

6. 在下拉菜单中，选择要使用的应用 ID，然后点击继续。
7. 选择您在上一步中选择的应用 ID 的 iOS 开发证书，然后点击 Continue。
8. 选择您想添加到配置文件中的 iOS 设备，然后点击 Continue（继续）。请务必选择要用于测试的所有设备。
9. 为此配置文件输入名称（例如 MessagingExampleProfile），然后点击生成。

10. 点击 Download，将配置文件保存至您的 Mac。

11. 双击配置文件进行安装。

4. 将 Firebase 添加到您的 iOS 项目

创建 Firebase 项目

您需要先创建一个要关联到您的 iOS 应用的 Firebase 项目，然后才能将 Firebase 添加到您的 iOS 应用。访问了解 Firebase 项目以详细了解 Firebase 项目。

1. 在 Firebase 控制台中，点击添加项目，然后选择或输入项目名称。

如果您已有 Google Cloud Platform (GCP) 项目，可以从下拉菜单中选择相应项目，将 Firebase 资源添加到该项目。

2. （可选）如果要创建新项目，可以修改项目 ID。

Firebase 会自动为您的 Firebase 项目分配一个唯一 ID。如需了解 Firebase 如何使用项目 ID，请访问“了解 Firebase 项目”。

注意：Firebase 为您的 Firebase 项目预配好资源后，您就无法再更改项目 ID。如需使用特定标识符，您必须在此设置步骤中修改项目 ID。

3. 点击继续。
4. 为您的项目设置 Google Analytics，以便在使用以下任何 Firebase 产品时都能获得最佳体验：

• Firebase Crashlytics
• Firebase Predictions
• Firebase Cloud Messaging
• Firebase In-App Messaging
• Firebase Remote Config
• Firebase A/B Testing

出现提示时，选择使用现有的 Google Analytics 账号或创建新账号。如果您选择创建新账号，请选择您的 Google Analytics 报告位置，然后接受项目的数据共享设置和 Google Analytics 条款。

5. 点击创建项目（如果使用现有 GCP 项目，则点击添加 Firebase）。

Firebase 会自动为您的 Firebase 项目预配资源。完成此过程后，您将进入 Firebase 控制台中 Firebase 项目的概览页面。

在 Firebase 中注册您的应用

有了 Firebase 项目后，您就可以向其中添加 iOS 应用了。

请访问了解 Firebase 项目，详细了解将应用添加到 Firebase 项目的最佳做法和注意事项，包括如何处理多个 build 变体。

1. 转到 Firebase 控制台。
2. 在项目概览页面的中心位置，点击 iOS 图标以启动设置工作流。

如果您已向 Firebase 项目添加了应用，请点击“添加应用”以显示平台选项。

3. 在 iOS 软件包 ID 字段中输入应用的软件包 ID。
4. （可选）输入其他应用信息：应用别名和 App Store ID。
5. 点击注册应用。

添加 Firebase 配置文件

1. 点击下载 GoogleService-Info.plist，获取 Firebase iOS 配置文件 (GoogleService-Info.plist)。
2. 将配置文件移动到 Xcode 项目的根目录中。如果出现提示，请选择将配置文件添加到所有目标。

如果您的项目中有多个软件包 ID，则必须将每个软件包 ID 与 Firebase 控制台中已注册的应用相关联，以便每个应用都可以拥有自己的 GoogleService-Info.plist 文件。

关闭 XCode。

将 Firebase SDK 添加到您的应用

我们建议使用 CocoaPods 安装 Firebase 库。不过，如果您不想使用 CocoaPods，可以直接集成 SDK 框架或使用 Swift Package Manager Beta 版。

1. 如果您没有 Podfile，请创建一个。如果您使用的是快速入门示例，则 Xcode 项目和 Podfile（包含 Pod）已经存在。

$ cd MessagingExample
$ pod init

2. 将想要在应用中使用的 Firebase Pod 添加到 Podfile 中。

您可以将任何受支持的 Firebase 产品添加到您的 iOS 应用中。

快速入门示例中添加了 Google Analytics 和 Firebase Cloud Messaging SDK。

# Add the Firebase pod for Google Analytics
pod 'Firebase/Analytics'

# Add the pod for Firebase Cloud Messaging
pod 'Firebase/Messaging'

3. 安装 Pod，然后打开 .xcworkspace 文件以在 Xcode 中查看该项目：

$ pod install

4. 打开 MessagingExample.xcworkspace，然后在 Firebase 控制台中点击下一步。

在您的应用中初始化 Firebase

您需要将 Firebase 初始化代码添加到您的应用中。

导入 Firebase 模块并配置一个共享实例（在快速入门示例中，已导入 Firebase 模块）。

1. 在 UIApplicationDelegate 中导入 Firebase 模块：

AppDelegate.swift

import UIKit
import Firebase // Add this line

2. 配置一个 FirebaseApp 共享实例（通常在应用的 application:didFinishLaunchingWithOptions: 方法中配置）：

AppDelegate.swift

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
  FirebaseApp.configure() // Add this line
  return true
}

3. 在 Firebase 控制台中点击下一步。
4. Firebase SDK 会添加到您的应用中。点击继续前往控制台。

5. 配置 FCM 客户端

上传您的 APNs 身份验证密钥

将您的 APNs 身份验证密钥上传到 Firebase。

1. 在 Firebase 控制台中，在您的项目内依次选择齿轮图标、项目设置以及 Cloud Messaging 标签页。
2. 在 iOS 应用配置下的 APNs 身份验证密钥中，点击上传按钮。
3. 浏览至您保存密钥的位置，选择该密钥，然后点击打开。添加该密钥的 ID（可在 Apple Developer Member Center 的 Certificates, Identifiers &Profiles 中找到），然后点击上传。

注册接收远程通知

在启动时或在应用流程中期望的时间点，注册您的应用以接收远程通知。

在快速入门示例中，已添加 registerForRemoteNotifications。

AppDelegate.swift

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
  FirebaseApp.configure()
  // [START register for remote notifications]
  if #available(iOS 10.0, *) {
    // For iOS 10 display notification (sent via APNS)
    UNUserNotificationCenter.current().delegate = self
        
    let authOptions: UNAuthorizationOptions = [.alert, .badge, .sound]
    UNUserNotificationCenter.current().requestAuthorization(options: authOptions, completionHandler: {_, _ in })
  } else {
    let settings: UIUserNotificationSettings = UIUserNotificationSettings(types: [.alert, .badge, .sound], categories: nil)
    application.registerUserNotificationSettings(settings)
  }

  application.registerForRemoteNotifications()
  // [END register for remote notifications]
  return true
}

通过在 AppDelegate.swift 末尾添加以下几行代码来分配 UNUserNotificationCenter 的委托属性。

AppDelegate.swift

@available(iOS 10, *)
extension AppDelegate : UNUserNotificationCenterDelegate {

  // Receive displayed notifications for iOS 10 devices.
  func userNotificationCenter(_ center: UNUserNotificationCenter,
                              willPresent notification: UNNotification,
    withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
    let userInfo = notification.request.content.userInfo

    // Print full message.
    print(userInfo)

    // Change this to your preferred presentation option
    completionHandler([[.alert, .sound]])
  }

  func userNotificationCenter(_ center: UNUserNotificationCenter,
                              didReceive response: UNNotificationResponse,
                              withCompletionHandler completionHandler: @escaping () -> Void) {
    let userInfo = response.notification.request.content.userInfo

    // Print full message.
    print(userInfo)

    completionHandler()
  }
}

设置消息委托

如需接收注册令牌，请实现消息委托协议，并在调用 [FIRApp configure] 后设置 FIRMessaging 的 delegate 属性。例如，如果您的应用委托符合消息委托协议，您可以将 application:didFinishLaunchingWithOptions: 上的委托设为其自身（在快速入门示例中，委托已设置）。

AppDelegate.swift

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
  FirebaseApp.configure()
  Messaging.messaging().delegate = self // Add this line
  // [START register for remote notifications]
  if #available(iOS 10.0, *) {
    // For iOS 10 display notification (sent via APNS)
    UNUserNotificationCenter.current().delegate = self
        
    let authOptions: UNAuthorizationOptions = [.alert, .badge, .sound]
    UNUserNotificationCenter.current().requestAuthorization(options: authOptions, completionHandler: {_, _ in })
  } else {
    let settings: UIUserNotificationSettings = UIUserNotificationSettings(types: [.alert, .badge, .sound], categories: nil)
    application.registerUserNotificationSettings(settings)
  }

  application.registerForRemoteNotifications()
  // [END register for remote notifications]
  return true
}

通过在 AppDelegate.swift 末尾添加以下几行代码来分配 FIRMessaging 的委托属性。

AppDelegate.swift

extension AppDelegate : MessagingDelegate {
  func messaging(_ messaging: Messaging, didReceiveRegistrationToken fcmToken: String?) {
    print("Firebase registration token: \(String(describing: fcmToken))")
    
    let dataDict:[String: String] = ["token": fcmToken ?? ""]
    NotificationCenter.default.post(name: Notification.Name("FCMToken"), object: nil, userInfo: dataDict)
  }
}

添加功能

您已在“Create an App ID”部分添加了推送通知功能，但您还必须按照以下步骤在 XCode 上添加此功能（以下步骤在 XCode 12.3 中进行了）：

1. 在“导航器区域”中点击项目名称。
2. 点击签名和功能。
3. 点击 + 功能。

4. 双击 Background Modes。
5. 再次点击 + 功能。
6. 双击 Push Notifications。
7. 选中 Background Modes 部分中的 Remote notifications。

6. 发送通知消息

您可以按照以下步骤发送测试消息：

1. 在目标设备上安装并运行应用。您需要接受权限请求，才能接收远程通知。
2. 在 XCode 日志中获取注册令牌。

3. 确保应用在设备后台运行。
4. 打开 Notifications Composer，然后选择新建通知。
5. 输入消息文字。
6. 选择发送测试消息。
7. 在标签为添加 FCM 注册令牌的字段中，输入您在第 2 步中获得的注册令牌。
8. 点击测试。

在您点击测试后，目标客户端设备（在后台中运行应用）应该会在通知中心内收到通知。

如需详细了解发送到您应用的消息，请参阅 FCM 报告信息中心，该信息中心记录了在 iOS 和 Android 设备上发送和打开的消息数量。

7. 恭喜

恭喜，您已成功发送测试邮件！

FCM 中还有许多其他的函数和配置，如主题订阅。

如果您对它们感兴趣，请参阅官方开发者文档。

后续操作

请查看以下 Codelab。

• 使用 Kotlin 进行高级 Android 01.2：Android Firebase Cloud Messaging

深入阅读

• Firebase Cloud Messaging 官方文档