Catch up on everthing we announced at this year's Firebase Summit. Learn more

在 Apple 平台上设置 Firebase Cloud Messaging 客户端应用

对于 Apple 客户端应用,您可通过 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 添加到您的 Apple 项目中

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

前提条件

  • 安装以下各项:

    • Xcode 12.2 或更高版本
    • CocoaPods 1.10.0 或更高版本
  • 确保您的项目满足以下要求:

    • 您的项目的目标平台不得低于以下版本:
      • iOS 10
      • macOS 10.12
      • tvOS 12
      • watchOS 6
  • 设置一台 Apple 真机设备以运行您的应用,然后完成以下任务:

    • 获取您的 Apple 开发者帐号的 Apple 推送通知身份验证密钥。
    • 在 XCode 中通过 App > Capabilities 启用推送通知功能。

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

创建 Firebase 项目

您需要先创建一个要关联到应用的 Firebase 项目,然后才能将 Firebase 添加到您的 Apple 应用。请访问了解 Firebase 项目,了解详情。

在 Firebase 中注册您的应用

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

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

  1. 转到 Firebase 控制台

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

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

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

  4. (可选)输入其他应用信息:应用别名App Store ID

  5. 点击注册应用

添加 Firebase 配置文件

  1. 点击下载 GoogleService-Info.plist,获取 Firebase Apple 平台配置文件 (GoogleService-Info.plist)。

  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 产品添加到 Apple 应用中。

    为了获得最佳的 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];

注册接收远程通知

可在启动时或在应用流程中期望的时间点注册您的应用,以便接收远程通知。调用 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()

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

获取注册令牌

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

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

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

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

设置消息委托

如需接收注册令牌,请实现消息委托协议,并在调用 [FIRApp configure] 后设置 FIRMessagingdelegate 属性。例如,如果您的应用委托符合消息委托协议,可以将 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.
}

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.
}

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

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

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

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;

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

后续步骤

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