在 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 发布的应用。

您可在 Apple Developer 会员中心创建以上两项。

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 项目后，您就可以将自己的 iOS 应用添加到其中了。

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

1. 转到 Firebase 控制台。

2. 在项目概览页面的中心位置，点击 iOS 图标 (plat_ios)，启动设置工作流。

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

3. 在 iOS 软件包 ID 字段中输入应用的软件包 ID。

   什么是软件包 ID，在哪里可以找到它？

   • 软件包 ID 是 Apple 生态系统中应用的唯一标识符。

   • 如何找到您的软件包 ID：在 Xcode 中打开您的 iOS 项目，在项目导航器中选择顶级应用，然后选择常规标签。

     软件包标识符字段的值就是 iOS 软件包 ID（例如 com.yourcompany.yourproject）。

   • 请注意，软件包 ID 值区分大小写，此 Firebase iOS 应用在您的 Firebase 项目中注册后，该值便无法更改。

4. （可选）输入其他应用信息：应用别名和 App Store ID。

   如何在 Firebase 中使用应用别名和 App Store ID？

   • 应用别名：方便内部使用的标识符，只有您能在 Firebase 控制台中看到

   • App Store ID：Firebase Dynamic Links 使用该 ID 将用户重定向到 App Store 页面，而 Google Analytics（分析）则用它将转化事件导入 Google Ads。 如果您的应用还没有 App Store ID，您可以稍后在项目设置中添加此 ID。

5. 点击注册应用。

添加 Firebase 配置文件

1. 点击下载 GoogleService-Info.plist，获取 Firebase iOS 配置文件 (GoogleService-Info.plist)。

   关于此配置文件，您需要了解哪些信息？

   • 该 Firebase 配置文件包含项目的唯一、非密文的标识符。如需详细了解此配置文件，请访问了解 Firebase 项目。

   • 您可以随时再次下载 Firebase 配置文件。

   • 请确保该配置文件名未附加其他字符，如 (2)。

2. 将配置文件移至 Xcode 项目的根目录中。如果出现提示，请选择将配置文件添加到所有目标。

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

将 Firebase SDK 添加至您的应用

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

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

1. 如果您没有 Podfile，请创建一个：

   cd your-project-directory

   pod init

2. 将想要用在应用中的 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'

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

   pod install

   open your-project.xcworkspace

上传您的 APNs 身份验证密钥

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

1. 在 Firebase 控制台中，在您的项目内依次选择齿轮图标、项目设置以及 Cloud Messaging 标签页。

2. 在 iOS 应用配置下的 APNs 身份验证密钥中，点击上传按钮。

3. 转到您保存密钥的位置，选择该密钥，然后点击打开。添加该密钥的 ID（可在 Apple Developer Member Center 中找到），然后点击上传。

在您的应用中初始化 Firebase

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

1. 在 UIApplicationDelegate 中导入 Firebase 模块：

   Swift

   import Firebase

   Objective-C

   @import Firebase;

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

   Swift

   // Use Firebase library to configure APIs
   FirebaseApp.configure()

   Objective-C

   // Use Firebase library to configure APIs
   [FIRApp configure];

注册接收远程通知

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

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

获取注册令牌

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

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

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

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

设置消息委托

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

Messaging.messaging().delegate = self

[FIRMessaging messaging].delegate = self;

获取当前的注册令牌

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

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

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

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)"
  }
}

[[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;
  }
}];

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

监控令牌刷新

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

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

- (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 属性：

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

// 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，您可以执行运行时调用：

Messaging.messaging().autoInitEnabled = true

[FIRMessaging messaging].autoInitEnabled = YES;

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

后续步骤

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

• 在 iOS 应用中接收消息
• 发送主题消息
• 向设备组发送消息