使用 Unity 設定 Firebase 雲端通訊用戶端應用程式

如要使用 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 Developer 帳戶的 Apple 推播通知驗證金鑰。
    • 在 XCode 中依序前往「App」 >「Capabilities」，啟用推播通知。

  • Android 適用：模擬器必須使用含有 Google Play 的模擬器映像檔。

• 使用 Google 帳戶登入 Firebase。

如果您尚未擁有 Unity 專案，但想試用 Firebase 產品，可以下載我們的快速入門範例。

步驟 1：建立 Firebase 專案

您必須先建立 Firebase 專案，才能將 Firebase 新增至 Unity 專案。請參閱「瞭解 Firebase 專案」一文，進一步瞭解 Firebase 專案。

建立 Firebase 專案

1. 在 Firebase 控制台中，按一下「新增專案」。

   • 如要將 Firebase 資源新增至現有 Google Cloud 專案，請輸入專案名稱，或從下拉式選單中選取。

   • 如要建立新專案，請輸入所需的專案名稱。您也可以視需要編輯專案名稱下方顯示的專案 ID。

     Firebase 會根據您指定的名稱，為 Firebase 專案產生專屬 ID。如果您想編輯這個專案 ID，請務必立即執行，因為 Firebase 為專案配置資源後，就無法再變更。請參閱「瞭解 Firebase 專案」，瞭解 Firebase 如何使用專案 ID。

2. 系統提示時，請詳閱並接受 Firebase 條款。

3. 按一下「繼續」。

4. (選用) 為專案設定 Google Analytics，即可在使用下列任何 Firebase 產品時獲得最佳體驗：

   Firebase Crashlytics Firebase Cloud Messaging

   Firebase In-App Messaging Firebase Remote Config

   Remote Config 個人化 Firebase A/B Testing

   選取現有的 Google Analytics 帳戶或建立新帳戶。

   如果您建立新帳戶，請選取Analytics報表位置，然後接受專案的資料共用設定和 Google Analytics 條款。

   您稍後可以前往 「專案設定」分頁的「整合」分頁標籤，設定 Google Analytics。

5. 按一下「建立專案」 (如果您使用的是現有的 Google Cloud 專案，請按一下「新增 Firebase」)。

Firebase 會自動為您的 Firebase 專案佈建資源。程序完成後，您會前往 Firebase 主控台的 Firebase 專案總覽頁面。

步驟 2：透過 Firebase 註冊應用程式

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

如果您打算在 iOS 和 Android 系統中發布遊戲，請透過同一個 Firebase 專案註冊 Unity 專案的兩個版本目標。如果您有多個建構變化版本，且已定義不同的 iOS 套件 ID 或 Android 應用程式 ID，則必須將每個變化版本註冊至同一個 Firebase 專案。

1. 前往 Firebase 控制台。

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

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

3. 選取要註冊的 Unity 專案版本目標，甚至可以選取現在同時註冊兩個目標。

   注意： 如果您現在只註冊 Unity 專案的一個版本目標，之後隨時可以返回設定工作流程，註冊其他版本目標。

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

   • 適用於 iOS：在 iOS 軟體包 ID 欄位中輸入 Unity 專案的 iOS ID。

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

   如何找到 Unity 專案的 ID？

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

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

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

   Unity 專案的 ID 是「Bundle Identifier」值 (ID 範例：com.yourcompany.yourproject)。

   請務必輸入專案實際使用的 ID。ID 值有大小寫之分，且在 Firebase 應用程式註冊至 Firebase 專案後，就無法變更。

5. (選用) 輸入 Unity 專案的平台專屬暱稱。
   這些別名是內部方便使用的 ID，只有您在 Firebase 控制台中才能看到。

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

步驟 3：新增 Firebase 設定檔

1. 在 Firebase 主控台設定工作流程中取得特定平台的 Firebase 設定檔。

   如果您同時註冊 Unity 專案的 iOS 和 Android 版本目標，就必須下載並新增這兩個平台的設定檔。

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

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

   您需要瞭解這個設定檔的哪些資訊？

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

   • 您隨時可以重新下載 Firebase 設定檔。

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

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

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

步驟 4：新增 Firebase Unity SDK

1. 在 Firebase 控制台中，按一下「Download 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 控制台，在設定工作流程中按一下「下一步」。

重要事項： 使用 Firebase Unity SDK for iOS 時，請勿停用方法 swizzling。SDK 需要使用 Swizzling，否則重要的 Firebase 功能 (例如 FCM 權杖處理) 無法正常運作。

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

Firebase Unity SDK for Android 需要 Google Play services，您必須先更新該 SDK 才能使用。

請在應用程式開頭加入下列 using 陳述式和初始化程式碼。您可以先檢查 Google Play services，並視需要更新至 Firebase Unity SDK 所需的版本，再呼叫 SDK 中的任何其他方法。

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。

請參閱將 Firebase 新增至 Unity 專案，瞭解如何：

• 瞭解 Firebase Unity SDK 支援哪些 Firebase 產品。
• 為 Unity 專案設定電腦版工作流程。
• 排解已知問題。

上傳 APNs 驗證金鑰，以便 Apple 支援團隊提供協助

將 APNs 驗證金鑰上傳至 Firebase。如果您尚未取得 APNs 驗證金鑰，請務必前往 Apple Developer Member Center 建立金鑰。

1. 在 Firebase 控制台的專案中，依序選取齒輪圖示、「Project Settings」(專案設定)，然後選取「Cloud Messaging」分頁。

2. 在「iOS 應用程式設定」下方的「APNs 驗證金鑰」中，按一下「上傳」按鈕。

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

在 Apple 平台上啟用推播通知

步驟 1：新增使用者通知架構

1. 在 Xcode 中按一下專案，然後在「編輯器」區域中選取「一般」分頁。

2. 向下捲動至「Linked Frameworks and Libraries」，然後按一下「+」按鈕新增架構。

3. 在隨即顯示的視窗中，捲動至「UserNotifications.framework」，按一下該項目，然後按一下「Add」。

步驟 2：啟用推播通知

1. 按一下 Xcode 中的專案，然後在「編輯器」區域選取「功能」分頁標籤。

2. 將「推播通知」切換為「開啟」。

3. 向下捲動至「背景模式」，然後將其切換為「開啟」。

4. 選取「背景模式」下方的「遠端通知」核取方塊。

初始化 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 進入點活動

在 Android 上，Firebase Cloud Messaging 會隨附自訂的進入點活動，用來取代預設的 UnityPlayerActivity。如果您未使用自訂進入點，系統會自動執行此替換作業，因此您不必採取任何額外行動。如果應用程式未使用預設進入點 Activity，或提供自己的 Assets/Plugins/AndroidManifest.xml，就需要額外設定。

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 正確處理傳入訊息而言，是必要的。

設定自訂進入點活動

如果您的應用程式未使用預設 UnityPlayerActivity，您必須移除提供的 AndroidManifest.xml，並確保自訂活動能正確處理 Android 活動生命週期的所有轉換 (如需瞭解如何執行這項操作，請參閱下方的範例)。如果自訂活動擴充 UnityPlayerActivity，您可以改為擴充 com.google.firebase.MessagingUnityPlayerActivity，後者會實作所有必要的方法。

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

/**
 * 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 older 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 ensures 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 會為裝置指定目標產生註冊權杖。產生權杖時，程式庫會將 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;

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

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

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

後續步驟

設定用戶端應用程式後，您就可以使用 Firebase 傳送下游和主題訊息。如需更多資訊，請參閱快速入門範例，瞭解這項功能。

如要為應用程式新增其他進階行為，請參閱以下指南，瞭解如何透過應用程式伺服器傳送訊息：

• 傳送主題訊息
• 傳送至裝置群組
• 傳送上游訊息

請注意，您需要伺服器實作才能使用這些功能。