要開始使用 FCM,請構建最簡單的用例:當應用程序在設備後台運行時,將測試通知消息從通知編輯器發送到開發設備。此頁面列出了實現此目的的所有步驟,從設置到驗證——如果您已為 FCM設置 Apple 客戶端應用程序,它可能涵蓋您已經完成的步驟。
將 Firebase 添加到您的 Apple 項目
如果您已經為您的應用啟用了其他 Firebase 功能,本部分涵蓋您可能已經完成的任務。具體對於 FCM,您需要上傳您的 APNs 身份驗證密鑰並註冊遠程通知。
先決條件
安裝以下內容:
- Xcode 13.3.1 或更高版本
確保您的項目滿足以下要求:
- 您的項目必須針對這些平台版本或更高版本:
- iOS 11
- macOS 10.13
- 電視操作系統 12
- watchOS 6
- 您的項目必須針對這些平台版本或更高版本:
設置物理 Apple 設備來運行您的應用程序,並完成以下任務:
- 為您的Apple Developer 帳戶獲取 Apple Push Notification Authentication Key。
- 在App > Capabilities下的 XCode 中啟用推送通知。
- 使用您的 Google 帳戶登錄 Firebase 。
如果您還沒有 Xcode 項目並且只想試用 Firebase 產品,您可以下載我們的快速入門示例之一。
創建一個 Firebase 項目
在將 Firebase 添加到您的 Apple 應用程序之前,您需要創建一個 Firebase 項目以連接到您的應用程序。訪問了解 Firebase 項目以了解有關 Firebase 項目的更多信息。
向 Firebase 註冊您的應用
要在您的 Apple 應用程序中使用 Firebase,您需要在 Firebase 項目中註冊您的應用程序。註冊您的應用程序通常稱為將您的應用程序“添加”到您的項目中。
轉到Firebase 控制台。
在項目概覽頁面的中央,單擊iOS+圖標以啟動設置工作流程。
如果您已將應用程序添加到 Firebase 項目,請單擊添加應用程序以顯示平台選項。
在bundle ID字段中輸入您應用程序的 bundle ID。
捆綁包 ID唯一標識 Apple 生態系統中的應用程序。
查找您的包 ID:在 Xcode 中打開您的項目,在項目導航器中選擇頂級應用程序,然後選擇常規選項卡。
Bundle Identifier字段的值是包 ID(例如,
com.yourcompany.yourproject
)。請注意,bundle ID 值區分大小寫,在您的 Firebase 項目中註冊後,無法更改此 Firebase 應用程序的值。
(可選)輸入其他應用信息:應用暱稱和App Store ID 。
應用暱稱:僅在 Firebase 控制台中對您可見的內部便利標識符
App Store ID :由 Firebase 動態鏈接用於將用戶重定向到您的 App Store 頁面,由 Google Analytics 用於將轉換事件導入 Google Ads 。如果您的應用還沒有 App Store ID,您可以稍後在項目設置中添加 ID。
單擊註冊應用程序。
添加 Firebase 配置文件
單擊下載 GoogleService-Info.plist以獲取您的 Firebase Apple 平台配置文件 (
GoogleService-Info.plist
)。Firebase 配置文件包含項目的唯一但非機密標識符。要了解有關此配置文件的更多信息,請訪問了解 Firebase 項目。
您可以隨時再次下載您的Firebase 配置文件。
確保配置文件名未附加其他字符,例如
(2)
。
將配置文件移動到 Xcode 項目的根目錄中。如果出現提示,請選擇將配置文件添加到所有目標。
如果您的項目中有多個 bundle ID,則必須將每個 bundle ID 與 Firebase 控制台中註冊的應用相關聯,以便每個應用都可以擁有自己的GoogleService-Info.plist
文件。
將 Firebase SDK 添加到您的應用
使用 Swift Package Manager 安裝和管理 Firebase 依賴項。
- 在 Xcode 中,打開您的應用程序項目,導航至File > Add Packages 。
- 出現提示時,添加 Firebase Apple 平台 SDK 存儲庫:
- 選擇 Firebase 雲消息傳遞庫。
- 為了獲得 Firebase 雲消息傳遞的最佳體驗,我們建議在您的 Firebase 項目中啟用 Google Analytics ,並將適用於 Google Analytics 的 Firebase SDK 添加到您的應用程序中。您可以選擇沒有 IDFA 集合或有 IDFA 集合的庫。
- 完成後,Xcode 將自動開始在後台解析和下載您的依賴項。
https://github.com/firebase/firebase-ios-sdk
上傳您的 APNs 身份驗證密鑰
將您的 APNs 身份驗證密鑰上傳到 Firebase。如果您還沒有 APNs 身份驗證密鑰,請確保在Apple Developer Member Center中創建一個。
在 Firebase 控制台的項目內,選擇齒輪圖標,選擇Project Settings ,然後選擇Cloud Messaging選項卡。
在iOS app configuration下的APNs authentication key中,點擊Upload按鈕。
瀏覽到您保存密鑰的位置,選擇它,然後單擊打開。添加密鑰的密鑰 ID(可在Apple Developer Member Center中獲得)並單擊Upload 。
在您的應用中初始化 Firebase
您需要將 Firebase 初始化代碼添加到您的應用程序中。導入 Firebase 模塊並配置共享實例,如下所示:
- 在您的
UIApplicationDelegate
中導入FirebaseCore
模塊,以及您的應用委託使用的任何其他Firebase 模塊。例如,要使用 Cloud Firestore 和身份驗證:斯威夫特用戶界面
import SwiftUI import FirebaseCore import FirebaseFirestore import FirebaseAuth // ...
迅速
import FirebaseCore import FirebaseFirestore import FirebaseAuth // ...
目標-C
@import FirebaseCore; @import FirebaseFirestore; @import FirebaseAuth; // ...
- 在您的應用委託的
application(_:didFinishLaunchingWithOptions:)
方法中配置一個FirebaseApp
共享實例:斯威夫特用戶界面
// Use Firebase library to configure APIs FirebaseApp.configure()
迅速
// Use Firebase library to configure APIs FirebaseApp.configure()
目標-C
// Use Firebase library to configure APIs [FIRApp configure];
- 如果您使用的是 SwiftUI,則必須創建一個應用程序委託並通過
UIApplicationDelegateAdaptor
或NSApplicationDelegateAdaptor
將其附加到您的App
結構。您還必須禁用應用委託調配。有關詳細信息,請參閱SwiftUI 說明。斯威夫特用戶界面
@main struct YourApp: App { // register app delegate for Firebase setup @UIApplicationDelegateAdaptor(AppDelegate.self) var delegate var body: some Scene { WindowGroup { NavigationView { ContentView() } } } }
註冊遠程通知
在啟動時或應用程序流程中的所需時間點,註冊您的應用程序以獲取遠程通知。如圖所示調用registerForRemoteNotifications
:迅速
UNUserNotificationCenter.current().delegate = self let authOptions: UNAuthorizationOptions = [.alert, .badge, .sound] UNUserNotificationCenter.current().requestAuthorization( options: authOptions, completionHandler: { _, _ in } ) application.registerForRemoteNotifications()
目標-C
[UNUserNotificationCenter currentNotificationCenter].delegate = self; UNAuthorizationOptions authOptions = UNAuthorizationOptionAlert | UNAuthorizationOptionSound | UNAuthorizationOptionBadge; [[UNUserNotificationCenter currentNotificationCenter] requestAuthorizationWithOptions:authOptions completionHandler:^(BOOL granted, NSError * _Nullable error) { // ... }]; [application registerForRemoteNotifications];
訪問註冊令牌
要向特定設備發送消息,您需要知道該設備的註冊令牌。由於您需要在通知編輯器的字段中輸入令牌才能完成本教程,因此請務必復制令牌或在檢索後安全地存儲它。
默認情況下,FCM SDK 在應用啟動時為客戶端應用實例生成一個註冊令牌。與 APNs 設備令牌類似,此令牌允許您向應用程序的任何特定實例發送有針對性的通知。
與 Apple 平台通常在應用程序啟動時提供 APNs 設備令牌的方式相同,FCM 通過FIRMessagingDelegate
的messaging:didReceiveRegistrationToken:
方法提供註冊令牌。 FCM SDK 在初始應用程序啟動期間以及令牌更新或失效時檢索新令牌或現有令牌。在所有情況下,FCM SDK 都會使用有效令牌調用messaging:didReceiveRegistrationToken:
在以下情況下,註冊令牌可能會更改:
- 該應用程序已在新設備上恢復
- 用戶卸載/重新安裝應用程序
- 用戶清除應用程序數據。
設置消息代理
要接收註冊令牌,請實施消息傳遞委託協議並在調用[FIRApp configure]
後設置FIRMessaging
的delegate
屬性。例如,如果您的應用程序委託符合消息傳遞委託協議,您可以將application:didFinishLaunchingWithOptions:
上的委託設置為其自身。
迅速
Messaging.messaging().delegate = self
目標-C
[FIRMessaging messaging].delegate = self;
獲取當前註冊令牌
註冊令牌通過messaging:didReceiveRegistrationToken:
方法傳遞。通常每個應用程序以註冊令牌開始調用此方法一次。調用此方法時,是執行以下操作的理想時機:
- 如果註冊令牌是新的,請將其發送到您的應用程序服務器。
- 將註冊令牌訂閱到主題。這僅適用於新訂閱或用戶重新安裝應用程序的情況。
您可以使用token(completion:)直接檢索令牌。如果令牌檢索以任何方式失敗,則會提供非空錯誤。
迅速
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)" } }
目標-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; } }];
您可以隨時使用此方法訪問令牌而不是存儲它。
監控令牌刷新
要在令牌更新時收到通知,請提供符合消息傳遞委託協議的委託。以下示例註冊委託並添加適當的委託方法:
迅速
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. }
目標-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
而不是提供委託方法。令牌屬性始終具有當前令牌值。
發送通知消息
在目標設備上安裝並運行該應用程序。在 Apple 設備上,您需要接受接收遠程通知的權限請求。
確保應用程序在設備的後台運行。
在 Firebase 控制台中,打開消息頁面。
如果這是您的第一條消息,請選擇創建您的第一個營銷活動。
- 選擇Firebase Notification messages並選擇Create 。
否則,在“活動”選項卡上,選擇“新建活動” ,然後選擇“通知” 。
輸入消息文本。所有其他字段都是可選的。
從右窗格中選擇發送測試消息。
在標記為添加 FCM 註冊令牌的字段中,輸入您在本指南上一節中獲得的註冊令牌。
選擇測試。
選擇測試後,目標客戶端設備(應用程序在後台)應該會收到通知。
要深入了解向您的應用程序發送的消息,請參閱FCM 報告儀表板,它記錄了在 Apple 和 Android 設備上發送和打開的消息數量,以及 Android 應用程序的“印象”(用戶看到的通知)數據。
下一步
要超越通知消息並向您的應用程序添加其他更高級的行為,請參閱:
,要開始使用 FCM,請構建最簡單的用例:當應用程序在設備後台運行時,將測試通知消息從通知編輯器發送到開發設備。此頁面列出了實現此目的的所有步驟,從設置到驗證——如果您已為 FCM設置 Apple 客戶端應用程序,它可能涵蓋您已經完成的步驟。
將 Firebase 添加到您的 Apple 項目
如果您已經為您的應用啟用了其他 Firebase 功能,本部分涵蓋您可能已經完成的任務。具體對於 FCM,您需要上傳您的 APNs 身份驗證密鑰並註冊遠程通知。
先決條件
安裝以下內容:
- Xcode 13.3.1 或更高版本
確保您的項目滿足以下要求:
- 您的項目必須針對這些平台版本或更高版本:
- iOS 11
- macOS 10.13
- 電視操作系統 12
- watchOS 6
- 您的項目必須針對這些平台版本或更高版本:
設置物理 Apple 設備來運行您的應用程序,並完成以下任務:
- 為您的Apple Developer 帳戶獲取 Apple Push Notification Authentication Key。
- 在App > Capabilities下的 XCode 中啟用推送通知。
- 使用您的 Google 帳戶登錄 Firebase 。
如果您還沒有 Xcode 項目並且只想試用 Firebase 產品,您可以下載我們的快速入門示例之一。
創建一個 Firebase 項目
在將 Firebase 添加到您的 Apple 應用程序之前,您需要創建一個 Firebase 項目以連接到您的應用程序。訪問了解 Firebase 項目以了解有關 Firebase 項目的更多信息。
向 Firebase 註冊您的應用
要在您的 Apple 應用程序中使用 Firebase,您需要在 Firebase 項目中註冊您的應用程序。註冊您的應用程序通常稱為將您的應用程序“添加”到您的項目中。
轉到Firebase 控制台。
在項目概覽頁面的中央,單擊iOS+圖標以啟動設置工作流程。
如果您已將應用程序添加到 Firebase 項目,請單擊添加應用程序以顯示平台選項。
在bundle ID字段中輸入您應用程序的 bundle ID。
捆綁包 ID唯一標識 Apple 生態系統中的應用程序。
查找您的包 ID:在 Xcode 中打開您的項目,在項目導航器中選擇頂級應用程序,然後選擇常規選項卡。
Bundle Identifier字段的值是包 ID(例如,
com.yourcompany.yourproject
)。請注意,bundle ID 值區分大小寫,在您的 Firebase 項目中註冊後,無法更改此 Firebase 應用程序的值。
(可選)輸入其他應用信息:應用暱稱和App Store ID 。
應用暱稱:僅在 Firebase 控制台中對您可見的內部便利標識符
App Store ID :由 Firebase 動態鏈接用於將用戶重定向到您的 App Store 頁面,由 Google Analytics 用於將轉換事件導入 Google Ads 。如果您的應用還沒有 App Store ID,您可以稍後在項目設置中添加 ID。
單擊註冊應用程序。
添加 Firebase 配置文件
單擊下載 GoogleService-Info.plist以獲取您的 Firebase Apple 平台配置文件 (
GoogleService-Info.plist
)。Firebase 配置文件包含項目的唯一但非機密標識符。要了解有關此配置文件的更多信息,請訪問了解 Firebase 項目。
您可以隨時再次下載您的Firebase 配置文件。
確保配置文件名未附加其他字符,例如
(2)
。
將配置文件移動到 Xcode 項目的根目錄中。如果出現提示,請選擇將配置文件添加到所有目標。
如果您的項目中有多個 bundle ID,則必須將每個 bundle ID 與 Firebase 控制台中註冊的應用相關聯,以便每個應用都可以擁有自己的GoogleService-Info.plist
文件。
將 Firebase SDK 添加到您的應用
使用 Swift Package Manager 安裝和管理 Firebase 依賴項。
- 在 Xcode 中,打開您的應用程序項目,導航至File > Add Packages 。
- 出現提示時,添加 Firebase Apple 平台 SDK 存儲庫:
- 選擇 Firebase 雲消息傳遞庫。
- 為了獲得 Firebase 雲消息傳遞的最佳體驗,我們建議在您的 Firebase 項目中啟用 Google Analytics ,並將適用於 Google Analytics 的 Firebase SDK 添加到您的應用程序中。您可以選擇沒有 IDFA 集合或有 IDFA 集合的庫。
- 完成後,Xcode 將自動開始在後台解析和下載您的依賴項。
https://github.com/firebase/firebase-ios-sdk
上傳您的 APNs 身份驗證密鑰
將您的 APNs 身份驗證密鑰上傳到 Firebase。如果您還沒有 APNs 身份驗證密鑰,請確保在Apple Developer Member Center中創建一個。
在 Firebase 控制台的項目內,選擇齒輪圖標,選擇Project Settings ,然後選擇Cloud Messaging選項卡。
在iOS app configuration下的APNs authentication key中,點擊Upload按鈕。
瀏覽到您保存密鑰的位置,選擇它,然後單擊打開。添加密鑰的密鑰 ID(可在Apple Developer Member Center中獲得)並單擊Upload 。
在您的應用中初始化 Firebase
您需要將 Firebase 初始化代碼添加到您的應用程序中。導入 Firebase 模塊並配置共享實例,如下所示:
- 在您的
UIApplicationDelegate
中導入FirebaseCore
模塊,以及您的應用委託使用的任何其他Firebase 模塊。例如,要使用 Cloud Firestore 和身份驗證:斯威夫特用戶界面
import SwiftUI import FirebaseCore import FirebaseFirestore import FirebaseAuth // ...
迅速
import FirebaseCore import FirebaseFirestore import FirebaseAuth // ...
目標-C
@import FirebaseCore; @import FirebaseFirestore; @import FirebaseAuth; // ...
- 在您的應用委託的
application(_:didFinishLaunchingWithOptions:)
方法中配置一個FirebaseApp
共享實例:斯威夫特用戶界面
// Use Firebase library to configure APIs FirebaseApp.configure()
迅速
// Use Firebase library to configure APIs FirebaseApp.configure()
目標-C
// Use Firebase library to configure APIs [FIRApp configure];
- 如果您使用的是 SwiftUI,則必須創建一個應用程序委託並通過
UIApplicationDelegateAdaptor
或NSApplicationDelegateAdaptor
將其附加到您的App
結構。您還必須禁用應用委託調配。有關詳細信息,請參閱SwiftUI 說明。斯威夫特用戶界面
@main struct YourApp: App { // register app delegate for Firebase setup @UIApplicationDelegateAdaptor(AppDelegate.self) var delegate var body: some Scene { WindowGroup { NavigationView { ContentView() } } } }
註冊遠程通知
在啟動時或應用程序流程中的所需時間點,註冊您的應用程序以獲取遠程通知。如圖所示調用registerForRemoteNotifications
:迅速
UNUserNotificationCenter.current().delegate = self let authOptions: UNAuthorizationOptions = [.alert, .badge, .sound] UNUserNotificationCenter.current().requestAuthorization( options: authOptions, completionHandler: { _, _ in } ) application.registerForRemoteNotifications()
目標-C
[UNUserNotificationCenter currentNotificationCenter].delegate = self; UNAuthorizationOptions authOptions = UNAuthorizationOptionAlert | UNAuthorizationOptionSound | UNAuthorizationOptionBadge; [[UNUserNotificationCenter currentNotificationCenter] requestAuthorizationWithOptions:authOptions completionHandler:^(BOOL granted, NSError * _Nullable error) { // ... }]; [application registerForRemoteNotifications];
訪問註冊令牌
要向特定設備發送消息,您需要知道該設備的註冊令牌。由於您需要在通知編輯器的字段中輸入令牌才能完成本教程,因此請務必復制令牌或在檢索後安全地存儲它。
默認情況下,FCM SDK 在應用啟動時為客戶端應用實例生成一個註冊令牌。與 APNs 設備令牌類似,此令牌允許您向應用程序的任何特定實例發送有針對性的通知。
與 Apple 平台通常在應用程序啟動時提供 APNs 設備令牌的方式相同,FCM 通過FIRMessagingDelegate
的messaging:didReceiveRegistrationToken:
方法提供註冊令牌。 FCM SDK 在初始應用程序啟動期間以及令牌更新或失效時檢索新令牌或現有令牌。在所有情況下,FCM SDK 都會使用有效令牌調用messaging:didReceiveRegistrationToken:
在以下情況下,註冊令牌可能會更改:
- 該應用程序已在新設備上恢復
- 用戶卸載/重新安裝應用程序
- 用戶清除應用程序數據。
設置消息代理
要接收註冊令牌,請實施消息傳遞委託協議並在調用[FIRApp configure]
後設置FIRMessaging
的delegate
屬性。例如,如果您的應用程序委託符合消息傳遞委託協議,您可以將application:didFinishLaunchingWithOptions:
上的委託設置為其自身。
迅速
Messaging.messaging().delegate = self
目標-C
[FIRMessaging messaging].delegate = self;
獲取當前註冊令牌
註冊令牌通過messaging:didReceiveRegistrationToken:
方法傳遞。通常每個應用程序以註冊令牌開始調用此方法一次。調用此方法時,是執行以下操作的理想時機:
- 如果註冊令牌是新的,請將其發送到您的應用程序服務器。
- 將註冊令牌訂閱到主題。這僅適用於新訂閱或用戶重新安裝應用程序的情況。
您可以使用token(completion:)直接檢索令牌。如果令牌檢索以任何方式失敗,則會提供非空錯誤。
迅速
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)" } }
目標-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; } }];
您可以隨時使用此方法訪問令牌而不是存儲它。
監控令牌刷新
要在令牌更新時收到通知,請提供符合消息傳遞委託協議的委託。以下示例註冊委託並添加適當的委託方法:
迅速
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. }
目標-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
而不是提供委託方法。令牌屬性始終具有當前令牌值。
發送通知消息
在目標設備上安裝並運行該應用程序。在 Apple 設備上,您需要接受接收遠程通知的許可請求。
確保應用程序在設備的後台運行。
在 Firebase 控制台中,打開消息頁面。
如果這是您的第一條消息,請選擇創建您的第一個營銷活動。
- 選擇Firebase Notification messages並選擇Create 。
否則,在“活動”選項卡上,選擇“新建活動” ,然後選擇“通知” 。
輸入消息文本。所有其他字段都是可選的。
從右窗格中選擇發送測試消息。
在標記為添加 FCM 註冊令牌的字段中,輸入您在本指南上一節中獲得的註冊令牌。
選擇測試。
選擇測試後,目標客戶端設備(應用程序在後台)應該會收到通知。
要深入了解向您的應用程序發送的消息,請參閱FCM 報告儀表板,它記錄了在 Apple 和 Android 設備上發送和打開的消息數量,以及 Android 應用程序的“印象”(用戶看到的通知)數據。
下一步
要超越通知消息並向您的應用程序添加其他更高級的行為,請參閱: