將Firebase添加到您的Unity項目

plat_ios plat_android plat_unity

使用我們的Firebase Unity SDK增強Unity遊戲的功能。

為了展示將Firebase插入Unity項目是多麼容易，我們製作了一個示例遊戲MechaHamster，您可以從GitHub ， App Store和Google Play商店下載該遊戲。

MechaHamster（GitHub）

MechaHamster（App Store）

MechaHamster（Play商店）

在我們的Firebase遊戲頁面上找到有關使用Firebase增強遊戲功能的更多信息。

已經將Firebase添加到您的Unity項目中？確保您使用的是最新版本的Firebase Unity SDK 。

先決條件

• 安裝Unity 2017.4或更高版本。較早的版本也可能兼容，但不會得到積極支持。

• （僅iOS）安裝以下內容：

  • Xcode 9.4.1或更高版本
  • CocoaPods 1.10.0或更高版本

• 確保您的Unity項目滿足以下要求：

  • 對於iOS-針對iOS 10或更高版本
  • 對於Android —以API級別16（Jelly Bean）或更高版本為目標

• 設置物理設備或使用仿真器運行您的應用程序。

  • 對於iOS-設置物理iOS設備或使用iOS模擬器。

    您要使用雲消息傳遞嗎？

    對於iOS上的Cloud Messaging，需要滿足以下先決條件：

    • 設置物理iOS設備。
    • 為您的Apple Developer帳戶獲取Apple Push Notification身份驗證密鑰。
    • 在“應用程序>功能”下的XCode中啟用推送通知。

  • 對於Android設備-模擬器必須在Google Play中使用模擬器圖像。

• 使用您的Google帳戶登錄Firebase 。

如果您還沒有Unity項目，而只想試用Firebase產品，則可以下載我們的快速入門樣本之一。

步驟1 ：建立Firebase專案

在將Firebase添加到Unity項目之前，您需要創建一個Firebase項目以連接到Unity項目。訪問了解Firebase項目以了解有關Firebase項目的更多信息。

第2步：在Firebase中註冊您的應用

您可以註冊一個或多個應用程序或遊戲以與Firebase項目連接。

1. 轉到Firebase控制台。

2. 在項目概述頁面的中心，單擊Unity圖標（ plat_unity ）以啟動設置工作流程。

   如果您已經將應用程序添加到Firebase項目中，請單擊“添加應用程序”以顯示平台選項。

3. 選擇您要註冊的Unity項目的構建目標，或者甚至可以選擇同時註冊兩個目標。

4. 輸入您的Unity項目的特定於平台的ID。

   • 對於iOS-在iOS捆綁包ID字段中輸入Unity項目的iOS ID。

   • 對於Android —在Android包名稱字段中輸入Unity項目的Android ID。
     術語包名稱和應用程序ID通常可以互換使用。

   您在哪裡找到Unity項目的ID？

   在Unity IDE中打開Unity項目，然後導航到每個平台的settings部分：

   • 對於iOS-導航至“構建設置”>“ iOS” 。

   • 對於Android —導航至Android>播放器設置>其他設置。

   Unity項目的ID是捆綁包標識符值（示例ID： com.yourcompany.yourproject ）。

5. （可選）輸入您的Unity項目的特定於平台的暱稱。
   這些暱稱是內部便利標識符，僅在Firebase控制台中對您可見。

6. 點擊註冊應用。

第3步：添加Firebase配置文件

1. 在Firebase控制台設置工作流程中獲取特定於平台的Firebase配置文件。

   • 對於iOS-單擊“下載GoogleService-Info.plist” 。

   • 對於Android —單擊“下載google-services.json” 。

   您需要了解什麼有關此配置文件？

   • Firebase配置文件包含項目的唯一但非秘密的標識符。要了解有關此配置文件的更多信息，請訪問了解Firebase項目。

   • 您可以隨時再次下載Firebase配置文件。

   • 確保配置文件名未附加其他字符，例如(2) 。

2. 打開Unity項目的“項目”窗口，然後將配置文件移到Assets文件夾中。

3. 返回Firebase控制台，在設置工作流程中，單擊“下一步” 。

步驟4 ：添加Firebase Unity SDK

1. 在Firebase控制台中，單擊“下載Firebase Unity SDK” ，然後將SDK解壓縮到方便的位置。

   • 您可以隨時再次下載Firebase Unity SDK 。

   • Firebase Unity SDK並非特定於平台。

2. 在打開的Unity項目中，導航到Assets > Import Package > Custom Package 。

3. 從解壓縮的SDK中，選擇要在應用程序中使用的受支持的Firebase產品。

   啟用分析

   • 為Google Analytics（分析）添加Firebase軟件包： FirebaseAnalytics.unitypackage
   • 添加您要在應用程序中使用的任何其他Firebase產品的軟件包。例如，要使用Firebase身份驗證和Firebase實時數據庫：
     FirebaseAuth.unitypackage和FirebaseDatabase.unitypackage

   尚未啟用分析

   添加您要在應用程序中使用的Firebase產品的軟件包。例如，要使用Firebase身份驗證和Firebase實時數據庫：
   FirebaseAuth.unitypackage和FirebaseDatabase.unitypackage

4. 在“導入Unity軟件包”窗口中，單擊導入。

5. 返回Firebase控制台，在設置工作流程中，單擊“下一步” 。

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

適用於Android的Firebase Unity SDK需要Google Play服務，該服務必須是最新的，然後才能使用該SDK。

在您的應用程序的開始處添加以下代碼。在調用SDK中的任何其他方法之前，您可以檢查Google Play服務並將其更新為Firebase Unity SDK所需的版本（可選）。

Firebase.FirebaseApp.CheckAndFixDependenciesAsync().ContinueWith(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。

已知的問題

使用Unity 2017.x和更高版本時的.NET兼容性

Firebase支持.NET 4.x作為Unity 2017及更高版本中的實驗性構建選項。 Firebase插件使用Parse SDK的組件在.NET的早期版本中提供一些.NET 4.x類。

因此，Firebase Unity SDK 5.4.0及更高版本在Firebase Unity SDK的dotnet3和dotnet4目錄中提供與.NET 3.x或.NET 4.x兼容的插件。

如果您導入的Firebase插件與您的項目中啟用的.NET版本不兼容，您將看到由Parse SDK實現的.NET框架中某些類型的編譯錯誤。

要解決編譯錯誤，如果您使用的是.NET 3.x，請執行以下操作：

1. 為所有平台刪除或禁用以下DLL：
   • Parse/Plugins/dotNet45/Unity.Compat.dll
   • Parse/Plugins/dotNet45/Unity.Tasks.dll
2. 為所有平台啟用以下DLL：
   • Parse/Plugins/Unity.Compat.dll
   • Parse/Plugins/Unity.Tasks.dll

要解決編譯錯誤，如果您使用的是.NET 4.x，請執行以下操作：

1. 為所有平台刪除或禁用以下DLL：
   • Parse/Plugins/Unity.Compat.dll
   • Parse/Plugins/Unity.Tasks.dll
2. 為所有平台啟用以下DLL：
   • Parse/Plugins/dotNet45/Unity.Compat.dll
   • Parse/Plugins/dotNet45/Unity.Tasks.dll

如果您導入另一個Firebase插件：

• 在您的Unity項目中，導航到“資產” >“ Play服務解析器” >“版本處理程序” >“更新”以為您的項目啟用正確的DLL。

NET 4.x項目中的Unity 2017.1 IL2CPP編譯

Firebase支持.NET 4.x作為Unity 2017及更高版本中的實驗性構建選項。 Firebase插件使用Parse SDK的組件在.NET的早期版本中提供一些.NET 4.x類。

因此，Firebase Unity SDK版本5.4.0和更高版本提供了類型轉發DLL，這些DLL將Parse類型（例如， System.Threading.Tasks.Task Parse實現）轉發到.NET框架。不幸的是，Unity 2017.1.x中隨附的IL2CPP（將C＃轉換為C ++的編譯器）無法正確處理類型轉發DLL，這會導致類似於以下內容的生成錯誤：

Fatal error in Unity CIL Linker Mono.Cecil.ResolutionException: Failed to
resolve System.Threading.Tasks.TaskCompletionSource`1<T>

當前在Unity 2017.1中沒有針對.NET 4.x IL2CPP構建錯誤的解決方法，因此您必須升級到Unity 2017.2或更高版本，才能在使用IL2CPP編譯的項目中使用.NET4.x。

Unity 2017.2聯網

Firebase Realtime Database使用.NET網絡堆棧創建TLS網絡連接。使用.NET 4.6時，Unity 2017.2中的TLS功能被破壞，導致Realtime Database插件在編輯器和桌面上失敗。

沒有針對此問題的解決方法，因此您必須使用其他版本的Unity，例如版本2017.1或2017.3。

Unity 2020中缺少Firebase Android配置文件。

為了支持無法自定義Gradle構建的Unity版本，Firebase編輯器工具將Assets/Plugins/Android/Firebase/res/values/google-services.xml成為Android資源，並將其打包為Android構建，以便Firebase SDK可以使用它來初始化默認的FirebaseApp實例。

在Unity 2020中，所有Android資源必須位於帶有.androidlib後綴的目錄中。如果您的項目使用的是可生成Assets/Plugins/Android/Firebase目錄的Firebase SDK，請將其重命名為Assets/Plugins/Android/Firebase.androidlib 。確保它包含AndroidManifest.xml ， project.properties和res/values/google-services.xml 。

構建Android應用程序時單個dex出現問題

在構建Android應用時，您可能會遇到與擁有一個dex文件有關的構建失敗。如果您的項目配置為使用Gradle構建系統，則錯誤消息看起來類似於以下內容。

Cannot fit requested classes in a single dex file.

Dalvik Executable（ .dex ）文件用於保存一組類定義及其與Android應用程序（ .apk ）相關的輔助數據。單個dex文件僅限於引用65,536個方法。如果項目中所有Android庫中方法的總數超過此限制，則構建將失敗。

統一引入微小在2017.2，它使用Proguard的（或其他工具在Unity的一些版本），以汽提出未使用的代碼，從而可以減少在一個單一的DEX文件的引用的方法的總數。該選項可在播放器設置> Android>發佈設置>縮小中找到。不同版本的Unity中的選項可能有所不同，因此請參考正式的Unity文檔。

如果引用的方法數量仍超過限制，則另一個選擇是啟用multidex 。在Unity中有多種方法可以實現此目的：

• 如果啟用了“ Player Settings下的Player Settings Custom Gradle Template Player Settings ，請修改mainTemplate.gradle 。
• 如果您使用Android Studio構建導出的項目，請修改模塊級別的build.gradle文件。

可以在multidex用戶指南中找到更多詳細信息。

設置桌面工作流程（測試版）

在創建遊戲時，通常更容易先在Unity編輯器和台式機平台上測試遊戲，然後在開發中在移動設備上進行部署和測試。為了支持此工作流程，我們提供了Firebase Unity SDK的子集，這些子集可以在Windows，macOS，Linux以及Unity編輯器中運行。

1. 遵循與移動平台相同的說明來設置桌面平台Unity項目（從上面的“使用Firebase註冊應用程序”步驟開始）。

2. 在Unity IDE中運行您的Unity項目，或選擇為桌面構建您的Unity項目。

3. （可選）在“編輯模式”下運行您的Unity項目。

   Firebase Unity SDK也可以在Unity的編輯模式下運行，從而可以在編輯器插件中使用。

   1. 當您創建編輯器使用的FirebaseApp ，請勿使用默認實例。

   2. 而是為FirebaseApp.Create()調用提供唯一的名稱。

      這對於避免Unity IDE使用的實例與Unity項目使用的實例之間的選項衝突很重要。

支持的Firebase產品

在參考文檔中了解有關Unity Firebase庫的更多信息。

Firebase Unity SDK在iOS和Android上支持以下Firebase產品：

支持的Firebase產品（台式機）

Firebase Unity SDK包括對一部分產品的桌面工作流支持，從而使Firebase的某些部分可以在Unity編輯器和Windows，macOS和Linux上的獨立桌面版本中使用。

為了在構建Windows，macOS和Linux時方便使用，Firebase提供了剩餘的桌面庫作為存根（非功能性）實現。因此，您無需有條件地編譯代碼即可將桌面作為目標。

下一步

• 探索示例Firebase應用程序。

• 準備啟動您的應用程序：

  • 在Google Cloud Console中為您的項目設置預算警報。
  • 在Firebase控制台中監控您的使用情況和結算信息中心。
  • 查看Firebase啟動核對錶。