对于 iOS 客户端应用,您可通过 Firebase Cloud Messaging APNs 接口接收不超过 4KB 的通知和数据载荷。
如需采用 Objective-C 或 Swift 编写客户端代码,我们建议您使用 FIRMessaging API。如需查看这两种语言的示例代码,请参阅快速入门示例。
Firebase Cloud Messaging 中的方法调配
FCM SDK 在两个关键环节执行方法调配:将 APNs 令牌映射到 FCM 注册令牌,以及在处理下行消息回调函数期间捕获分析数据。
如果开发者不希望使用调配,可以在应用的 Info.plist 文件中添加 FirebaseAppDelegateProxyEnabled
标志并将其设置为 NO(布尔值)来停用调配。指南的相关部分提供了启用和不启用方法调配的代码示例。
将 Firebase 添加至您的 iOS 项目
如果您已经为自己的应用启用了其他 Firebase 功能,那么您可能已经完成了本部分将要介绍的一些任务。您需要专门为 FCM 上传您的 APNs 身份验证密钥并注册接收远程通知。
前提条件
安装以下内容:
- Xcode 12.0 或更高版本
- CocoaPods 1.9.0 或更高版本
确保您的项目满足以下要求:
- 您的项目必须针对 iOS 10 或更高版本。
设置一台 iOS 真机设备以运行您的应用,然后完成以下任务:
- 获取您的 Apple 开发者帐号的 Apple 推送通知身份验证密钥。
- 在 XCode 中通过 App > Capabilities 启用推送通知功能。
- 使用您的 Google 帐号登录 Firebase。
如果您还没有 Xcode 项目,只是想试用某一 Firebase 产品,则可以下载一个我们的快速入门示例。
创建 Firebase 项目
您必须先创建一个要关联到 iOS 应用的 Firebase 项目,然后才能将 Firebase 添加到您的 iOS 应用。请访问了解 Firebase 项目以了解详情。
在 Firebase 中注册您的应用
有了 Firebase 项目后,您就可以将自己的 iOS 应用添加到其中了。
请访问了解 Firebase 项目以详细了解将应用添加到 Firebase 项目的最佳做法和注意事项,包括如何处理多个构建变体。
转到 Firebase 控制台。
在项目概览页面的中心位置,点击 iOS 图标 (
),启动设置工作流。如果您已向 Firebase 项目添加过应用,请点击添加应用以显示平台选项。
在 iOS 软件包 ID 字段中输入应用的软件包 ID。
(可选)输入其他应用信息:应用别名和 App Store ID。
点击注册应用。
添加 Firebase 配置文件
点击下载 GoogleService-Info.plist,获取 Firebase iOS 配置文件 (
GoogleService-Info.plist
)。将配置文件移至 Xcode 项目的根目录中。如果出现提示,请选择将配置文件添加到所有目标。
如果您的项目中有多个软件包 ID,则必须将每个软件包 ID 与 Firebase 控制台中的注册应用相关联,使每个应用都有自己的 GoogleService-Info.plist
文件。
将 Firebase SDK 添加至您的应用
我们建议使用 CocoaPods 安装 Firebase 库。但是,如果您不想使用 CocoaPods,可以直接集成 SDK 框架,也可以使用 Swift Package Manager Beta 版。
您是否使用了某个快速入门示例?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'
# Add the pod for Firebase Cloud Messaging pod 'Firebase/Messaging'未启用 Analytics(分析)
# Add the pod for Firebase Cloud Messaging pod 'Firebase/Messaging'
安装 pod,然后打开
.xcworkspace
文件以便在 Xcode 中查看该项目:pod install
open your-project.xcworkspace
上传您的 APNs 身份验证密钥
将您的 APNs 身份验证密钥上传到 Firebase。如果您还没有 APNs 身份验证密钥,请参阅配置 FCM APNs。
-
在 Firebase 控制台中,在您的项目内依次选择齿轮图标、项目设置以及 Cloud Messaging 标签页。
-
在 iOS 应用配置下的 APNs 身份验证密钥中,点击上传按钮。
-
转到您保存密钥的位置,选择该密钥,然后点击打开。添加该密钥的 ID(可在 Apple Developer Member Center 的 Certificates, Identifiers & Profiles 中找到),然后点击上传。
在您的应用中初始化 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()
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 设备令牌类似,此令牌也允许您将针对性通知发送到应用的任何特定实例。
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. }
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. }
或者,您也可以监听名为 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 客户端后,您随时可以为应用添加消息处理和其他更高级的行为。如需了解详情,请参阅以下这些指南: