開始在 Apple 平台應用程式中使用 Firebase 雲端通訊

選取平台： iOS+ Android 網頁 Flutter Unity C++


本指南說明如何在 Apple 平台 (例如 iOS) 用戶端應用程式中開始使用 Firebase Cloud Messaging，以便穩定傳送訊息。

如果是 Apple 用戶端應用程式，您可透過 Firebase Cloud Messaging APNs 介面接收通知和資料酬載，最多 4096 位元組。

如要以 Objective-C 或 Swift 編寫用戶端程式碼，建議使用 FIRMessaging API。快速入門範例提供兩種語言的程式碼範例。

開始之前，請先將 Firebase 新增至 Apple 專案。

Firebase Cloud Messaging 中的方法交換

FCM SDK 會在兩個主要領域執行方法調換：將 APNs 權杖對應至 Firebase 安裝 ID 或 FCM 註冊權杖，以及在下游訊息回呼處理期間擷取 Analytics 資料。如果開發人員不想使用 Swizzling，可以在應用程式的 Info.plist 檔案中新增 FirebaseAppDelegateProxyEnabled 旗標，並將其設為布林值 NO，即可停用這項功能。指南的相關部分提供程式碼範例，包括啟用和未啟用方法交換的範例。

上傳 APN 驗證金鑰

將 APNs 驗證金鑰上傳至 Firebase。如果沒有 APNs 驗證金鑰，請務必在 Apple 開發人員會員中心建立。

  1. 在 Firebase 控制台中，依序前往「設定」 >「一般」。然後點選「雲端通訊」分頁標籤。
  2. 在「iOS 應用程式設定」下方的「APNs 驗證金鑰」中，點按「上傳」，上傳開發或正式版驗證金鑰，或兩者皆上傳。至少須提供一個。
  3. 瀏覽至金鑰的儲存位置，選取金鑰，然後按一下「開啟」。新增金鑰的 ID (可在 Apple Developer Member Center 中取得)，然後按一下「上傳」。

註冊遠端通知

在啟動時或應用程式流程中的所需時間點，註冊應用程式以接收遠端通知。如以下範例所示呼叫 registerForRemoteNotifications：

Swift

UNUserNotificationCenter.current().delegate = self

let authOptions: UNAuthorizationOptions = [.alert, .badge, .sound]
UNUserNotificationCenter.current().requestAuthorization(
  options: authOptions,
  completionHandler: { _, _ in }
)

application.registerForRemoteNotifications()

Objective-C

[UNUserNotificationCenter currentNotificationCenter].delegate = self;
UNAuthorizationOptions authOptions = UNAuthorizationOptionAlert |
    UNAuthorizationOptionSound | UNAuthorizationOptionBadge;
[[UNUserNotificationCenter currentNotificationCenter]
    requestAuthorizationWithOptions:authOptions
    completionHandler:^(BOOL granted, NSError * _Nullable error) {
      // ...
    }];

[application registerForRemoteNotifications];

存取 Firebase 安裝 ID

根據預設，FCM SDK 會向 FCM 註冊應用程式例項，並在應用程式啟動時，為用戶端應用程式例項傳回 Firebase 安裝 ID (FID)。與 APNs 裝置權杖類似，這個 FID 可讓您將目標通知傳送至應用程式的任何特定例項。

與 Apple 平台通常會在應用程式啟動時傳送 APNs 裝置權杖的方式相同，FCM 會提供 FID，用於指定通知目標。FCM SDK 會使用 FIRMessagingDelegate 的 messaging:didReceiveRegistration: 方法傳送 FID，自動監控 FID 變更，並在偵測到變更時，使用新的 FID 叫用該方法。建議您定期擷取及上傳 FID，因為 FID 可能會在初始啟動後輪替。

如要進一步瞭解 FID 的重新核發時機，以及如何手動監控 FID，請參閱「監控 Firebase 安裝 ID 的生命週期」。

使用 Firebase 安裝 ID 啟用註冊

如要使用 FCM 註冊應用程式例項，請新增下列中繼資料標記至 Info.plist 檔案，而非 GoogleService-Info.plist 檔案： Firebase 安裝 ID (FID)

FirebaseMessagingInstallationIdEnabled = YES

設定訊息委派

如要接收 FID，請實作訊息委派通訊協定，並在呼叫 [FIRApp configure] 後設定 FIRMessaging 的 delegate 屬性。舉例來說，如果應用程式委派物件符合訊息委派物件通訊協定，您可以在 application:didFinishLaunchingWithOptions: 上將委派物件設為本身。

Swift

Messaging.messaging().delegate = self

Objective-C

[FIRMessaging messaging].delegate = self;

實作 didReceiveRegistration 方法

註冊完成後，系統會使用 FID 做為應用程式執行個體的目標。如要在註冊時接收 FID，請實作 messaging:didReceiveRegistration: 方法。這個方法通常會在每次啟動應用程式時，連同 FID 一併叫用。呼叫這個方法時，您可以執行下列動作：

  • 如果尚未將 FID 傳送至伺服器，或最近才傳送 FID，請將 FID 傳送至應用程式伺服器。
  • 如果使用者是新訂閱者或重新安裝應用程式，請將 FID 訂閱至主題。

Swift

func messaging(_ messaging: Messaging, didReceiveRegistration installationId: String?) {
  print("Firebase Installation ID: \(String(describing: installationId))")
  // Note: This callback is fired at each app startup.

  if let installationId = installationId {
    // Send the Firebase Installation ID to your app server.
    sendRegistrationToServer(installationId)
  }
}

Objective-C

- (void)messaging:(FIRMessaging *)messaging didReceiveRegistration:(nullable NSString *)installationId {
  NSLog(@"Firebase Installation ID: %@", installationId);
  // Note: This callback is fired at each app startup.

  if (installationId != nil) {
    // Send the Firebase Installation ID to your app server.
    [self sendRegistrationToServer:installationId];
  }
}

停用自動初始化功能時，請手動註冊

如果停用自動初始化，FCM SDK 就不會在應用程式啟動時，自動向 FCM 註冊應用程式例項。您必須在應用程式啟動時呼叫 register，透過 messaging:didReceiveRegistration: 方法觸發註冊程序並傳送 FID：

Swift

// Trigger manual registration if auto-initialization is turned off.
Messaging.messaging().register { error in
    if let error = error {
        // Handle the error
        print("Failed registering: \(error)")
        return
    }
    // Registration was successful. FID is delivered through the messaging:didReceiveRegistration: method.
    print("Successfully registered.")
}

Objective-C

// Trigger manual registration if auto-initialization is turned off.
[[FIRMessaging messaging] registerWithCompletion:^(NSError * _Nullable error) {
    if (error) {
        // Handle the error
        NSLog(@"Failed registering: %@", error);
        return;
    }
    // Registration was successful. FID is delivered through the messaging:didReceiveRegistration: method.
    NSLog(@"Successfully registered.");
}];

停用 Swizzling：對應 APNs 權杖和 FID

如果您已停用方法交換，或正在建構 SwiftUI 應用程式，就必須將 APNs 權杖明確對應至 Firebase 安裝 ID (FID)。實作 application(_:didRegisterForRemoteNotificationsWithDeviceToken:) 方法，擷取 APNs 權杖，然後設定 Messaging 的 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;
}

註冊 FID 後，您可以使用與啟用交換時相同的方法存取 FID，並監聽重新整理事件。

存取註冊權杖

根據預設，FCM SDK 會在應用程式啟動時，為用戶端應用程式例項產生註冊權杖。與 APNs 裝置權杖類似，這個權杖可讓您將目標通知傳送至應用程式的任何特定例項。

與 Apple 平台通常會在應用程式啟動時傳送 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:) 直接擷取權杖。如果權杖擷取作業因任何原因失敗，系統會提供非空值錯誤。

Swift

Messaging.messaging().token { token, error in
  if let error = error {
    print("Error fetching remote FCM registration token: \(error)")
  } else if let token = token {
    print("Remote instance ID token: \(token)")
  }
}

Objective-C

[[FIRMessaging messaging] tokenWithCompletion:^(NSString * _Nullable token, NSError * _Nullable error) {
  if (error != nil) {
    NSLog(@"Error fetching the remote FCM registration token: %@", error);
  } else {
    NSLog(@"Remote FCM registration token: %@", token);
    NSString* message =
      [NSString stringWithFormat:@"FCM registration token: %@", token];
    // display message
    NSLog(@"%@", message);
  }
}];

您可以隨時使用這個方法存取權杖，不必儲存權杖。

監控權杖更新

如要在權杖更新時收到通知，請提供符合訊息委派通訊協定的委派。以下範例會註冊委派，並新增適當的委派方法：

Swift

func messaging(_ messaging: Messaging, didReceiveRegistrationToken fcmToken: String?) {
  print("Firebase registration token: \(String(describing: fcmToken))")
  // 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，而不是提供委派方法。權杖屬性一律會包含目前的權杖值。

停用 Swizzling：對應 APNs 權杖和註冊權杖

如果您已停用方法交換，或是要建構 SwiftUI 應用程式，就必須將 APNs 權杖明確對應至 FCM 註冊權杖。實作 application(_:didRegisterForRemoteNotificationsWithDeviceToken:) 方法來擷取 APNs 權杖，然後設定 Messaging 的 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 註冊權杖後，您可以使用與啟用 swizzling 時相同的方法存取權杖，並監聽重新整理事件。

防止自動初始化

產生 FCM 註冊時，程式庫會將 ID 和設定資料上傳至 Firebase。如要先取得使用者的明確同意聲明，可以在設定時停用 FCM，防止自動註冊。如要這麼做，請將中繼資料值新增至 Info.plist (而非 GoogleService-Info.plist)：

FirebaseMessagingAutoInitEnabled = NO

如要重新啟用 FCM，可以進行執行階段呼叫：

Swift

Messaging.messaging().autoInitEnabled = true

Objective-C

[FIRMessaging messaging].autoInitEnabled = YES;

設定後，這個值會在應用程式重新啟動時保留。

設定通知服務擴充功能

如要傳送含圖片的通知到 Apple 裝置，必須新增通知服務擴充功能。這項擴充功能可讓裝置顯示通知酬載中傳送的圖片。如果不想在通知中傳送圖片，可以略過這個步驟。

如要新增服務擴充功能，請先完成必要設定工作，以便在 APNs 中修改及顯示通知，然後在 NotificationService.m 中新增 FCM 擴充功能輔助 API。具體來說，請使用 FIRMessaging extensionHelper 完成回呼，而非 self.contentHandler(self.bestAttemptContent);，如下所示：

@interface NotificationService () <NSURLSessionDelegate>
@property(nonatomic) void (^contentHandler)(UNNotificationContent *contentToDeliver);
@property(nonatomic) UNMutableNotificationContent *bestAttemptContent;
@end

@implementation NotificationService

- (void)didReceiveNotificationRequest:(UNNotificationRequest *)request withContentHandler:(void (^)(UNNotificationContent * _Nonnull))contentHandler {
    self.contentHandler = contentHandler;
self.bestAttemptContent = [request.content mutableCopy];

    // Modify the notification content here as you want
self.bestAttemptContent.title = [NSString stringWithFormat:@"%@ [modified]",
self.bestAttemptContent.title];

  // Call FIRMessaging extension helper API.
  [[FIRMessaging extensionHelper] populateNotificationContent:self.bestAttemptContent
withContentHandler:contentHandler];

}
...

傳送通知訊息

  1. 在目標裝置上安裝並執行應用程式。在 Apple 裝置上，接受接收遠端通知的權限要求。

  2. 確認應用程式在裝置上於背景執行。

  3. 在 Firebase 控制台中，依序前往「DevOps & Engagement」(開發運作與參與度) >「Messaging」(訊息)

  4. 建立廣告活動。

    • 如果這是您的第一則訊息：

      1. 選取「建立第一個廣告活動」。

      2. 選取「Firebase 通知訊息」，然後選取「建立」。

    • 如果您先前已建立廣告活動：

      1. 在「廣告活動」分頁中，選取「新增廣告活動」。

      2. 按一下「通知」。

  5. 輸入訊息文字。

  6. 在右側窗格中選取「傳送測試訊息」。

  7. 在標示為「新增 Firebase 安裝 ID 或註冊權杖」FCM的欄位中，輸入註冊權杖。

  8. 選取「測試」。

選取「測試」後，目標用戶端裝置應會收到通知，且應用程式會在背景執行。

如要深入瞭解訊息傳送至應用程式的情形，請前往 Firebase 控制台的「DevOps 和參與度」&gt;「訊息」&gt;「報告」資訊主頁。這個資訊主頁會記錄在 Apple 和 Android 裝置上傳送及開啟的訊息數量，以及 Android 應用程式的「曝光次數」(使用者看到的通知) 資料。

後續步驟

完成設定步驟後，您可以透過下列幾種方式，在 Apple 平台上使用 FCM：