在 C+ 中開始使用 Firebase；+

1. 總覽

在本程式碼研究室中，您將以 Google Analytics 為例，瞭解如何在 Android 範例遊戲中整合 C++ Firebase Games SDK。您可以新增所需功能、整合一些基本分析邏輯來評估玩家進度，並與測試人員分享遊戲，搶先取得意見回饋。

逐步操作說明

如要與作者一起完成本程式碼研究室，請觀看這部影片：

課程內容

• 如何將 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。您可以移除目標架構以外的所有架構，縮短建構時間。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. 為其命名，例如「冰棒跑者」
3. 啟用 Analytics
4. 新增或建立 Analytics 帳戶
5. 在專案中新增 Android 應用程式
6. 將 com.firebase.popsiclerunner 新增為套件名稱。

本程式碼研究室不需要 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' 新增為建構指令碼依附元件。

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. 新增 Analytics

即使在開發初期，您也能使用數據分析工具，評估 Beta 版測試人員與遊戲的互動情形。系統會自動收集部分數據分析資料 (例如留存率報表)，但加入專為特定遊戲量身打造的自訂事件，會更有助於分析。

建議您先在玩家開始關卡時記錄 Analytics 事件。我們可以根據關卡開始事件的數量，瞭解玩家在一個工作階段中重玩遊戲的頻率。

此外，我們也會記錄玩家死亡時的進度。這有助於我們瞭解所做的變更如何影響單一工作階段的時長，並判斷玩家是否偏好較短/較難或較長/較簡單的遊戲。

新增 Analytics 標頭

開啟 Classes/PopsicleScene.cpp，在頂端加入 Firebase 標頭，以便進行 Analytics 呼叫。

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()，並在設定 _gameOver = true; 之前，將此項目新增至 if(!_gameOver) { 區塊的結尾：

PopsicleScene.cpp

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

kEventLevelEnd 是關卡結束事件。而 "distance" 則是「事件參數」。我們將在此新增最後記錄的距離，這項資料可做為玩家死亡前移動距離的良好近似值。

7. 測試事件

您現在可以點按「Debug」，但 Analytics 資訊主頁需要一段時間才會回報任何事件。這是因為：1) 系統會將事件分批上傳 (約每小時一次)，以節省電量；2) 報表每 24 小時產生一次。

你可以透過某些機制更快查看事件。如果事件標示為轉換事件，在許多情況下，系統會近乎即時地回報。您也可以設定 Google Analytics 將資料匯出至 BigQuery，這樣一來，當日資料表的資料只會延遲約 4 小時。

啟用偵錯模式

您仍可將裝置設為偵錯模式，偵錯 Analytics 事件。

首先，請確認已安裝並設定 Android Debug Bridge (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」

按一下「Debug」圖示 並開始玩遊戲。遊戲中發生新事件後，您應該會立即看到這些事件。

展開 level_end 事件後，您也會看到記錄的自訂「距離」參數。

level_end 事件最終會顯示在事件報表中，但預設不會擷取距離。選取「事件」圖示 ，找到 level_end，展開右側的三點圖示 ，然後選取「編輯參數報表」，將其新增為事件報表中的參數。完成後，您就能查看球員的平均每場距離等統計資料。

8. 尋找測試人員

接下來，無論是工作室內部人員、親近好友或社群成員，您都希望他們能看到您的遊戲。Firebase 應用程式發布功能可讓您輕鬆邀請玩家試玩遊戲。

建構獨立二進位檔

首先，請依序選取「Build」>「Build Bundles(s) / APK(s)」>「Build APK(s)」，建構獨立 APK 以供分享。

如果先前變更過 ABI 篩選器，請務必返回 gradle.properties，並變更 PROP_APP_ABI，納入您打算測試的任何裝置：

PROP_APP_ABI=armeabi-v7a:arm64-v8a:x86

Android Studio 會彈出對話方塊，讓您找出建構的檔案。如果錯過，可以點選「事件記錄」再次取得連結。

上傳至 Firebase 應用程式發布

1. 開啟 App Distribution，然後按一下「開始使用」圖示
2. 將 .apk 檔案拖曳到「將任何 .apk 檔案拖曳到這裡，即可建立新版本」的方塊中。
3. 輸入您的電子郵件地址做為第一位測試人員。
4. 點選「下一步」。
5. 新增說明並按一下「發布」

邀請測試人員

不必手動輸入每個電子郵件地址，只要建立邀請連結即可。使用這個邀請連結擷取使用者時，您也可以將他們加入測試人員群組。舉例來說，您可以藉此區分內部測試人員和外部測試人員。

1. 按一下「測試人員和群組」圖示
2. 建立新群組 ，並命名為「Android 測試人員」等。
3. 按一下「邀請連結」圖示
4. 按一下「新增邀請連結」
5. 從下拉式選單中設定群組。
6. 按一下「建立連結」
7. 按一下「複製連結」，然後以任何方式分享

9. 恭喜

您已成功在以 C++ 為基礎的遊戲中加入 Analytics，並邀請了一些朋友一起玩，而且您知道如何在 Android 開發中常見的 CMake 和 Gradle 建構系統中，尋找及連結 Firebase 程式庫。

涵蓋內容

• 如何將 Firebase 新增至以 Android CMake 為基礎的遊戲。
• 如何找出所需的 C++ 和 Gradle 依附元件。
• 如何記錄 Analytics 事件。
• 如何偵錯 Analytics 事件。
• 如何透過 App Distribution 分享遊戲。

後續步驟

• 請嘗試以匿名方式登入使用者，並將他們的高分儲存至即時資料庫。
• 在自己的遊戲中記錄 Analytics 事件。
• 試著在 iOS 遊戲中加入 Analytics。

瞭解詳情

• 請參閱遊戲專屬事件清單，並考量這些事件是否適合您的遊戲。