將 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 專案

您需要先建立 Firebase 專案並連結至 C++ 專案，才能將 Firebase 新增至您的 C++ 專案。請參閱「瞭解 Firebase 專案」一文，進一步瞭解 Firebase 專案。

步驟 3：將應用程式註冊至 Firebase

如要在 Android 應用程式中使用 Firebase，您必須將應用程式註冊至 Firebase 專案。註冊應用程式通常稱為「新增」應用程式至專案中。

1. 前往 Firebase 控制台。

2. 在專案總覽頁面的中間，按一下「Android」圖示 (plat_android) 或「新增應用程式」，啟動設定工作流程。

3. 在「Android 套件名稱」欄位中輸入應用程式的套件名稱。

   什麼是套件名稱？如何找出套件名稱？

   • 套件名稱可用於在裝置和 Google Play 商店中明確識別應用程式。

   • 「套件名稱」通常稱為「應用程式 ID」。

   • 在模組 (應用程式層級) Gradle 檔案中尋找應用程式的套件名稱，通常是 app/build.gradle (套件名稱範例：com.yourcompany.yourproject)。

   • 請注意，套件名稱值有區分大小寫，且在 Firebase 專案註冊此 Firebase Android 應用程式後，就無法變更。

4. (選用) 輸入其他應用程式資訊：應用程式暱稱和偵錯簽署憑證 SHA-1。

   如何在 Firebase 中使用應用程式別名和偵錯簽署憑證 SHA-1？

   • 應用程式暱稱：這個內部便利的 ID，只會顯示在 Firebase 控制台中

   • 偵錯簽署憑證 SHA-1：Firebase Authentication (使用 Google 登入或電話號碼登入時) 和 Firebase Dynamic Links 都需要 SHA-1 雜湊。

5. 按一下 [Register app] (註冊應用程式)。

步驟 4：新增 Firebase 設定檔

1. 按一下「Download google-services.json」，取得 Firebase Android 設定檔。

   您需要瞭解這個設定檔的哪些資訊？

   • Firebase 設定檔包含專案的非祕密專屬 ID。如要進一步瞭解這個設定檔，請參閱「瞭解 Firebase 專案」。

   • 您隨時可以再次下載 Firebase 設定檔。

   • 請確認設定檔名稱未附加額外的字元，例如 (2)。

2. 在 IDE 中開啟 C++ 專案，然後將設定檔新增至專案：

   • Gradle 建構：將設定檔新增至頂層 build.gradle 檔案所在的目錄。

   • 其他建構系統：請參閱下方的「自訂建構系統」，瞭解如何產生 Android 字串資源。

3. (僅限 Gradle 建構) 如要在 C++ 專案中啟用 Firebase 服務，請將 google-services 外掛程式新增至頂層 build.gradle 檔案。

   1. 新增規則，加入 Google Services 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.2'  // Google Services plugin
            implementation 'com.google.android.gms:18.5.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。否則，您可以略過驗證步驟。

   裝置記錄會顯示 Firebase 驗證，證明初始化已完成。如果您在有網路存取權的模擬器上執行應用程式，Firebase 控制台會通知您應用程式連線已完成。

大功告成！您的 C++ 應用程式已註冊並設定為使用 Firebase 服務。

可用的程式庫

如要進一步瞭解 C++ Firebase 程式庫，請參閱參考說明文件，以及 GitHub 上的開放原始碼 SDK 版本。

Android 適用的程式庫 (使用 CMake)

請注意，Apple 平台的 C++ 程式庫會列於這個設定頁面的 Apple 平台 (iOS+) 版本。

行動版設定的其他資訊

取得 NDK 當機報告

Firebase Crashlytics 支援使用 Android 原生程式庫的應用程式當機回報功能。詳情請參閱「取得 Android NDK 當機報告」。

自訂建構系統

Firebase 提供 generate_xml_from_google_services_json.py 指令碼，可將 google-services.json 轉換為可納入專案的 .xml 資源。這個指令碼會套用 Google Play 服務 Gradle 外掛程式在建構 Android 應用程式時執行的轉換作業。

如果您並未使用 Gradle 進行建構 (例如使用 ndk-build、makefile、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 服務。

AdMob 和 Google Play 服務

大多數版本的 Google Mobile Ads SDK for Android 都能在用戶端裝置上正常運作，無須 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 版)

製作遊戲時，通常最好先在電腦平台上測試遊戲，然後再在開發過程後期在行動裝置上部署及測試。為了支援這個工作流程，我們提供Firebase C++ SDK 的子集，可在 Windows、macOS、Linux 和 C++ 編輯器中執行。

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 的獨立電腦版本中使用 Firebase 的部分功能。

Firebase 會提供其他桌面程式庫做為暫置 (非功能性) 實作，方便您建構 Windows、macOS 和 Linux 應用程式。因此，您不需要依條件編譯程式碼，以便指定電腦。

Realtime Database 電腦

電腦版 Realtime Database SDK 使用 REST 存取您的資料庫，因此您必須宣告在電腦上用於 Query::OrderByChild() 的索引，否則事件監聽器會失敗。

電腦版設定的其他資訊

Windows 程式庫

在 Windows 上，程式庫版本會根據以下條件提供：

• 建構平台：32 位元 (x86) 與 64 位元 (x64) 模式
• Windows 執行階段環境：多執行緒/MT 與多執行緒 DLL/MD
• 目標：發布版與偵錯版

請注意，以下程式庫是使用 Visual Studio 2015 和 2017 進行測試。

在 Windows 上建構 C++ 桌面應用程式時，請將下列 Windows SDK 程式庫連結至專案。詳情請參閱編譯器說明文件。

macOS 程式庫

如為 macOS (Darwin)，則會提供 64 位元 (x86_64) 平台的程式庫版本。此外，我們提供了架構，方便您使用。

請注意，我們已使用 Xcode 13.3.1 測試 macOS 程式庫。

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

後續步驟

• 探索 Firebase 應用程式範例。

• 探索 GitHub 中的開放原始碼 SDK。

• 準備發布應用程式：

  • 在 Google Cloud 控制台中，為專案設定預算快訊。
  • 請在 Firebase 控制台中監控使用量和帳單資訊主頁，全面掌握專案在多項 Firebase 服務中的用量。
  • 詳閱 Firebase 上市檢查清單。