開始使用 Firebase 雲端通訊


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

使用 Unity 設定 Firebase Cloud Messaging用戶端應用程式

如要使用 Unity 編寫跨平台的 Firebase Cloud Messaging 用戶端應用程式，請使用 Firebase Cloud Messaging API。Unity SDK 適用於 Android 和 Apple，但每個平台都需要額外設定。

事前準備

事前準備

  • 安裝 Unity 2021 LTS 以上版本。Unity 2020 的支援服務已淘汰，下一個主要版本發布後，我們將不再主動提供支援。舊版或許也能使用，但不會主動提供支援。

  • (僅限 Apple 平台) 安裝下列項目：

    • Xcode 13.3.1 以上版本
    • CocoaPods 1.12.0 以上版本

  • 請確認 Unity 專案符合下列規定：

    • 適用於 iOS：指定 iOS 13 以上版本
    • tvOS：指定 tvOS 13 以上版本
    • Android：指定 API 級別 21 (Lollipop) 以上版本

  • 設定裝置或使用模擬器執行 Unity 專案。

    • iOS 或 tvOS：設定實體裝置來執行應用程式，並完成下列工作：

      • 為Apple 開發人員帳戶取得 Apple 推播通知驗證金鑰。
      • 在 XCode 中依序前往「App」 >「Capabilities」，然後啟用推播通知。

    • Android：模擬器必須使用搭載 Google Play 的模擬器映像檔。

如果您還沒有 Unity 專案，只是想試用 Firebase 產品，可以下載我們的快速入門範例。

步驟 1：建立 Firebase 專案

將 Firebase 新增至 Unity 專案前，請先建立要連結至該 Unity 專案的 Firebase 專案。如要進一步瞭解 Firebase 專案，請參閱「瞭解 Firebase 專案」一文。

步驟 2：向 Firebase 註冊應用程式

您可以註冊一或多個應用程式或遊戲，與 Firebase 專案建立連結。

  1. 前往 Firebase 控制台。

  2. 在專案總覽頁面中間，按一下「Unity」圖示 () 啟動設定工作流程。

    如果已在 Firebase 專案中新增應用程式，請按一下「新增應用程式」，顯示平台選項。

  3. 選取要註冊的 Unity 專案建構目標，或同時註冊兩個目標。

  4. 輸入 Unity 專案的平台專屬 ID。

    • iOS：在「iOS 軟體包 ID」欄位中，輸入 Unity 專案的 iOS ID。

    • Android：在「Android package name」(Android 套件名稱) 欄位中，輸入 Unity 專案的 Android ID。
      「套件名稱」和「應用程式 ID」這兩個詞彙經常互通。

  5. (選用) 輸入 Unity 專案的平台專屬暱稱。
    這些暱稱是內部使用的便利 ID，只會顯示在Firebase控制台中。

  6. 按一下 [Register app] (註冊應用程式)。

步驟 3：新增 Firebase 設定檔

  1. 在 Firebase 控制台設定工作流程中，取得平台專屬的 Firebase 設定檔。

    • iOS 版：按一下「下載 GoogleService-Info.plist」。

    • Android 版：按一下「下載 google-services.json」。

  2. 開啟 Unity 專案的「Project」視窗，然後將設定檔移至 Assets 資料夾。

  3. 返回 Firebase 控制台，在設定工作流程中按一下「下一步」。

步驟 4：新增 Firebase Unity SDK

  1. 在 Firebase 控制台中，按一下「Download Firebase Unity SDK」(下載 Firebase Unity SDK)，然後將 SDK 解壓縮到方便的位置。

    • 您可以隨時重新下載 Firebase Unity SDK。

    • Firebase Unity SDK 不限於特定平台。

  2. 在開啟的 Unity 專案中，依序前往「Assets」 >「Import Package」 >「Custom Package」。

  3. 在已解壓縮的 SDK 中，選取要在應用程式中使用的支援 Firebase 產品。

    為獲得最佳 Firebase Cloud Messaging 體驗，建議您在專案中啟用 Google Analytics。此外，設定 Analytics 時，您也必須將 Analytics 的 Firebase 套件新增至應用程式。

    已啟用 Analytics 個

    • 為 Google Analytics 新增 Firebase 套件： FirebaseAnalytics.unitypackage
    • 新增 Firebase Cloud Messaging 的套件： FirebaseMessaging.unitypackage

    Analytics未啟用

    新增 Firebase Cloud Messaging 的套件： FirebaseMessaging.unitypackage

  4. 在「Import Unity Package」視窗，按一下「Import」。

  5. 返回 Firebase 控制台，在設定工作流程中按一下「下一步」。

步驟 5：確認 Google Play 服務版本需求

Android 版 Firebase Unity SDK 中的部分產品需要 Google Play services。瞭解哪些產品有這項依附元件。必須先更新「Google Play services」，才能使用這些產品。

在應用程式開頭加入下列 using 陳述式和初始化程式碼。您可以在呼叫 SDK 中的任何其他方法之前，檢查 Google Play services 是否為必要版本，並視需要更新。

using Firebase.Extensions;

Firebase.FirebaseApp.CheckAndFixDependenciesAsync().ContinueWithOnMainThread(task => {
  var dependencyStatus = task.Result;
  if (dependencyStatus == Firebase.DependencyStatus.Available) {
    // Create and hold a reference to your FirebaseApp,
    // where app is a Firebase.FirebaseApp property of your application class.
       app = Firebase.FirebaseApp.DefaultInstance;

    // Set a flag here to indicate whether Firebase is ready to use by your app.
  } else {
    UnityEngine.Debug.LogError(System.String.Format(
      "Could not resolve all Firebase dependencies: {0}", dependencyStatus));
    // Firebase Unity SDK is not safe to use here.
  }
});

Unity 專案已註冊並設定為使用 Firebase。

設定 Apple 平台

請按照下列操作說明，使用 Unity 和 Apple 平台設定 FCM。

上傳 APN 驗證金鑰

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

  1. 在 Firebase 控制台的專案中，依序選取齒輪圖示、「專案設定」和「Cloud Messaging」分頁標籤。

  2. 在「iOS 應用程式設定」下方的「APN 驗證金鑰」中，按一下「上傳」按鈕，上傳開發或正式版驗證金鑰，或兩者都上傳。至少須提供一個。

  3. 瀏覽至您儲存金鑰的位置，選取金鑰，然後按一下「開啟」。新增金鑰的 ID (可在 Apple Developer Member Center 中取得)，然後按一下「上傳」。

在 Apple 平台上啟用推播通知

  1. 在 Xcode 中按一下專案，然後從「編輯器區域」選取「一般」分頁。
  2. 捲動至「Linked Frameworks and Libraries」，然後按一下「+」按鈕新增架構。
  3. 在顯示的視窗中，捲動至「UserNotifications.framework」，點選該項目，然後按一下「Add」。
  4. 在 Xcode 中按一下專案，然後從「編輯器區域」選取「功能」分頁標籤。
  5. 將「推播通知」切換為「開啟」。
  6. 捲動至「背景模式」，然後切換為「開啟」。
  7. 選取「Background Modes」下方的「Remote notifications」核取方塊。

初始化 Firebase Cloud Messaging

新增 TokenReceived 或 MessageReceived 事件的處理常式時，系統會初始化 Firebase 雲端訊息程式庫。

初始化時，系統會為用戶端應用程式例項要求註冊權杖。應用程式會透過 OnTokenReceived 事件接收權杖，並應快取權杖以供日後使用。如要指定這部裝置接收訊息，您需要這個權杖。

此外，如要接收訊息，您必須註冊 OnMessageReceived 事件。

設定畫面如下所示：

public void Start() {
  Firebase.Messaging.FirebaseMessaging.TokenReceived += OnTokenReceived;
  Firebase.Messaging.FirebaseMessaging.MessageReceived += OnMessageReceived;
}

public void OnTokenReceived(object sender, Firebase.Messaging.TokenReceivedEventArgs token) {
  UnityEngine.Debug.Log("Received Registration Token: " + token.Token);
}

public void OnMessageReceived(object sender, Firebase.Messaging.MessageReceivedEventArgs e) {
  UnityEngine.Debug.Log("Received a new message from: " + e.Message.From);
}

設定 Android 平台

請按照下列操作說明，使用 Unity 和 Android 平台設定 FCM。

設定 Android 進入點 Activity

Firebase Cloud Messaging 會與自訂進入點活動一併封裝，取代預設的 UnityPlayerActivity。如果您未使用自訂進入點，系統會自動進行這項替換作業，您不必採取任何額外行動。

Android 版 Firebase Cloud Messaging Unity 外掛程式隨附兩個額外檔案：

  • Assets/Plugins/Android/libmessaging_unity_player_activity.jar 包含名為 MessagingUnityPlayerActivity 的活動，可取代標準的 UnityPlayerActivity。
  • Assets/Plugins/Android/AndroidManifest.xml 會指示應用程式使用 MessagingUnityPlayerActivity 做為應用程式的進入點。

提供這些檔案的原因是，預設的 UnityPlayerActivity 不會處理 onStop、onRestart 活動生命週期轉換，也不會實作 onNewIntent，而 Firebase Cloud Messaging 必須實作 onNewIntent 才能正確處理傳入的訊息。

設定自訂進入點活動

如果您的應用程式未使用預設的 UnityPlayerActivity，請移除提供的 AndroidManifest.xml，並確保自訂活動能正確處理 Android Activity Lifecycle 的所有轉換 (下方會顯示如何執行的範例)。如果自訂活動會擴充 UnityPlayerActivity，您可以改為擴充 com.google.firebase.MessagingUnityPlayerActivity，其中會實作所有必要方法。

如果您使用自訂 Activity，且未擴充 com.google.firebase.MessagingUnityPlayerActivity，則應在 Activity 中加入下列程式碼片段。

/**
 * Workaround for when a message is sent containing both a Data and Notification payload.
 *
 * When the app is in the background, if a message with both a data and notification payload is
 * received the data payload is stored on the Intent passed to onNewIntent. By default, that
 * intent does not get set as the Intent that started the app, so when the app comes back online
 * it doesn't see a new FCM message to respond to. As a workaround, we override onNewIntent so
 * that it sends the intent to the MessageForwardingService which forwards the message to the
 * FirebaseMessagingService which in turn sends the message to the application.
 */
@Override
protected void onNewIntent(Intent intent) {
  Intent message = new Intent(this, MessageForwardingService.class);
  message.setAction(MessageForwardingService.ACTION_REMOTE_INTENT);
  message.putExtras(intent);
  message.setData(intent.getData());
  // For earlier versions of Firebase C++ SDK (< 7.1.0), use `startService`.
  // startService(message);
  MessageForwardingService.enqueueWork(this, message);
}

/**
 * Dispose of the mUnityPlayer when restarting the app.
 *
 * This makes sure that when the app starts up again it does not start with stale data.
 */
@Override
protected void onCreate(Bundle savedInstanceState) {
  if (mUnityPlayer != null) {
    mUnityPlayer.quit();
    mUnityPlayer = null;
  }
  super.onCreate(savedInstanceState);
}

新版 Firebase C++ SDK (7.1.0 以上版本) 使用 JobIntentService，因此需要對 AndroidManifest.xml 檔案進行額外修改。

<service android:name="com.google.firebase.messaging.MessageForwardingService"
     android:permission="android.permission.BIND_JOB_SERVICE"
     android:exported="false" >
</service>

Android 裝置上的訊息傳送

如果應用程式完全沒有執行，且使用者輕觸通知，根據預設，訊息不會透過 FCM 的內建回呼路徑傳送。在這種情況下，系統會透過Intent接收訊息酬載，並用於啟動應用程式。

應用程式在背景執行時收到的訊息，會使用通知欄位的內容填入系統匣通知，但該通知內容不會傳送至 FCM。這表示 FirebaseMessage.Notification 會是空值。

簡單來說：

應用程式狀態 通知 資料 兩者並用
前景 Firebase.Messaging.FirebaseMessaging.MessageReceived Firebase.Messaging.FirebaseMessaging.MessageReceived Firebase.Messaging.FirebaseMessaging.MessageReceived
背景 系統匣 Firebase.Messaging.FirebaseMessaging.MessageReceived 通知：系統匣
資料：意圖的額外內容。

FCM 允許傳送含有應用程式深層連結的訊息。如要接收含有深層連結的訊息，您必須在處理應用程式深層連結的活動中新增意圖篩選器。意圖篩選器應擷取網域的深層連結。在 AndroidManifest.xml 中：

<intent-filter>
  <action android:name="android.intent.action.VIEW"/>
  <category android:name="android.intent.category.DEFAULT"/>
  <category android:name="android.intent.category.BROWSABLE"/>
  <data android:host="CHANGE_THIS_DOMAIN.example.com" android:scheme="http"/>
  <data android:host="CHANGE_THIS_DOMAIN.example.com" android:scheme="https"/>
</intent-filter>

您也可以指定萬用字元，讓意圖篩選器更具彈性。例如：

<intent-filter>
  <action android:name="android.intent.action.VIEW"/>
  <category android:name="android.intent.category.DEFAULT"/>
  <category android:name="android.intent.category.BROWSABLE"/>
  <data android:host="*.example.com" android:scheme="http"/>
  <data android:host="*.example.com" android:scheme="https"/>
</intent-filter>

使用者輕觸含有您指定配置和主機連結的通知時，應用程式會啟動含有這個意圖篩選器的活動，以處理該連結。

防止自動初始化

FCM 會產生裝置指定目標的註冊權杖。 產生權杖後，程式庫會將 ID 和設定資料上傳至 Firebase。如要在使用權杖前取得明確的同意聲明，您可以在設定時停用 FCM (以及 Android 上的 Analytics)，防止系統產生權杖。您可以在 Apple 上的 Info.plist (而非 GoogleService-Info.plist) 或 Android 上的 AndroidManifest.xml 新增中繼資料值：

Android

<?xml version="1.0" encoding="utf-8"?>
<application>
  <meta-data android:name="firebase_messaging_auto_init_enabled"
             android:value="false" />
  <meta-data android:name="firebase_analytics_collection_enabled"
             android:value="false" />
</application>

Swift

FirebaseMessagingAutoInitEnabled = NO

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

Firebase.Messaging.FirebaseMessaging.TokenRegistrationOnInitEnabled = true;

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

後續步驟

完成設定步驟後，您可以透過下列幾種方式繼續使用 Unity 適用的 FCM：