将 Firebase 添加到您的 C++ 项目

Firebase C++ SDK 提供了以 Firebase SDK 为基础的 C++ 接口，可为您的 C++ 游戏提供强力支持。

您只需使用 C++ 代码就能访问 Firebase，无需编写任何平台原生代码。该 Firebase SDK 还将 Firebase 使用的许多编程语言所特有的习语转译为 C++ 开发人员更为熟悉的接口。

如需详细了解如何使用 Firebase 为您的游戏提供强力支持，请访问我们的 Firebase 游戏页面。

已将 Firebase 添加到您的 C++ 项目中？确保您使用的是最新版 Firebase C++ SDK。


前提条件

  • 安装您的首选编辑器或 IDE，例如 Android Studio、IntelliJ 或 VS Code。

  • 获取 Android SDK。

  • 确保您的项目满足以下要求：

    • 目标 API 级别为 21 (Lollipop) 或更高

    • 使用 Gradle 并配置了 CMake

  • 设置一台实体设备或使用模拟器运行您的应用。

    • 模拟器必须使用 Google Play 提供的模拟器映像。

    • 对于某些 C++ 库，客户端设备上必须安装 Google Play 服务；请查看本页中的列表。

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

第 2 步：创建 Firebase 项目

您需要先创建一个要关联到 C++ 项目的 Firebase 项目，然后才能将 Firebase 添加到 C++ 项目。请访问了解 Firebase 项目以了解详情。

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

如需在 Android 应用中使用 Firebase，您需要向 Firebase 项目注册您的应用。注册应用的过程通常称为将应用“添加”到项目中。

  1. 前往 Firebase 控制台。

  2. 在项目概览页面的中心位置，点击 Android 图标 () 或添加应用，启动设置工作流。

  3. 在 Android 软件包名称字段中输入应用的软件包名称。

  4. （可选）输入应用别名；这是用于内部的便捷标识符，仅您可在 Firebase 控制台中看到。

  5. 点击注册应用。

第 4 步：添加 Firebase 配置文件

  1. 点击下载 google-services.json 以获取 Firebase Android 配置文件。

  2. 在 IDE 中打开您的 C++ 项目，然后将配置文件添加到您的项目中：

  3. （仅限 Gradle build）如需在 C++ 项目中启用 Firebase 服务，请将 google-services 插件添加到顶级 build.gradle 文件中。

    1. 添加规则以包含 Google 服务 Gradle 插件。此外，请确认您拥有 Google 的 Maven 代码库。

        buildscript {

    repositories {
      // Check that you have the following line (if not, add it):
      google()  // Google's Maven repository
    }

    dependencies {
      // ...

      // Add the following lines:
      classpath 'com.google.gms:google-services:4.4.4'  // Google Services plugin
      implementation 'com.google.android.gms:18.9.0'
    }
  }

  allprojects {
    // ...

    repositories {
      // Check that you have the following line (if not, add it):
      google()  // Google's Maven repository
      // ...
    }
  }

    2. 应用 Google 服务 Gradle 插件：

        apply plugin: 'com.android.application'
  // Add the following line:
  apply plugin: 'com.google.gms.google-services'  // Google Services plugin

  android {
    // ...
  }

  4. 您已完成在 Firebase 控制台中的设置任务。请继续执行下面的添加 Firebase C++ SDK 步骤。

第 5 步：添加 Firebase C++ SDK

本部分中的步骤说明了如何将受支持的 Firebase 产品添加到 Firebase C++ 项目。

  1. 下载 Firebase C++ SDK，然后将此 SDK 解压缩到合适的位置。

    Firebase C++ SDK 并不局限于特定平台，但包含平台专用库。

  2. 在项目的 gradle.properties 文件中，指定解压缩的 SDK 的位置：

    systemProp.firebase_cpp_sdk.dir=full-path-to-SDK

  3. 在项目的 settings.gradle 文件中，添加以下内容：

    def firebase_cpp_sdk_dir = System.getProperty('firebase_cpp_sdk.dir')

gradle.ext.firebase_cpp_sdk_dir = "$firebase_cpp_sdk_dir"
includeBuild "$firebase_cpp_sdk_dir"

  4. 在您的模块（应用级）Gradle 文件（通常是 app/build.gradle）中添加以下内容。
    添加要在应用中使用的 Firebase 产品的库依赖项。

    已启用 Analytics

    android.defaultConfig.externalNativeBuild.cmake {
arguments "-DFIREBASE_CPP_SDK_DIR=$gradle.firebase_cpp_sdk_dir"
}

# Add the dependencies for the Firebase products you want to use in your app
# For example, to use Analytics, Firebase Authentication, and Firebase Realtime Database
apply from: "$gradle.firebase_cpp_sdk_dir/Android/firebase_dependencies.gradle"
firebaseCpp.dependencies {
  analytics
  auth
  database
}

    未启用 Analytics

    android.defaultConfig.externalNativeBuild.cmake {
arguments "-DFIREBASE_CPP_SDK_DIR=$gradle.firebase_cpp_sdk_dir"
}

# Add the dependencies for the Firebase products you want to use in your app
# For example, to use Firebase Authentication and Firebase Realtime Database
apply from: "$gradle.firebase_cpp_sdk_dir/Android/firebase_dependencies.gradle"
firebaseCpp.dependencies {
  auth
  database
}

  5. 在项目的 CMakeLists.txt 文件中，添加以下内容。
    包括要在应用中使用的 Firebase 产品的库。

    已启用 Analytics

    # Add Firebase libraries to the target using the function from the SDK.
add_subdirectory(${FIREBASE_CPP_SDK_DIR} bin/ EXCLUDE_FROM_ALL)

# The Firebase C++ library `firebase_app` is required,
# and it must always be listed last.

# Add the Firebase SDKs for the products you want to use in your app
# For example, to use Analytics, Firebase Authentication, and Firebase Realtime Database
set(firebase_libs
  firebase_analytics
  firebase_auth
  firebase_database
  firebase_app
)
target_link_libraries(${target_name} "${firebase_libs}")

    未启用 Analytics

    # Add Firebase libraries to the target using the function from the SDK.
add_subdirectory(${FIREBASE_CPP_SDK_DIR} bin/ EXCLUDE_FROM_ALL)

# The Firebase C++ library `firebase_app` is required,
# and it must always be listed last.

# Add the Firebase SDKs for the products you want to use in your app
# For example, to use Firebase Authentication and Firebase Realtime Database
set(firebase_libs
  firebase_auth
  firebase_database
  firebase_app
)
target_link_libraries(${target_name} "${firebase_libs}")

  6. 同步您的应用以确保所有依赖项都具有必要的版本。

  7. 如果您添加了 Analytics，请运行您的应用，向 Firebase 发送您已成功集成 Firebase 的验证信息。如果您没有添加 Analytics，则可以跳过验证步骤。

    您的设备日志将显示 Firebase 验证信息，表明初始化已完成。如果您在具有网络访问权限的模拟器上运行应用，则 Firebase 控制台会通知您应用连接已完成。

大功告成！您的 C++ 应用现已注册，并配置为使用 Firebase 服务。

可用的库

如需详细了解 C++ Firebase 库，请查看参考文档以及 GitHub 上的开源 SDK 版本。

适用于 Android 的库（使用 CMake）

请注意，此设置页面的 Apple 平台 (iOS+) 版本上列出了适用于 Apple 平台的 C++ 库。

Firebase 产品 库引用
（firebaseCpp.dependencies
用于 build.gradle 文件）		 库引用
（firebase_libs
用于 CMakeLists.txt 文件）
AdMob admob firebase_admob
（需要）firebase_analytics
（需要）firebase_app
Analytics analytics firebase_analytics
（需要）firebase_app
App Check appCheck firebase_app_check
（需要）firebase_app
Authentication auth firebase_auth
（需要）firebase_app
Cloud Firestore firestore firebase_firestore
（需要）firebase_auth
（需要）firebase_app
Cloud Functions functions firebase_functions
（需要）firebase_app
Cloud Messaging messaging firebase_messaging
（推荐）firebase_analytics
（需要）firebase_app
Cloud Storage storage firebase_storage
（需要）firebase_app
Dynamic Links dynamicLinks firebase_dynamic_links
（推荐）firebase_analytics
（需要）firebase_app
Realtime Database database firebase_database
（需要）firebase_app
Remote Config remoteConfig firebase_remote_config
（推荐）firebase_analytics
（需要）firebase_app

有关移动设置的其他信息

获取 NDK 崩溃报告

对于使用 Android 原生库的应用，Firebase Crashlytics 支持崩溃报告。如需了解详情，请参阅获取 Android NDK 崩溃报告。

自定义构建系统

Firebase 提供脚本 generate_xml_from_google_services_json.py，可将 google-services.json 转换为您可以包含在项目中的 .xml 资源。此脚本所应用的转换与 Google Play 服务 Gradle 插件在构建 Android 应用时所执行的转换相同。

如果您不使用 Gradle 进行构建（例如，使用 ndk-build、makefiles、Visual Studio 等），可以使用此脚本自动生成 Android 字符串资源。

ProGuard

许多 Android 构建系统都为处于发布模式的版本使用 ProGuard，来压缩应用大小及保护 Java 源代码。

如果使用 ProGuard，则需要在 libs/android/*.pro 中添加与 ProGuard 配置中使用的 Firebase C++ 库相对应的文件。

例如，使用 Gradle 时，如果您使用的是 Google Analytics，则 build.gradle 文件将如下所示：

android {
  // ...
  buildTypes {
    release {
      minifyEnabled true
      proguardFile getDefaultProguardFile('your-project-proguard-config.txt')
      proguardFile file(project.ext.your_local_firebase_sdk_dir + "/libs/android/app.pro")
      proguardFile file(project.ext.your_local_firebase_sdk_dir + "/libs/android/analytics.pro")
      // ...  and so on, for each Firebase C++ library that you're using
    }
  }
}

Google Play 服务要求

大多数 Firebase C++ 库需要在客户端的 Android 设备上安装 Google Play 服务。如果 Firebase C++ 库在初始化时返回 kInitResultFailedMissingDependency，则表明 Google Play 服务在客户端设备上不可用（即表示其需要更新、重新激活、解决权限问题等）。在相关问题在客户端设备上得到解决之前，您无法使用 Firebase 库。

您可以使用 google_play_services/availability.h 中的函数来确定 Google Play 服务在客户端设备上不可用的原因（并尝试修复）。

下表列出了各个受支持的 Firebase 产品是否要求在客户端设备上安装 Google Play 服务。

Firebase C++ 库 客户端设备上是否需要安装 Google Play 服务？
AdMob 不需要（通常情况下）
Analytics 不需要
Authentication 需要
Cloud Firestore 需要
Cloud Functions 需要
Cloud Messaging 需要
Cloud Storage 需要
Dynamic Links 需要
Realtime Database 需要
Remote Config 需要

AdMob 和 Google Play 服务

适用于 Android 的 Google Mobile Ads SDK 的大部分版本都可以在未安装 Google Play 服务的客户端设备上正常工作。但是，如果您使用的是 com.google.android.gms:play-services-ads-lite 依赖项，而非上文列出的标准 com.google.firebase:firebase-ads 依赖项，则必须安装 Google Play 服务。

只有当同时满足以下两个条件时，AdMob 初始化才会返回 kInitResultFailedMissingDependency：

  • Google Play 服务在客户端设备上不可用。
  • 您在使用 com.google.android.gms:play-services-ads-lite。

设置桌面工作流（Beta 版）

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

  1. 对于桌面工作流，您需要完成以下操作：

    1. 为 CMake 配置 C++ 项目。
    2. 创建 Firebase 项目
    3. 在 Firebase 中注册您的应用（iOS 或 Android）
    4. 添加移动平台 Firebase 配置文件

  2. 创建 Firebase 配置文件的桌面版本：

    • 如果您添加了 Android google-services.json 文件 - 当您运行应用时，Firebase 会找到此移动平台文件，然后自动生成桌面平台 Firebase 配置文件 (google-services-desktop.json)。

    • 如果您添加了 iOS GoogleService-Info.plist 文件 - 在运行应用之前，您需要将此移动平台文件转换为桌面平台 Firebase 配置文件。如需转换该文件，请从 GoogleService-Info.plist 文件所在的目录中运行以下命令：

      generate_xml_from_google_services_json.py --plist -i GoogleService-Info.plist

    此桌面平台配置文件包含您在 Firebase 控制台设置工作流中输入的 C++ 项目 ID。访问了解 Firebase 项目以详细了解配置文件。

  3. 将 Firebase SDK 添加到您的 C++ 项目。

    下述步骤示范了如何将受支持的 Firebase 产品添加到 C++ 项目。在本示例中，我们将完成 Firebase Authentication 和 Firebase Realtime Database 添加操作。

    1. 将 FIREBASE_CPP_SDK_DIR 环境变量设置为已解压缩的 Firebase C++ SDK 的位置。

    2. 在项目的 CMakeLists.txt 文件中，添加以下内容，包括您要使用的 Firebase 产品适用的库。例如，使用 Firebase Authentication 和 Firebase Realtime Database：

      # Add Firebase libraries to the target using the function from the SDK.
add_subdirectory(${FIREBASE_CPP_SDK_DIR} bin/ EXCLUDE_FROM_ALL)

# The Firebase C++ library `firebase_app` is required,
# and it must always be listed last.

# Add the Firebase SDKs for the products you want to use in your app
# For example, to use Firebase Authentication and Firebase Realtime Database
set(firebase_libs firebase_auth firebase_database firebase_app)
target_link_libraries(${target_name} "${firebase_libs}")

  4. 运行您的 C++ 应用。

可用的库（桌面平台）

Firebase C++ SDK 为部分功能提供桌面工作流支持，让您可以在 Windows、macOS 和 Linux 上的独立桌面 build 中使用 Firebase 的某些部分。

Firebase 产品 库引用（使用 CMake）
App Check firebase_app_check
（需要）firebase_app
Authentication firebase_auth
（需要）firebase_app
Cloud Firestore firebase_firestore
firebase_auth
firebase_app
Cloud Functions firebase_functions
（需要）firebase_app
Cloud Storage firebase_storage
（需要）firebase_app
Realtime Database firebase_database
（需要）firebase_app
Remote Config firebase_remote_config
（需要）firebase_app

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

Realtime Database 桌面

Realtime Database 桌面 SDK 使用 REST 访问您的数据库，因此您必须在桌面上使用 Query::OrderByChild() 声明您使用的索引，否则监听器会失败。

有关桌面设置的其他信息

Windows 库

对于 Windows，我们根据以下各项提供库版本：

  • Build 平台：32 位 (x86) 与 64 位 (x64) 模式
  • Windows 运行时环境：多线程/MT 与多线程 DLL/MD
  • 目标：发布与调试

请注意，以下库使用 Visual Studio 2015 和 2017 进行了测试。

在 Windows 上构建 C++ 桌面应用时，请将以下 Windows SDK 库关联到您的项目。有关详情，请参阅您的编译器文档。

Firebase C++ 库 Windows SDK 库依赖项
App Check advapi32, ws2_32, crypt32
Authentication advapi32, ws2_32, crypt32
Cloud Firestore advapi32, ws2_32, crypt32, rpcrt4, ole32, shell32
Cloud Functions advapi32, ws2_32, crypt32, rpcrt4, ole32
Cloud Storage advapi32, ws2_32, crypt32
Realtime Database advapi32, ws2_32, crypt32, iphlpapi, psapi, userenv
Remote Config advapi32, ws2_32, crypt32, rpcrt4, ole32

macOS 库

对于 macOS (Darwin)，我们为 64 位 (x86_64) 平台提供了库版本。我们还提供了框架，以方便您参考。

请注意，macOS 库已使用 Xcode 16.2 进行了测试。

在 macOS 上构建 C++ 桌面应用时，请将以下内容关联到您的项目：

  • pthread 系统库
  • CoreFoundation macOS 系统框架
  • Foundation macOS 系统框架
  • Security macOS 系统框架
  • GSS macOS 系统框架
  • Kerberos macOS 系统框架
  • SystemConfiguration macOS 系统框架

有关详情，请参阅您的编译器文档。

Linux 库

对于 Linux，我们为 32 位 (i386) 和 64 位 (x86_64) 平台提供了库版本。

请注意，Linux 库已在 Ubuntu 上使用 GCC 4.8.0、GCC 7.2.0 和 Clang 5.0 进行了测试。

在 Linux 上构建 C++ 桌面应用时，请将 pthread 系统库关联到您的项目。有关详情，请参阅您的编译器文档。如果您使用 GCC 5 或更高版本构建，请定义 -D_GLIBCXX_USE_CXX11_ABI=0。

后续步骤