本快速入門導覽課程說明如何在行動和網頁用戶端應用程式中設定 Firebase Cloud Messaging，以便穩定傳送訊息。如果是伺服器環境，請參閱「您的伺服器環境和 FCM」。

在 Flutter 上設定 Firebase 雲端通訊用戶端應用程式

視目標平台而定，您需要完成一些額外的必要設定步驟。

iOS+

在 Xcode 中啟用應用程式功能

應用程式必須先在 Xcode 專案中啟用推播通知和背景模式，才能開始接收訊息。

1. 開啟 Xcode 專案工作區 (`ios/Runner.xcworkspace`)。
2. 啟用推播通知。
3. 啟用「背景擷取」和「遠端通知」背景執行模式。

上傳 APNs 驗證金鑰

使用 FCM 前，請先將 APN 驗證金鑰上傳至 Firebase 控制台。如果還沒有 APNs 驗證金鑰，請在 Apple Developer Member Center 建立。

1. 在 Firebase 控制台的專案中，依序選取齒輪圖示、「專案設定」和「Cloud Messaging」分頁標籤。
2. 選取「上傳」按鈕，上傳開發或正式版驗證金鑰，或兩者皆上傳。或至少擇一提供。
3. 針對每個驗證金鑰，選取 .p8 檔案，並提供金鑰 ID 和 Apple 團隊 ID。選取「儲存」。

方法交換

如要在 Apple 裝置上使用 FCM Flutter 外掛程式，必須進行方法交換。如果沒有這個檔案，FCM 權杖處理等重要 Firebase 功能就無法正常運作。

Android

Google Play 服務

FCM 用戶端必須在搭載 Android 4.4 以上版本，且已安裝 Google Play 服務的裝置上執行，或是使用搭載 Google API 的 Android 4.4 模擬器。請注意，您不一定要透過 Google Play 商店部署 Android 應用程式。

如果應用程式使用 Play 服務 SDK，存取 Google Play 服務功能前，請務必先檢查裝置是否安裝相容的 Google Play 服務 APK。建議在兩個位置執行這項操作：主要活動的 onCreate() 方法和 onResume() 方法。onCreate() 中的檢查可確保應用程式必須通過檢查才能使用。onResume() 中的檢查可確保使用者透過其他方式 (例如返回按鈕) 返回執行中的應用程式時，系統仍會執行檢查。

如果裝置沒有相容版本的 Google Play 服務，應用程式可以呼叫 GoogleApiAvailability.makeGooglePlayServicesAvailable()，讓使用者從 Play 商店下載 Google Play 服務。

網頁

使用「FCM」設定網站憑證

FCM 網頁介面會使用稱為「自願應用程式伺服器識別碼」或「VAPID」金鑰的網頁憑證，授權將要求傳送至支援的網頁推播服務。如要讓應用程式訂閱推播通知，您需要將一組金鑰與 Firebase 專案建立關聯。您可以透過 Firebase 控制台產生新的金鑰組，或是匯入現有的金鑰組。

產生新的金鑰組

1. 開啟 Firebase 控制台「設定」窗格的「Cloud Messaging」分頁，然後前往「Web configuration」部分。
2. 在「Web Push certificates」(網路推播憑證) 分頁中，按一下「Generate Key Pair」(產生金鑰組)。控制台會顯示金鑰組已產生的通知，以及公開金鑰字串和新增日期。

匯入現有的金鑰組

如果您已使用現有的金鑰組搭配網頁應用程式，可以將該金鑰組匯入 FCM，以便透過 FCM API 存取現有的網頁應用程式例項。如要匯入金鑰，您必須擁有 Firebase 專案的擁有者層級存取權。以 Base64 URL 安全編碼形式匯入現有的公開和私密金鑰：

1. 開啟 Firebase 控制台「設定」窗格的「Cloud Messaging」分頁，然後前往「Web configuration」部分。
2. 在「Web Push certificates」(網頁推送通知憑證) 分頁中，選取「import an existing key pair」(匯入現有的金鑰配對)。
3. 在「Import a key pair」對話方塊中，在對應欄位中提供公開和私密金鑰，然後按一下「Import」。控制台會顯示公開金鑰字串和新增日期。

如要進一步瞭解金鑰格式和產生方式，請參閱「應用程式伺服器金鑰」。

安裝 FCM 外掛程式

1. 如果尚未安裝及初始化 Flutter 適用的 Firebase 外掛程式，請執行此步驟。

2. 在 Flutter 專案的根目錄中，執行下列指令來安裝外掛程式：

   flutter pub add firebase_messaging
   

3. 完成後，請重建 Flutter 應用程式：

   flutter run
   

存取註冊權杖

如要傳送訊息給特定裝置，您必須知道裝置的註冊權杖。如要擷取應用程式例項的註冊權杖，請呼叫 getToken()。如果尚未授予通知權限，這個方法會要求使用者授予通知權限。否則，系統會傳回權杖，或因發生錯誤而拒絕 Future。

// You may set the permission requests to "provisional" which allows the user to choose what type
// of notifications they would like to receive once the user receives a notification.
final notificationSettings = await FirebaseMessaging.instance.requestPermission(provisional: true);

// For apple platforms, make sure the APNS token is available before making any FCM plugin API calls
final apnsToken = await FirebaseMessaging.instance.getAPNSToken();
if (apnsToken != null) {
 // APNS token is available, make FCM plugin API requests...
}

在網頁平台上，將 VAPID 公開金鑰傳遞至 getToken()：

final fcmToken = await FirebaseMessaging.instance.getToken(vapidKey: "BKagOny0KF_2pCJQ3m....moL0ewzQ8rZu");

如要在權杖更新時收到通知，請訂閱 onTokenRefresh 串流：

FirebaseMessaging.instance.onTokenRefresh
    .listen((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.
    })
    .onError((err) {
      // Error getting token.
    });

防止自動初始化

產生 FCM 註冊權杖時，程式庫會將 ID 和設定資料上傳至 Firebase。如要避免自動產生權杖，請在建構時停用自動初始化。

iOS

在 iOS 上，將中繼資料值新增至 Info.plist：

FirebaseMessagingAutoInitEnabled = NO

Android

在 Android 上，將下列中繼資料值新增至 AndroidManifest.xml，即可停用 Analytics 收集功能和 FCM 自動初始化功能 (兩者都必須停用)：

<meta-data
    android:name="firebase_messaging_auto_init_enabled"
    android:value="false" />
<meta-data
    android:name="firebase_analytics_collection_enabled"
    android:value="false" />

重新啟用執行階段的 FCM 自動初始化功能

如要為特定應用程式例項啟用自動初始化功能，請呼叫 setAutoInitEnabled()：

await FirebaseMessaging.instance.setAutoInitEnabled(true);

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

傳送測試通知訊息

1. 在目標裝置上安裝並執行應用程式。在 Apple 裝置上，你必須接受接收遠端通知的權限要求。
2. 確認裝置上的應用程式在背景執行。
3. 在 Firebase 控制台中，開啟「Messaging」頁面。
4. 如果是第一次建立訊息，請選取「建立您的第一個廣告活動」。
   1. 選取「Firebase 通知訊息」，然後選取「建立」。
5. 否則，請在「廣告活動」分頁中選取「新增廣告活動」，然後選取「通知」。
6. 輸入訊息文字。
7. 在右側窗格中選取「傳送測試訊息」。
8. 在標示為「新增 FCM 註冊權杖」的欄位中，輸入註冊權杖。
9. 選取「測試」。

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

如要深入瞭解訊息傳送至應用程式的情況，請參閱 FCM 報表資訊主頁，其中會記錄在 Apple 和 Android 裝置上傳送及開啟的訊息數量，以及 Android 應用程式的曝光資料。

處理互動

使用者輕觸通知時，Android 和 iOS 預設都會開啟應用程式。如果應用程式已終止，系統會啟動應用程式；如果應用程式在背景執行，系統會將其移至前景。

視通知內容而定，您可能想在應用程式開啟時處理使用者的互動。舉例來說，如果使用者透過通知傳送新的即時通訊訊息，並選取該訊息，您可能會希望在應用程式開啟時，開啟特定對話。

firebase-messaging 套件提供兩種處理這類互動的方式：

1. getInitialMessage(): 如果應用程式是從終止狀態開啟，這個方法會傳回包含 RemoteMessage 的 Future。RemoteMessage 一經使用就會移除。
2. onMessageOpenedApp：應用程式從背景狀態開啟時，會發布 RemoteMessage 的 Stream。

為確保使用者體驗順暢，您應處理這兩種情況。以下程式碼範例說明如何達成這個目標：

class Application extends StatefulWidget {
  @override
  State createState() => _Application();
}

class _Application extends State {
  // In this example, suppose that all messages contain a data field with the key 'type'.
  Future setupInteractedMessage() async {
    // Get any messages which caused the application to open from
    // a terminated state.
    RemoteMessage? initialMessage =
        await FirebaseMessaging.instance.getInitialMessage();

    // If the message also contains a data property with a "type" of "chat",
    // navigate to a chat screen
    if (initialMessage != null) {
      _handleMessage(initialMessage);
    }

    // Also handle any interaction when the app is in the background using a
    // Stream listener
    FirebaseMessaging.onMessageOpenedApp.listen(_handleMessage);
  }

  void _handleMessage(RemoteMessage message) {
    if (message.data['type'] == 'chat') {
      Navigator.pushNamed(context, '/chat',
        arguments: ChatArguments(message),
      );
    }
  }

  @override
  void initState() {
    super.initState();

    // Run code required to handle interacted messages in an async function
    // as initState() must not be async
    setupInteractedMessage();
  }

  @override
  Widget build(BuildContext context) {
    return Text("...");
  }
}

互動的處理方式取決於您的設定。先前顯示的範例是使用 StatefulWidget 的基本範例。

後續步驟

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

• 傳送訊息到裝置
• 在 Flutter 應用程式中接收訊息
• 將訊息傳送至主題