在 C 中开始使用 Firebase

1. 概览

在此 Codelab 中，您将学习如何在示例 Android 游戏中集成 C++ Firebase Games SDK，并以 Google Analytics 为例进行说明。您将能够添加所需的功能，集成一些基本的分析逻辑来衡量玩家的进度，并与测试人员分享游戏以获得早期反馈。

演示

如果您想与作者一起完成此 Codelab，请观看以下视频：

学习内容

• 如何将 Firebase 添加到基于 Android CMake 的游戏中。
• 如何确定您需要的 C++ 和 Gradle 依赖项。
• 如何记录 Analytics 事件。
• 如何调试 Analytics 事件。
• 如何通过 App Distribution 分享游戏。

所需条件

• Android Studio
• 示例代码
• 安装了 Google Play 服务的测试设备或模拟器

2. 获取示例代码

从 GitHub 中签出或下载：

git clone https://github.com/FirebaseExtended/cmake-way-for-firebase.git

下载 Firebase SDK

MacOS/Linux：

sh download.sh

Windows（通过 PowerShell）：

./download.ps1

您也可以手动下载 SDK。如果这样做，则必须将 Firebase C++ SDK 提取到 /third_party 中，以便名为 firebase_cpp_sdk 的文件夹包含 Firebase SDK 中的根 CMakeLists.txt。

3. 运行示例游戏

首先，玩一下示例游戏，确保一切正常运行。这是一款简单的跑酷游戏，关卡采用程序化生成，只需一个按钮即可跳跃。

1. 依次选择“File”>“New”>“Import Project”（或从启动画面中选择“Import Project”）
2. 打开代码库中包含的 proj.android/ 文件夹

这是一个 Cocos2dx 项目，而不是典型的 Android 项目。通常情况下，您应该会在该代码库的根目录下看到一个 build.gradle 文件，但该文件位于 proj.android/ 下，因此每个目标操作系统都可以有自己的独立构建流程。

3. [可选] 打开 proj.android/gradle.properties 并微调 PROP_APP_ABI。您可以移除除目标架构之外的所有架构，以缩短 build 时间。PROP_APP_ABI=x86 将仅针对模拟器进行构建，PROP_APP_ABI=armeabi-v7a 将针对大多数手机进行构建
4. 点击“调试”按钮 以构建并运行游戏。构建 Cocos2dx 游戏引擎需要一些时间。

如果您已安装 Cocos2dx CLI，经验丰富的 Cocos2dx 开发者可以选择使用 cocos run -p android。Android 开发者可能更喜欢 ./gradlew installDebug。在本教程中，我将假定您使用 Android Studio 进行开发、构建和部署。

4. Firebase 控制台设置

1. 在 Firebase 控制台中创建一个新项目。
2. 为其指定一个名称，例如“Popsicle Runner”
3. 启用 Google Analytics
4. 添加或创建 Google Analytics 账号
5. 向项目添加新的 Android 应用
6. 添加 com.firebase.popsiclerunner 作为您的软件包名称。

此 Codelab 不需要使用 SHA-1

7. 下载 google-services.json 并将其复制到 proj.android/app

如果您尝试提交 google-services.json，许多源代码托管服务会将其标记为“机密”，但此文件中的任何内容都不是真正的机密（在正式版游戏中，检索此文件的内容非常简单）。如果您打算将此文件提交到公共源代码库，仍应谨慎行事，因为如果此文件公开发布，那么在您编写出色的安全规则之前，其他人将更容易找到您的数据库或 Cloud Storage 存储分区。

8. 忽略有关添加 Firebase SDK 的说明，然后点击“下一步”
9. 当系统要求您验证安装时，您可以点击“跳过此步骤”

5. 将 Firebase 添加到您的游戏

将 Firebase SDK 添加到 CMakeLists.txt

打开根级 CMakeLists.txt。此文件顶部附近应包含以下代码

CMakeLists.txt

cmake_minimum_required(VERSION 3.6)

set(APP_NAME popsiclerunner)

project(${APP_NAME})

并将以下代码行添加到该 CMakeLists.txt 文件的末尾

CMakeLists.txt

add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/third_party/firebase_cpp_sdk)
target_link_libraries(${APP_NAME} firebase_analytics firebase_app)

add_subdirectory 包含 Firebase C++ SDK，并使其可供相应游戏使用

target_link_libraries 将游戏与为 Android 构建的 Firebase C++ 库相关联。

请参阅此表，了解您需要哪些库才能使用各项功能。我就是这样知道 firebase_analytics 需要 firebase_app 的。

添加 Google 服务插件

如需关联 Firebase SDK，您必须将 Google 服务插件添加到 Gradle 构建脚本中。为此，请打开项目级 build.gradle 文件（位于 proj.android 文件夹中）。并将 classpath 'com.google.gms:google-services:4.3.3' 添加为 buildscript 依赖项。

build.gradle

buildscript {
    repositories {
        google()
        jcenter()
    }

    dependencies {
        classpath 'com.android.tools.build:gradle:4.0.1'

        // NOTE: Do not place your application dependencies here; they belong
        // in the individual module build.gradle files
        classpath 'com.google.gms:google-services:4.3.3'  // Google Services plugin
    }
}

然后，将插件添加到模块级 build.gradle 文件（位于 proj.android/app 文件夹中）。在 apply plugin: 'com.android.application' 下添加 apply plugin: 'com.google.gms.google-services'：

build.gradle

apply plugin: 'com.android.application'
apply plugin: 'com.google.gms.google-services'  // Google Services plugin

在 Gradle 中找到 C++ SDK

如需告知 Gradle 在何处查找 Firebase C++ SDK，请将以下行添加到 settings.gradle 文件的底部。

settings.gradle

gradle.ext.firebase_cpp_sdk_dir = "$settingsDir/../third_party/firebase_cpp_sdk/"
includeBuild "$gradle.ext.firebase_cpp_sdk_dir"

此变量必须指向与 CMake 中的 add_subdirectory 调用相同的位置。

添加 Android 依赖项

如需关联 Firebase 的 Android 依赖项，请打开模块级 Gradle 文件 popsicle_runner（位于 proj.android/app/build.gradle 中），并在末尾的常规 dependences { 部分之前添加以下内容：

build.gradle

apply from: "$gradle.firebase_cpp_sdk_dir/Android/firebase_dependencies.gradle"
firebaseCpp.dependencies {
    analytics
}

每个 C++ SDK 都是针对特定版本的 Android SDK 构建的。firebaseCpp.dependencies 是一个便捷函数，可用于发现和配置必要的 Gradle 依赖项，以确保您拥有经过验证的配置。

AndroidX 和 Jetifier

打开 gradle.properties，在末尾添加以下代码，以添加 AndroidX 和 Jetifier 支持：

gradle.properties

android.useAndroidX = true
android.enableJetifier = true

在游戏中初始化 Firebase

打开 Classes/AppDelegate.cpp，在游戏中初始化 Firebase。在顶部添加以下 #include 指令：

AppDelegate.cpp

#include <firebase/app.h>
#include <firebase/analytics.h>

然后添加 App::Create 并初始化所需 Firebase 功能。为此，请找到 AppDelegate::applicationDidFinishLaunching，并在 auto scene = MainMenuScene::createScene() 之前添加以下代码：

AppDelegate.cpp

{
    using namespace firebase;
    auto app = App::Create(JniHelper::getEnv(), JniHelper::getActivity());
    analytics::Initialize(*app);
}

我倾向于使用匿名块 {} 来限制 using 语句（例如 using namespace firebase;）的范围。

如果您调试游戏并刷新 Firebase 控制台，应该会在一分钟左右后看到一个新用户。

6. 添加 Google Analytics

即使在开发初期，分析也是一种有用的工具，可用于衡量 Beta 版测试人员与游戏的互动情况。有些分析数据是自动收集的，例如留存率报告，但添加针对特定游戏量身定制的自定义事件也很有用。

一个不错的起点是在玩家开始挑战关卡时记录一个分析事件。我们可以使用关卡开始事件的数量来了解玩家在会话中重玩游戏的频率。

我们还会记录玩家死亡时的进度。这样一来，我们就能了解所做更改对单次会话时长的影响，并确定玩家是喜欢时长较短但难度较高的游戏，还是时长较长但难度较低的游戏。

添加 Analytics 标头

打开 Classes/PopsicleScene.cpp，在顶部添加 Firebase 标头，以便我们可以进行分析调用。

PopsicleScene.cpp

#include <firebase/analytics.h>
#include <firebase/analytics/event_names.h>

记录 Level Start 事件

如需在 Cocos2dx Director 将此场景分阶段呈现时记录事件，请找到桩函数 PopsicleScene::onEnter()。输入以下代码以在此处记录“关卡开始”事件：

PopsicleScene.cpp

using namespace firebase;
analytics::LogEvent(analytics::kEventLevelStart);

记录“关卡结束”事件

为了了解玩家的表现，我们记录一个“关卡结束”事件，其中包含玩家最终死亡时的闯关进度。为此，请找到 PopsicleScene::gameOver()，然后将以下代码添加到 if(!_gameOver) { 代码块的末尾（在设置 _gameOver = true; 之前）：

PopsicleScene.cpp

{
    using namespace firebase;
    analytics::LogEvent(analytics::kEventLevelEnd, "distance", _lastDistance);
}

kEventLevelEnd 是关卡结束事件。而 "distance" 是“事件参数”。我们在此处添加了上次记录的距离，该距离可以很好地近似表示玩家在死亡前行进的距离。

7. 测试活动

您现在可以点击“调试”图标 ，但任何事件都需要一段时间才能在 Google Analytics 信息中心内报告。这有两个原因：1) 事件会分批上传，大约每小时上传一次，以节省电池电量；2) 报告每 24 小时生成一次。

您可以通过一些机制更快地查看活动。如果某个事件被标记为转化事件，那么在许多情况下，系统都会近乎实时地报告该事件。您还可以将 Google Analytics 配置为导出到 BigQuery，这样日内表的延迟时间仅为 4 小时左右。

启用调试模式

您仍然可以将设备置于调试模式，以调试 Google Analytics 事件。

首先，请确保您已安装并设置 Android 调试桥 (ADB)。输入 adb devices 应该会显示您要测试的设备：

$ adb devices
List of devices attached
emulator-5554   device

然后运行以下 adb shell 命令：

adb shell setprop debug.firebase.analytics.app com.firebase.popsiclerunner

这会告知 Firebase Analytics 立即记录事件，并自动从常规报告中排除这些事件，以避免在测试时污染直播活动。如果您想在日后撤消此操作，只需写入：

adb shell setprop debug.firebase.analytics.app .none.

查看活动

在 Firebase 控制台中打开“DebugView”

点击“调试”图标 ，然后玩游戏。您应该会在游戏中发生新事件后立即看到这些事件。

如果您展开 level_end 事件，还会看到您记录的自定义“distance”参数。

当 level_end 事件最终出现在您的事件报告中时，默认情况下不会获取距离。您需要依次选择“事件”图标 、找到 level_end、展开右侧的三点状图标 ，然后选择修改参数报告，将其添加为事件报告中的参数。完成此操作后，您就可以查看统计数据，例如球员的场均跑动距离。

8. 寻找测试人员

接下来，您需要让其他人看到您的游戏，无论是工作室内部人员、亲密好友还是社区成员。借助 Firebase App Distribution，您可以轻松邀请玩家试玩您的游戏。

构建独立二进制文件

首先，构建一个独立的 APK 以供分享，方法是依次选择“Build”>“Build Bundles(s) / APK(s)”>“Build APK(s)”

如果您之前更改过 ABI 过滤条件，请务必返回到 gradle.properties 并更改 PROP_APP_ABI 以包含您计划测试的任何设备：

PROP_APP_ABI=armeabi-v7a:arm64-v8a:x86

Android Studio 会弹出一个对话框，让您找到构建的文件。如果您错过了，可以点击“活动日志”再次获取该链接。

上传到 Firebase App Distribution

1. 打开 App Distribution，然后点击“开始使用”图标
2. 将 .apk 文件拖放到显示“将任意 .apk 拖到此处以创建新的版本”的框中。
3. 输入您的电子邮件地址作为第一个测试人员。
4. 点击“下一步”。
5. 添加说明，然后点击“分发”

邀请测试人员

您无需手动输入每个电子邮件地址，只需创建邀请链接即可。当您通过此邀请链接捕获用户时，还可以将他们添加到测试人员群组。这样一来，您就可以将内部测试人员与外部测试人员区分开来。

1. 点击“测试人员和群组”图标
2. 创建新群组 ，并为其命名，例如“Android 测试人员”。
3. 点击“邀请链接”图标
4. 点击“新建邀请链接”
5. 从下拉菜单中选择群组。
6. 点击“创建链接”
7. 点击“复制链接”，然后以任意方式分享该链接

9. 恭喜

您已成功为基于 C++ 的游戏添加了分析功能，邀请了一些好友来玩游戏，并且知道如何在基于 CMake 和 Gradle 的构建系统中（在 Android 开发中很常见）查找和关联 Firebase 库。

所学内容

• 如何将 Firebase 添加到基于 Android CMake 的游戏中。
• 如何确定您需要的 C++ 和 Gradle 依赖项。
• 如何记录 Analytics 事件。
• 如何调试 Analytics 事件。
• 如何通过 App Distribution 分享游戏。

后续步骤

• 尝试以匿名方式登录用户，并将其最高得分保存在 Realtime Database 中。
• 在自己的游戏中记录 Analytics 事件。
• 尝试将 Google Analytics 添加到 iOS 游戏中。

了解详情

• 查看游戏专用事件列表，并考虑这些事件如何适用于您自己的游戏。