在 iOS 中设置 Firebase 云消息传递客户端应用

对于 iOS 客户端应用，您可通过两种互补的方式实现 Firebase 云消息传递 (FCM)：

  • 通过 Firebase 云消息传递 APNs 接口接收不超过 4KB 的基本推送消息。

  • 在前台应用中发送上行消息和/或接收下行数据负载，最高 4KB。

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

Firebase 云消息传递中的方法调配

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

将 Firebase 添加至您的 iOS 项目

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

前提条件

开始之前，需要在您的环境中设置几项内容：

  • Xcode 9.4.1 或更高版本
  • 一个针对 iOS 8 或更高版本的 Xcode 项目
  • Swift 项目必须使用 Swift 3.0 或更高版本
  • 您的应用的软件包标识符
  • CocoaPods 1.4.0 或更高版本
  • 针对云消息传递：
    • 一台 iOS 真机
    • 一个 Apple 开发者帐号所对应的 Apple 推送通知身份验证密钥
    • 在 Xcode 中通过 App > Capabilities 启用推送通知功能

如果您还没有 Xcode 项目，只是想试用一下某项 Firebase 功能，可以下载我们的快速入门示例。如果使用快速入门示例，请不要忘记从项目设置中获取软件包标识符，下一步中会用到该标识符。

将 Firebase 添加到您的应用

现在需要将 Firebase 添加至您的应用。要执行此操作，您需要有一个 Firebase 项目和适用于您的应用的 Firebase 配置文件。

要创建 Firebase 项目，请执行以下操作：

  1. 访问 Firebase 控制台。

  2. 点击添加项目，然后选择或输入项目名称。

    • 如果您已经拥有一个与应用关联的 Google 项目，请从项目名称下拉菜单中选择该项目。
    • 如果您尚未创建 Google 项目，请输入新的项目名称。

  3. （可选）修改项目 ID。

    Firebase 会自动为您的 Firebase 项目分配一个独一无二的 ID。此 ID 会显示在公众可见的 Firebase 服务中，例如：

    • 默认实时数据库网址：your-project-id.firebaseio.com
    • 默认 Cloud Storage 存储分区名称：your-project-id.appspot.com
    • 默认托管子网域：your-project-id.firebaseapp.com

  4. 在 Firebase 控制台中完成剩下的设置步骤，然后点击创建项目（如果您使用的是现有 Google 项目，则点击添加 Firebase）。

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

创建项目之后，您就可以向其中添加 iOS 应用了：

  1. 点击将 Firebase 添加到您的 iOS 应用，然后按设置步骤操作。如果您是导入现有 Google 项目，系统可能会自动执行这些操作，您只需下载配置文件即可。

  2. 看到提示时，输入应用的软件包 ID。请务必输入应用在使用的软件包 ID；只有在将应用添加到 Firebase 项目时您才能进行此设置。

  3. 将 Firebase iOS 配置文件添加到您的应用：

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

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

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

  4. 添加初始化代码后，运行您的应用以便向 Firebase 控制台发送验证信息，证明您已成功安装 Firebase。

添加 SDK

如果您是设置一个新项目，则需要安装 SDK。您可能已经在创建 Firebase 项目的过程中完成此步操作。

我们建议使用 CocoaPods 安装相关的库。您可以按照安装说明来安装 Cocoapods。如果不想使用 CocoaPods，则可以直接集成 SDK 框架，而不使用 CocoaPods。

如果您计划下载并运行某个快速入门示例，示例中会提供 Xcode 项目和 Podfile，不过您还是需要安装 Pod 并下载 GoogleService-Info.plist 文件。如果您希望将 Firebase 库集成至自己的某个项目中，则需要为想要使用的库添加 Pod。

  1. 如果还没有 Xcode 项目，请立即创建一个。

  2. 如果还没有 Podfile，请创建一个：

    $ cd your-project directory
$ pod init

  3. 添加您想安装的 Pod。您可以按照以下方法在 Podfile 中纳入一个 Pod：

    pod 'Firebase/Core'
pod 'Firebase/Messaging'

    这会在您的 iOS 应用中添加 Firebase 正常运行所需的必备库以及 Google Analytics for Firebase 功能。下面列出了目前可供使用的一系列 pod 和 subspec。在针对不同功能的设置指南中也对此给出了相应的链接。

  4. 安装 Pod 并打开 .xcworkspace 文件以便在 Xcode 中查看该项目。

    $ pod install
$ open your-project.xcworkspace

  5. 从 Firebase 控制台中下载一个 GoogleService-Info.plist 文件并将其添加到您的应用中。

上传您的 APNs 身份验证密钥

将您的 APNs 身份验证密钥上传到 Firebase。如果您还没有 APNs 身份验证密钥，请参阅配置 FCM APNs。

  1. 在 Firebase 控制台中，在您的项目内依次选择齿轮图标、项目设置以及云消息传递标签。

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

  3. 转到您保存密钥的位置，选择该密钥，然后点击打开。添加该密钥的密钥 ID（可在 Apple 开发者会员中心的 Certificates, Identifiers & Profiles 中找到），然后点击上传。

在您的应用中初始化 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];

注册接收远程通知

可在启动时或应用流程中的指定时刻注册您的应用，以便接收远程通知。按如下所示调用 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

获取注册令牌

默认情况下，启动应用时，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: 方法传送的。系统通常会在应用每次启动时用注册令牌调用此方法。调用此方法后，最适合执行以下操作：

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

您可以直接使用 instanceIDWithHandler: 检索令牌。此回调函数会提供 InstanceIDResult，其中包含令牌。如果 InstanceID 检索以任何方式失败，则系统会显示非 NULL 错误。

Swift

InstanceID.instanceID().instanceID { (result, error) in
  if let error = error {
    print("Error fetching remote instance ID: \(error)")
  } else if let result = result {
    print("Remote instance ID token: \(result.token)")
    self.instanceIDTokenMessage.text  = "Remote InstanceID token: \(result.token)"
  }
}

Objective-C

[[FIRInstanceID instanceID] instanceIDWithHandler:^(FIRInstanceIDResult * _Nullable result,
                                                    NSError * _Nullable error) {
  if (error != nil) {
    NSLog(@"Error fetching remote instance ID: %@", error);
  } else {
    NSLog(@"Remote instance ID token: %@", result.token);
    NSString* message =
      [NSString stringWithFormat:@"Remote InstanceID token: %@", result.token];
    self.instanceIDTokenMessage.text = message;
  }
}];

通常情况下，令牌在本地提供，因此该方法不会打开网络连接。您随时可以使用此方法来访问令牌，而无需存储令牌。

监控令牌刷新

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

Swift

func messaging(_ messaging: Messaging, didReceiveRegistrationToken fcmToken: String) {
  print("Firebase registration token: \(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: NSData) {
  Messaging.messaging().apnsToken = deviceToken
}

Objective-C

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

生成 FCM 注册令牌后，您可以像在启用了调配时那样获取令牌和侦听刷新事件。

导入现有的用户 APNs 令牌

如果想要将现有用户群加入 FCM 客户端应用，请使用 Instance ID 提供的 batchImport API。使用此 API，您可以将现有的 iOS APNs 令牌批量导入 FCM，将它们映射到有效的新注册令牌。

防止自动初始化

FCM 会生成一个实例 ID，并在 FCM 中将其用作注册令牌。在生成实例 ID 后，库会将标识符和配置数据上传到 Firebase。如果您想在使用实例 ID 之前能够明确地自行选择，则可以通过在配置时停用 FCM 来防止生成代码。为此，请向您的 Info.plist（而非 GoogleService-Info.plist）添加元数据值：

FirebaseMessagingAutoInitEnabled = NO

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

Swift

Messaging.messaging().autoInitEnabled = true

Objective-C

[FIRMessaging messaging].autoInitEnabled = YES;

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

后续步骤

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

发送以下问题的反馈：

此网页
文档反馈
Firebase
Firebase
产品反馈
需要帮助？请访问我们的支持页面。