转到控制台

将 Firebase 添加到您的 Unity 项目plat_iosplat_androidplat_unity

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

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

MechaHamster (GitHub)

MechaHamster (App Store)

MechaHamster(Play 商店)


如需详细了解如何使用 Firebase 为您的游戏注入强劲动力,请访问我们的 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 项目。

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

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

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

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

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

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

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

    2. 依次转到 Build Settings > iOSAndroid > 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 配置文件。

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

    • 在移动配置文件之前,请确保配置文件名未附加其他字符,例如 (2)
    • 您可以将 Firebase 配置文件保存在 Assets 文件夹中的任意位置。
  3. 返回 Firebase 控制台,在设置工作流中,点击下一步

第 5 步:添加 Firebase Unity SDK

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

  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 产品

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

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

第 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。

已知问题

使用 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 的 dotnet3dotnet4 目录中提供与 .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。

设置桌面工作流(测试版

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

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

  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 产品 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 软件包
身份验证 FirebaseAuth.unitypackage
Cloud Functions FirebaseFunctions.unitypackage
Cloud Storage FirebaseStorage.unitypackage
实时数据库 FirebaseDatabase.unitypackage
远程配置 FirebaseRemoteConfig.unitypackage

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

后续步骤