開始在 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 控制台中，依序前往「設定」 >「一般」。然後按一下「Cloud Messaging」分頁標籤。
  2. 在「iOS 應用程式設定」下方的「APN 驗證金鑰」中，按一下「上傳」，上傳開發或正式版驗證金鑰，或同時上傳兩者。至少須提供一個。
  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 的重新核發時機和手動監控方式，請參閱「監控 Firebase 安裝 ID 生命週期」。

使用 Firebase 安裝 ID 啟用註冊功能

如要啟用應用程式執行個體向 FCM 註冊的功能，請使用 Firebase 安裝 ID (FID)， 並在 Info.plist 檔案中新增下列中繼資料標記，而非 GoogleService-Info.plist 檔案：

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：對應 APN 權杖和 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.
}

或者，您也可以監聽名為 NSNotification 的 kFIRMessagingRegistrationTokenRefreshNotification，而非提供委派方法。權杖屬性一律具有目前的權杖值。

停用 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」(DevOps 與參與度) >「Messaging」(訊息)

  4. 建立廣告活動。

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

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

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

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

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

      2. 按一下「通知」。

  5. 輸入訊息文字。

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

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

  8. 選取「測試」。

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

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

後續步驟

完成設定步驟後，您可以選擇下列幾種方式，繼續使用 Apple 平台專用的 FCM：