将 Firebase 添加到您的 Unity 项目

将 Firebase 添加到您的 Unity 项目

利用我们的 Firebase Unity SDK 为您的 Unity 游戏注入强劲动力。

为了说明将 Firebase 添加至您的 Unity 项目中有多么容易，我们开发了一款示例游戏《MechaHamster》，您可以从 GitHub、App Store 和 Google Play 商店下载这款游戏。

MechaHamster (GitHub)

MechaHamster (App Store)

MechaHamster（Play 商店）

如需详细了解如何使用 Firebase 为您的游戏注入强劲动力，请访问我们的 Firebase 游戏页面。

您可以了解 Firebase Unity SDK 支持哪些 Firebase 产品。

第 1 步：设置环境

• 安装 Unity 5.3 或更高版本。

• （仅限 iOS）确保您已具备：

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

• 确保您的 Unity 项目以适当的操作系统级别为目标：

  • 对于 iOS - 目标为 iOS 8 或更高版本
  • 对于 Android - 目标为 API 级别 16 (Jelly Bean) 或更高版本

• 设置可用于运行 Unity 项目的设备或模拟器。

  • 对于 iOS - 为了支持 Firebase 云消息传递，您需要：

    • 一台 iOS 真机
    • 已启用推送通知功能的 APNs 证书

  • 对于 Android - 模拟器必须使用具有 Google Play 的模拟器映像。

• 使用您的 Google 帐号登录 Firebase。

如果您还没有 Unity 项目，并且只是想试用某项 Firebase 产品，则可以下载我们的快速入门示例。

第 2 步：创建 Firebase 项目

您必须创建一个 Firebase 项目以关联到您的 Unity 项目，然后才能将 Firebase 添加到该 Unity 项目。访问了解 Firebase 项目以详细了解 Firebase 项目。

创建 Firebase 项目

1. 在 Firebase 控制台中，点击添加项目，然后选择或输入项目名称。

   如果您已经拥有一个 Google Cloud Platform (GCP) 项目，则可以从项目名称下拉菜单中选择该项目。否则，请输入新的项目名称。

2. （可选）修改项目 ID。

   Firebase 会自动为您的 Firebase 项目分配一个唯一 ID。访问了解 Firebase 项目以了解 Firebase 如何使用该项目 ID。

   Firebase 为您的 Firebase 项目预配好资源后，您就无法再更改项目 ID。
   因此，若要使用特定标识符，您必须在此设置步骤修改项目 ID。

3. 在 Firebase 控制台中完成剩下的设置步骤，然后点击创建项目（如果您使用的是现有 Google 项目，则点击添加 Firebase）。

Firebase 会自动为您的 Firebase 项目预配资源。完成此过程后，您将进入 Firebase 控制台中 Firebase 项目的概览页面。

第 3 步：在 Firebase 中注册您的应用

您可以注册一个或多个应用或游戏，以便将其与 Firebase 项目关联。

如果您要在 iOS 和 Android 两个系统上发布游戏，请在同一个 Firebase 项目中注册 Unity 项目的这两个构建目标。如果您有多个指定了不同 iOS 软件包 ID 或 Android 应用 ID 的构建版本，则必须在同一个 Firebase 项目中注册每个应用版本。

1. 在 Firebase 控制台的项目概览页面的中心位置，点击 Unity 图标以启动设置工作流。

   如果您已向 Firebase 项目添加了应用，请点击添加应用以显示平台选项。

2. 选择您要注册的 Unity 项目的构建目标，甚至可以选择同时注册两个目标。

   注意：您现在可以注册 iOS 和 Android 构建目标了（可同时注册！）。或者，如果需要，您现在可以先注册 Unity 项目的一个构建目标，之后再返回到此设置工作流，以注册另一个构建目标。

3. 输入 Unity 项目针对具体平台的 ID。

   1. 在 Unity IDE 中打开您的 Unity 项目。

   2. 依次转到 Build Settings > iOS 或 Android > Player Settings > Other Settings。

      Unity 项目的 ID 是软件包标识符的值。（ID 示例：com.yourcompany.unity-project-name）

   3. 在相应字段中输入每个针对具体平台的 ID：

      • 对于 iOS - 在 iOS 软件包 ID 字段中输入您的 Unity 项目的 iOS ID。

      • 对于 Android - 在 Android 软件包名称字段中输入您的 Unity 项目的 Android ID。

        • 术语“软件包名称”和“应用 ID”通常可互换使用。

4. （可选）输入 Unity 项目针对具体平台的别名。

   这些别名是方便内部使用的标识符，只有您能在 Firebase 控制台中看到。

5. 点击注册应用。

第 4 步：添加 Firebase 配置文件

1. 在 Firebase 控制台设置工作流中，获取针对具体平台的 Firebase 配置文件。

   如果您要同时注册 Unity 项目的 iOS 和 Android 构建目标，则需要为两个平台都下载并添加配置文件。

   • 对于 iOS - 点击下载 GoogleService-Info.plist。

     • 您可以随时再次下载 Firebase iOS 配置文件。

   • 对于 Android - 点击下载 google-services.json。

     • 您可以随时再次下载 Firebase Android 配置文件。
     注意：该 Firebase 配置文件包含项目的唯一、非机密标识符。
     访问了解 Firebase 项目以详细了解此配置文件。

2. 打开 Unity 项目的 Project 窗口，然后将已下载的配置文件移动到 Assets 文件夹中。

   您可以将 Firebase 配置文件保存在 Assets 文件夹中的任意位置。

3. 返回 Firebase 控制台，在设置工作流中，点击下一步。

第 5 步：添加 Firebase Unity SDK

本部分中的步骤举例说明如何将受支持的 Firebase 产品添加到 Unity 项目。在此示例中，我们将演示如何添加 Google Analytics for Firebase。

注意：将 Google Analytics for Firebase 添加到 Unity 项目为可选操作，但若要验证 Firebase 与 Unity 项目能否正常配合使用，则这是一种相对简单的方法。此外，Analytics 在开发和调试过程中会非常有用，并且可帮助您跟踪生产游戏的表现。

1. 在 Firebase 控制台中，点击下载 Firebase Unity SDK，然后将此 SDK 解压缩到方便的位置。

   • 您可以随时再次下载 Firebase Unity SDK。

   • Firebase Unity SDK 不专用于特定平台。

2. 在您打开的 Unity 项目中，依次转到 Assets > Import Package > Custom Package。

3. 从解压缩后的 SDK 中，选择导入 Analytics SDK (FirebaseAnalytics.unitypackage)。

   您也可以导入其他任何受支持的 Firebase 产品。

   Unity 5.x 及更早版本使用 .NET 3.x 框架，因此请导入 dotnet3/FirebaseAnalytics.unitypackage。

   Unity 2017.x 及更高版本支持 .NET 4.x 框架。如果您的 Unity 项目使用 .NET 4.x，请导入 dotnet4/FirebaseAnalytics.unitypackage。

4. 在“Import Unity Package”窗口中，点击 Import。

5. 返回 Firebase 控制台，在设置工作流中，点击下一步。

   重要提示：使用 iOS 版 Firebase Unity SDK 时，请勿停用方法调配。SDK 需要调配，如果您禁止调配，关键的 Firebase 功能（如 FCM 令牌处理）将无法正常运行。

第 6 步：确认 Google Play 服务版本要求

Android 版 Firebase Unity SDK 需要使用 Google Play 服务。您必须先将 Google Play 服务更新为最新版本，然后才能使用该 SDK。

您应在应用开头处添加以下代码，以便检查 Google Play 服务版本是否符合 Firebase Unity SDK 的要求，并视情况将其更新为相应版本，然后再调用 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。

已知问题

启动时 iOS 可能会崩溃

一些开发者在 iOS 上初始化 Firebase 时（涉及 +[FIRApp firebaseUserAgent]）遭遇崩溃。

要在 Unity SDK 中解决此问题，您可以更新所用 iOS SDK 的版本。为此，请修改 Assets > Firebase > Editor > *Dependencies.xml，将 iosPod 的相关 Firebase 的版本更改为“5.20.0”。

如需了解详情，请参阅该 GitHub 问题。

使用 Unity 2017.x 及更高版本时的 .NET 兼容性

在 Unity 2017 及更高版本中，Firebase 对 .NET 4.x 的支持是作为一个实验性构建选项提供的。Firebase 插件使用 Parse SDK 的组件来在更早版本的 .NET 中提供某些 .NET 4.x 类。

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

如果导入与项目中启用的 .NET 版本不兼容的 Firebase 插件，您会发现 .NET 框架中由 Parse SDK 实现的某些类型存在编译错误。

要在使用 .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 项目中，依次转到 Assets > Play Services Resolver > Version Handler > Update，以便为您的项目启用正确的 DLL。

.NET 4.x 项目中的 Unity 2017.1 IL2CPP 编译

在 Unity 2017 及更高版本中，Firebase 对 .NET 4.x 的支持是作为一个实验性构建选项提供的。Firebase 插件使用 Parse SDK 的组件来在更早版本的 .NET 中提供某些 .NET 4.x 类。

因此，Firebase Unity SDK 5.4.0 及更高版本提供了类型转发 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 编译的项目中使用 .NET 4.x。

Unity 2017.2 网络

Firebase 实时数据库通过 .NET 网络堆栈创建 TLS 网络连接。使用 .NET 4.6 时，Unity 2017.2 中的 TLS 功能会受到影响，从而导致实时数据库插件无法在编辑器和桌面上运行。

此问题没有解决方法，因此您必须使用其他版本的 Unity，例如版本 2017.1 或 2017.3。

设置桌面工作流（测试版）

注意：Firebase Unity SDK 桌面支持是一项测试版功能。此功能仅适用于游戏开发过程中的工作流，而不适用于公开发布的代码。

当您创建游戏时，建议在开发时先在 Unity 编辑器中和桌面平台上测试您的游戏，然后再在移动设备上进行部署和测试，因为这样往往更轻松。为了支持这种工作流，我们提供了可在 Windows、OS X、Linux 上以及 Unity 编辑器中运行的一部分 Firebase Unity SDK。

1. 按照与移动平台相同的说明设置桌面平台 Unity 项目（从上面的在 Firebase 中注册 Unity 项目那一步开始）。

2. 在 Unity IDE 中运行您的 Unity 项目，或选择构建桌面平台的 Unity 项目。

   注意：Firebase 会找到您添加到 Unity 项目的移动 Firebase 配置文件（GoogleService-Info.plist 或 google-services.json）。然后，Firebase 会基于移动平台配置文件自动生成桌面平台 Firebase 配置文件 (google-services-desktop.json)。
   此桌面平台配置文件包含您在 Firebase 控制台设置工作流中输入的 Unity 项目 ID。此文件将您的应用与 Firebase 项目关联。

3. （可选）在编辑模式下运行 Unity 项目。

   Firebase Unity SDK 也可以在 Unity 的编辑模式下运行，因此可供在编辑器插件中使用。

   1. 创建供编辑器使用的 FirebaseApp 时，请勿使用默认实例。

   2. 请改为在进行 FirebaseApp.Create() 调用时提供一个独一无二的名称。

      这一点很重要，因为这样可避免 Unity IDE 使用的实例与 Unity 项目使用的实例之间发生选项冲突。

受支持的 Firebase 产品

要详细了解 Unity Firebase 库，请查看参考文档。

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

Firebase 产品	Unity 软件包
AdMob	在 AdMob Unity 插件中单独分发
Analytics	FirebaseAnalytics.unitypackage
身份验证	FirebaseAuth.unitypackage
Cloud Functions	FirebaseFunctions.unitypackage
云消息传递	FirebaseMessaging.unitypackage
Cloud Storage	FirebaseStorage.unitypackage
Crashlytics	FirebaseCrashlytics.unitypackage
动态链接	FirebaseDynamicLinks.unitypackage
实时数据库	FirebaseDatabase.unitypackage
远程配置	FirebaseRemoteConfig.unitypackage

受支持的 Firebase 产品（桌面设备）

Firebase Unity SDK 的一部分产品提供桌面工作流支持，让您可以在 Unity 编辑器中以及 Windows、OS X 和 Linux 的独立桌面版本中使用 Firebase 的某些部分。

注意：Firebase Unity SDK 桌面支持是一项测试版功能。此功能仅适用于游戏开发过程中的工作流，而不适用于公开发布的代码。

Firebase 产品（桌面设备）	Unity 软件包
身份验证	FirebaseAuth.unitypackage
Cloud Functions	FirebaseFunctions.unitypackage
Cloud Storage	FirebaseStorage.unitypackage
实时数据库	FirebaseDatabase.unitypackage
远程配置	FirebaseRemoteConfig.unitypackage

Firebase 以 Stub（非函数）实现提供其余的桌面库，以方便您针对 Windows、OS X 和 Linux 进行构建。这样一来，您就不必在将桌面平台作为目标时专门编译代码。

支持

Firebase 支持