開始在 Unity 應用程式中使用 Firebase 雲端通訊

本指南說明如何在 Unity 用戶端應用程式中開始使用 Firebase Cloud Messaging，以便可靠地傳送訊息。

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

事前準備

必要條件

• 安裝 Unity 2021 LTS 以上版本。較舊版本可能也相容，但不會主動支援。

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

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

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

  • iOS 裝置：指定 iOS 15 以上版本
  • tvOS：指定 tvOS 15 以上版本
  • Android：以 API 級別 24 (Nougat) 以上版本為目標

• 設定裝置或使用模擬器執行 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」圖示 (plat_unity) 啟動設定工作流程。

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

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

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

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

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

   在哪裡可以找到 Unity 專案的 ID？

   在 Unity IDE 中開啟 Unity 專案，然後前往各平台的設定部分：

   • iOS：依序前往「Build Settings」>「iOS」。

   • Android：依序前往「Android」>「Player Settings」>「Other Settings」。

   Unity 專案的 ID 是套件組合 ID 值 (ID 範例：com.yourcompany.yourproject)。

5. (選用) 輸入 Unity 專案的平台專屬暱稱。
   這些暱稱是內部使用的便利 ID，只有您可以在 Firebase 控制台中查看。

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

步驟 3：新增 Firebase 設定檔

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

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

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

   這個設定檔有哪些注意事項？

   • Firebase 設定檔包含專案和應用程式的非祕密專屬 ID。如要進一步瞭解這個設定檔，請參閱「瞭解 Firebase 專案」。

   • 您隨時可以再次下載 Firebase 設定檔。

   • 請確定設定檔名稱未附加額外的字元，例如 (2)。

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

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

步驟 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 服務版本需求

Firebase Unity SDK for Android 中的部分產品需要 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 Developer Member Center 建立。

1. 在 Firebase 控制台中，依序前往「settings Settings」(設定) >「General」(一般)。接著，按一下「Cloud Messaging」(雲端通訊) 分頁標籤。
2. 在「iOS app configuration」(iOS 應用程式設定) 下方的「APNs authentication key」(APN 驗證金鑰) 中，按一下「Upload」(上傳)，上傳開發驗證金鑰和/或正式版驗證金鑰。至少擇一提供。
3. 瀏覽至金鑰的儲存位置，選取金鑰，然後按一下「開啟」。新增金鑰的 ID (可在 Apple Developer Member Center 中取得)，然後按一下「上傳」。

在 Apple 平台啟用推播通知

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

初始化 Firebase Cloud Messaging

使用 Firebase 安裝 ID 啟用註冊

如要使用 Firebase 安裝 ID (FID) 啟用應用程式例項向 Firebase Cloud Messaging 註冊的功能，請先在 Android 和 Apple 平台的應用程式設定中啟用 FID：

<meta-data android:name="firebase_messaging_installation_id_enabled"
           android:value="true" />

FirebaseMessagingInstallationIdEnabled = YES

註冊 FCM 事件

為 RegistrationReceived 或 MessageReceived 事件新增處理常式時，系統會初始化 Firebase Cloud Messaging 程式庫。

初始化時，Firebase Cloud Messaging 會使用 Firebase 安裝 ID (FID) 註冊用戶端應用程式執行個體，以便接收訊息。應用程式會透過 RegistrationReceived 事件接收 FID，您應將 FID 緩存在伺服器上，以便針對這個特定裝置傳送訊息。

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

設定畫面如下所示：

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

public void OnRegistrationReceived(
    object sender,
    Firebase.Messaging.RegistrationReceivedEventArgs e) {
  UnityEngine.Debug.Log("Received Firebase Installation ID: " +
                        e.InstallationId);
  // TODO: Send the Firebase Installation ID (FID) to your app server to target
  // this device for messages.
}

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

取得 Firebase 安裝 ID 後，請將其傳送至應用程式伺服器，並使用偏好的方法儲存。

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

您也可以在執行階段使用 RegisterAsync() 手動觸發 FCM 註冊：

// Manually register with FCM
Firebase.Messaging.FirebaseMessaging.RegisterAsync().ContinueWith(task => {
  if (task.IsCompleted) {
    // Note: The registered Installation ID is delivered to the
    // RegistrationReceived event handler.
    UnityEngine.Debug.Log("Registered with FCM");
  }
});

存取 FCM 註冊權杖 (已淘汰)

如果應用程式仍使用已淘汰的權杖 API，可以監聽 TokenReceived：

// Deprecated: Use RegistrationReceived instead
public void Start() {
  Firebase.Messaging.FirebaseMessaging.TokenReceived += OnTokenReceived;
}

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

設定 Android 平台

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

設定 Android 進入點活動

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 正確處理收到的訊息所必需的。

設定自訂進入點 Activity

如果應用程式未使用預設的 UnityPlayerActivity，您必須移除提供的 AndroidManifest.xml，並確保自訂活動能妥善處理 Android 活動生命週期的所有轉換 (以下提供範例)。如果自訂活動擴充 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 將為空值。

簡單來說：

在 Android 上處理含有深層連結的訊息

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 中新增中繼資料值：

<?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>

FirebaseMessagingAutoInitEnabled = NO

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

Firebase.Messaging.FirebaseMessaging.RegistrationOnInitEnabled = true;

設定後，即使重新啟動應用程式，這個值仍會保留。

後續步驟

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

• 傳送訊息至裝置
• 在 Unity 用戶端接收訊息
• 傳送主題訊息