在 C 中开始使用 Firebase

1. 概览

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

演示

如果您想和作者一起浏览此 Codelab，请观看此视频：

学习内容

• 如何将 Firebase 添加到基于 Android CMake 的游戏中。
• 如何确定所需的 C++ 和 Gradle 依赖项？
• 如何记录 Analytics 事件。
• 如何调试 Google 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. 选择文件 >新建 >导入项目（或从启动画面选择“导入项目”）
2. 打开代码库中包含的 proj.android/ 文件夹

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

3. [可选] 打开 proj.android/gradle.properties，然后确定 PROP_APP_ABI。您可以移除目标架构以外的所有架构，以缩短构建时间。PROP_APP_ABI=x86 将仅针对模拟器进行构建，PROP_APP_ABI=armeabi-v7a 将针对大多数手机进行构建
4. 点击“Debug”按钮 以构建并运行游戏。这将需要一些时间来构建 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 标记为“Secret”如果您尝试提交该文件，但此文件中没有真正的秘密（在运输游戏中，检索该文件的内容是轻而易举的）。如果您打算将文件提交到公开源代码库，则仍需保持谨慎。如果此文件公开发布，在编写严格的安全规则之前，查找数据库或 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 依赖项，请打开 popsicle_runner 的模块级 Gradle 文件（在 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 版测试人员与游戏的互动情况。系统会自动收集一些分析数据（例如留存率报告），但添加针对特定游戏量身定制的自定义事件会很有帮助。

一种比较好的做法是在玩家开始关卡时记录分析事件。我们可以根据关卡开始事件数量来了解玩家在一次会话中重放游戏的频率。

我们还将在玩家死亡时记录一个事件，以及他们已经走了多远。这样，我们就能了解所做的更改如何改变单次会话的时长，进而确定玩家是想要缩短/难度更大的游戏，还是需要更长/更简单的游戏。

添加 Google Analytics 标头

打开 Classes/PopsicleScene.cpp 并将 Firebase 头文件添加到顶部，以便我们进行分析调用。

PopsicleScene.cpp

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

记录关卡开始事件

如需在 Cocos2dx Director 预演此场景时记录事件，请找到存根函数 PopsicleScene::onEnter()。在此处输入以下代码，以在此处记录 Level Start 事件：

PopsicleScene.cpp

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

记录关卡结束事件

为了解玩家的表现，让我们记录一个关卡结束事件，记录玩家最终死亡有多远。为此，请找到 PopsicleScene::gameOver()，并在设置 _gameOver = true; 之前将以下代码添加到 if(!_gameOver) { 代码块的末尾：

PopsicleScene.cpp

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

kEventLevelEnd 是关卡结束事件。而 "distance" 是“事件参数”。我们在此处添加了最后记录的距离，这个距离非常好，能够很好地反映玩家在死亡前走了多远。

7. 测试事件

您现在可以点击“调试”图标 ，但 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.

查看活动

打开“DebugView”在 Firebase 控制台中

点击“Debug”图标 ，然后玩游戏。您应该会在游戏中出现新活动后立即看到相应活动。

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

当 level_end 事件最终进入事件报告后，默认情况下，该事件不会获取距离。您需要依次选择“事件”图标 和“level_end”，展开右侧的三个点 ，然后选择修改参数报告，将其添加为事件报告中的参数。完成上述操作后，你就可以看到你的运动员等统计数据，平均每场比赛距离

8. 查找测试人员

接下来，你就需要关注自己的游戏，无论他们是工作室内部用户、好友还是社区。Firebase App Distribution 是邀请玩家玩游戏的好方法。

构建独立的二进制文件

首先，从“构建”中构建要分享的独立 APKbuild Bundle/APK >构建 APK

如果您之前更改了 ABI 过滤器，请记得返回 gradle.properties 并更改 PROP_APP_ABI，以包含您计划用于测试的所有设备：

PROP_APP_ABI=armeabi-v7a:arm64-v8a:x86

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

上传到 Firebase App Distribution

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

邀请测试人员

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

1. 点击“测试人员和群组"
2. 创建一个新群组 ，并为其命名，例如“Android Testers”。
3. 点击“邀请链接”
4. 点击“新建邀请链接”
5. 从下拉菜单中在此处设置群组。
6. 点击“创建关联”
7. 点击“复制链接”还可以随意分享

9. 恭喜

您已经成功地将分析工具添加到基于 C++ 的游戏，邀请了一些朋友一起玩游戏，还知道如何在 Android 开发中常用的基于 CMake 和 Gradle 的构建系统中查找和关联 Firebase 库。

所学内容

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

后续步骤

• 尝试让用户匿名登录并在 Realtime Database 中保存其最高得分。
• 在您自己的游戏中记录 Analytics 事件。
• 尝试为 iOS 游戏添加分析数据。

了解详情

• 不妨查看游戏专属活动列表，并思考如何将这些活动融入您自己的游戏。