在 iOS 中设置 Firebase Cloud Messaging 客户端应用

对于 iOS 客户端应用，您可通过 Firebase Cloud Messaging APNs 接口接收不超过 4KB 的通知和数据载荷。

如需采用 Objective-C 或 Swift 编写客户端代码，我们建议您使用 FIRMessaging API。如需查看这两种语言的示例代码，请参阅快速入门示例。

要启用通过 APN 发送推送通知的功能，您需要：

一个为 Apple 开发者帐号设立的 Apple 推送通知身份验证密钥。 Firebase Cloud Messaging 使用此令牌将推送通知发送至应用 ID 标识的应用。
该应用 ID 的预配配置文件，已启用推送通知。要在开发时测试您的应用，您需要为开发环境创建一个预配配置文件，授权您的设备运行尚未在 App Store 发布的应用。

Firebase Cloud Messaging 中的方法调配

FCM SDK 在两个关键环节执行方法调配：将 APNs 令牌映射到 FCM 注册令牌，以及在处理下行消息回调函数期间捕获分析数据。如果开发者不希望使用调配，可以在应用的 Info.plist 文件中添加 FirebaseAppDelegateProxyEnabled 标志并将其设置为 NO（布尔值）来停用调配。指南的相关部分提供了启用和不启用方法调配的代码示例。

将 Firebase 添加至您的 iOS 项目

如果您已经为自己的应用启用了其他 Firebase 功能，那么您可能已经完成了本部分将要介绍的一些任务。您需要专门为 FCM 上传您的 APNs 身份验证密钥并注册接收远程通知。

前提条件

安装以下各项：
- Xcode 12.2 或更高版本
- CocoaPods 1.10.0 或更高版本
确保您的项目满足以下要求：
- 您的项目必须以 iOS 10 或更高版本为目标平台。

设置一台 iOS 真机设备以运行您的应用，然后完成以下任务：
- 获取您的 Apple 开发者帐号的 Apple 推送通知身份验证密钥。
- 在 XCode 中通过 App > Capabilities 启用推送通知功能。

使用您的 Google 帐号登录 Firebase。

如果您还没有 Xcode 项目，只是想试用某一 Firebase 产品，则可以下载一个我们的快速入门示例。

创建 Firebase 项目

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

创建 Firebase 项目

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

如果您已有 Google Cloud 项目，则可以从下拉菜单中选择该项目，然后将 Firebase 资源添加到该项目中。
（可选）如果要创建一个新项目，可以修改项目 ID。

Firebase 会自动为您的 Firebase 项目分配一个唯一的 ID。请访问了解 Firebase 项目以详细了解 Firebase 如何使用该项目 ID。

Firebase 为您的 Firebase 项目预配好资源后，您将无法更改项目 ID。
因此，如需使用特定标识符，就必须在此设置步骤修改项目 ID。
点击继续。

（可选）为您的项目设置 Google Analytics（分析），以便在使用以下任何 Firebase 产品时获得最佳体验：

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

点击创建项目（如果使用现有的 Google Cloud 项目，则点击添加 Firebase）。

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

在 Firebase 中注册您的应用

有了 Firebase 项目后，您就可以将自己的 iOS 应用添加到其中了。

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

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

如果您已向 Firebase 项目添加过应用，请点击添加应用以显示平台选项。
在 iOS 软件包 ID 字段中输入应用的软件包 ID。
什么是软件包 ID，在哪里可以找到它？
- 软件包 ID 是 Apple 生态系统中应用的唯一标识符。
- 如何找到您的软件包 ID：在 Xcode 中打开您的 iOS 项目，在项目导航器中选择顶级应用，然后选择常规标签。
  
  软件包标识符字段的值就是 iOS 软件包 ID（例如 com.yourcompany.yourproject）。
- 请注意，软件包 ID 值区分大小写，此 Firebase iOS 应用在您的 Firebase 项目中注册后，该值便无法更改。
请务必输入您的应用实际使用的软件包 ID。软件包 ID 值区分大小写，并且此 Firebase iOS 应用在您的 Firebase 项目中注册后，该值便无法更改。
（可选）输入其他应用信息：应用别名和 App Store ID。
应用别名和 App Store ID 在 Firebase 中起什么作用？
- 应用别名：方便内部使用的标识符，只有您能在 Firebase 控制台中看到
- App Store ID：Firebase Dynamic Links 使用该 ID 将用户重定向到 App Store 页面，而 Google Analytics（分析）则用它将转化事件导入 Google Ads。如果您的应用还没有 App Store ID，您可以稍后在项目设置中添加此 ID。
点击注册应用。

添加 Firebase 配置文件

点击下载 GoogleService-Info.plist，获取 Firebase iOS 配置文件 (GoogleService-Info.plist)。
关于此配置文件，您需要了解哪些信息？
- 此 Firebase 配置文件包含项目的唯一、非密文的标识符。如需详细了解此配置文件，请访问了解 Firebase 项目。
- 您可以随时再次下载 Firebase 配置文件。
- 请确保该配置文件名未附加其他字符，如 (2)。
将配置文件移至 Xcode 项目的根目录中。如果出现提示，请选择将配置文件添加到所有目标。

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

将 Firebase SDK 添加至您的应用

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

您是否使用了某个快速入门示例？Xcode 项目和 Podfile（包含 pod）已经存在，但您仍然需要添加 Firebase 配置文件并安装 pod。

如果您没有 Podfile，请创建一个：
```
cd your-project-directory
```
```
pod init
```
将想要用在应用中的 Firebase pod 添加到 Podfile。

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

为了获得最佳的 Firebase Cloud Messaging 使用体验，我们建议您在项目中启用 Google Analytics（分析）。此外，在设置 Analytics（分析）时，您还需要将适用于 Analytics（分析）的 Firebase SDK 添加到您的应用中。
已启用 Analytics
```
# Add the Firebase pod for Google Analytics
pod 'Firebase/Analytics'

# For Analytics without IDFA collection capability, use this pod instead
# pod ‘Firebase/AnalyticsWithoutAdIdSupport’

# Add the pod for Firebase Cloud Messaging
pod 'Firebase/Messaging'
```
如需详细了解 IDFA（设备级广告标识符），请参阅 Apple 的用户隐私和数据使用和 App Tracking Transparency 文档。
未启用 Analytics
```
# Add the pod for Firebase Cloud Messaging
pod 'Firebase/Messaging'
```
默认情况下，Firebase 的二进制依赖项集成为静态框架。如果将 Firebase 用作动态框架的依赖项，请务必阅读有关通过框架或库使用 Firebase 的文档。
安装 pod，然后打开 .xcworkspace 文件，以便在 Xcode 中查看该项目：
```
pod install
```
```
open your-project.xcworkspace
```

上传您的 APNs 身份验证密钥

将您的 APNs 身份验证密钥上传到 Firebase。如果您还没有 APNs 身份验证密钥，请务必在 Apple Developer Member Center 内创建一个。

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

在您的应用中初始化 Firebase

您需要为应用添加 Firebase 初始化代码。请按如下所示导入 Firebase 模块并配置一个共享实例：

在 UIApplicationDelegate 中导入 Firebase 模块：
Swift
```
import Firebase
```
Objective-C
```
@import Firebase;
```
配置一个 FirebaseApp 共享实例（通常在应用的 application:didFinishLaunchingWithOptions: 方法中配置）：
Swift
```
// Use Firebase library to configure APIs
FirebaseApp.configure()
```
Objective-C
```
// Use Firebase library to configure APIs
[FIRApp configure];
```

注册接收远程通知

可在启动时或在应用流程中期望的时间点注册您的应用，以便接收远程通知。调用 registerForRemoteNotifications，如下所示：

Swift

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()
AppDelegate.swift

Objective-C

if ([UNUserNotificationCenter class] != nil) {
  // iOS 10 or later
  // For iOS 10 display notification (sent via APNS)
  [UNUserNotificationCenter currentNotificationCenter].delegate = self;
  UNAuthorizationOptions authOptions = UNAuthorizationOptionAlert |
      UNAuthorizationOptionSound | UNAuthorizationOptionBadge;
  [[UNUserNotificationCenter currentNotificationCenter]
      requestAuthorizationWithOptions:authOptions
      completionHandler:^(BOOL granted, NSError * _Nullable error) {
        // ...
      }];
} else {
  // iOS 10 notifications aren't available; fall back to iOS 8-9 notifications.
  UIUserNotificationType allNotificationTypes =
  (UIUserNotificationTypeSound | UIUserNotificationTypeAlert | UIUserNotificationTypeBadge);
  UIUserNotificationSettings *settings =
  [UIUserNotificationSettings settingsForTypes:allNotificationTypes categories:nil];
  [application registerUserNotificationSettings:settings];
}

[application registerForRemoteNotifications];AppDelegate.m

对于运行 iOS 10 及更高版本的设备，您必须分配 UNUserNotificationCenter 的 delegate 属性和 FIRMessaging 的 delegate 属性。例如，在 iOS 应用中，需在应用委托的 applicationWillFinishLaunchingWithOptions: 或 applicationDidFinishLaunchingWithOptions: 方法中对其进行分配。

获取注册令牌

默认情况下，启动应用时，FCM SDK 会为客户端应用实例生成注册令牌。与 APNs 设备令牌类似，此令牌也允许您将针对性通知发送到应用的任何特定实例。

iOS 通常在应用启动时传送 APNs 设备令牌，FCM 以同样的方式通过 FIRMessagingDelegate 的 messaging:didReceiveRegistrationToken: 方法提供注册令牌。FCM SDK 会在应用初次启动期间以及令牌更新或失效时检索新令牌或现有令牌。无论哪种情况，FCM SDK 都会使用一个有效的令牌来调用 messaging:didReceiveRegistrationToken:。

注册令牌可能会在发生下列情况时更改：

应用在新设备上恢复
用户卸载/重新安装应用
用户清除应用数据

设置消息委托

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

Swift

Messaging.messaging().delegate = self

Objective-C

[FIRMessaging messaging].delegate = self;

获取当前的注册令牌

注册令牌是通过 messaging:didReceiveRegistrationToken: 方法传送的。系统通常会在应用每次启动时用注册令牌调用此方法一次。调用此方法时，最适合执行以下操作：

如果注册令牌是新的，将其发送到您的应用服务器。
为注册令牌订阅主题。只需针对新订阅或者在用户重新安装了应用时执行此操作。

您可以直接使用 token(completion:) 检索令牌。如果令牌检索失败，系统会显示非 NULL 错误。

Swift

Messaging.messaging().token { token, error in
  if let error = error {
    print("Error fetching FCM registration token: \(error)")
  } else if let token = token {
    print("FCM registration token: \(token)")
    self.fcmRegTokenMessage.text  = "Remote FCM registration token: \(token)"
  }
}

Objective-C

[[FIRMessaging messaging] tokenWithCompletion:^(NSString *token, NSError *error) {
  if (error != nil) {
    NSLog(@"Error getting FCM registration token: %@", error);
  } else {
    NSLog(@"FCM registration token: %@", token);
    self.fcmRegTokenMessage.text = token;
  }
}];

您随时可以使用此方法来访问令牌，而无需存储令牌。

监控令牌刷新

如需在每次令牌更新时获得通知，请提供符合消息委托协议的委托。以下示例注册了此类委托，并添加了合适的委托方法：

Swift

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
  )
  // TODO: If necessary send token to application server.
  // Note: This callback is fired at each app startup and whenever a new token is generated.
}
AppDelegate.swift

Objective-C

- (void)messaging:(FIRMessaging *)messaging didReceiveRegistrationToken:(NSString *)fcmToken {
    NSLog(@"FCM registration token: %@", fcmToken);
    // Notify about received token.
    NSDictionary *dataDict = [NSDictionary dictionaryWithObject:fcmToken forKey:@"token"];
    [[NSNotificationCenter defaultCenter] postNotificationName:
     @"FCMToken" object:nil userInfo:dataDict];
    // TODO: If necessary send token to application server.
    // Note: This callback is fired at each app startup and whenever a new token is generated.
}AppDelegate.m

或者，您也可以监听名为 kFIRMessagingRegistrationTokenRefreshNotification 的 NSNotification，而不提供委托方法。该令牌属性始终具有当前令牌值。

调配停用：映射您的 APNs 令牌和注册令牌

如果您已停用方法调配，则需要将您的 APNs 令牌明确映射到 FCM 注册令牌。您可以重写方法 didRegisterForRemoteNotificationsWithDeviceToken 来检索 APNs 令牌，然后设置 FIRMessaging 的 APNSToken 属性：

Swift

func application(application: UIApplication,
                 didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
  Messaging.messaging().apnsToken = deviceToken
}

Objective-C

// With "FirebaseAppDelegateProxyEnabled": NO
- (void)application:(UIApplication *)application
    didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
    [FIRMessaging messaging].APNSToken = deviceToken;
}

生成 FCM 注册令牌后，您可以使用与调配启用时相同的方法获取令牌和侦听刷新事件。

防止自动初始化

在生成 FCM 注册令牌后，库会将标识符和配置数据上传到 Firebase。如果您想先让用户进行明确的自行选择，则可以通过在配置时停用 FCM 来防止生成令牌。为此，请向您的 Info.plist（而不是 GoogleService-Info.plist）添加元数据值：

FirebaseMessagingAutoInitEnabled = NO

若要重新启用 FCM，您可以执行运行时调用：

Swift

Messaging.messaging().autoInitEnabled = true

Objective-C

[FIRMessaging messaging].autoInitEnabled = YES;

此值一经设置，就会在应用重启后持久保存。

后续步骤

设置 iOS 客户端后，您随时可以为应用添加消息处理和其他更高级的行为。如需了解详情，请参阅以下这些指南：

在 iOS 中设置 Firebase Cloud Messaging 客户端应用

Firebase Cloud Messaging 中的方法调配

将 Firebase 添加至您的 iOS 项目

前提条件

创建 Firebase 项目

在 Firebase 中注册您的应用

添加 Firebase 配置文件

将 Firebase SDK 添加至您的应用

已启用 Analytics

未启用 Analytics

上传您的 APNs 身份验证密钥

在您的应用中初始化 Firebase

Swift

Objective-C

Swift

Objective-C

注册接收远程通知

Swift

Objective-C

获取注册令牌

设置消息委托

Swift

Objective-C

获取当前的注册令牌

Swift

Objective-C

监控令牌刷新

Swift

Objective-C

调配停用：映射您的 APNs 令牌和注册令牌

Swift

Objective-C

防止自动初始化

Swift

Objective-C

后续步骤