將 Firebase 新增至您的 C++ 專案

透過 Firebase C++ SDK 強化 C++ 遊戲，這類 SDK 可在 Firebase SDK 之上提供 C++ 介面。

您可以完全透過 C++ 程式碼存取 Firebase，無須編寫任何平台原生程式碼。Firebase SDK 也會將 Firebase 使用的許多語言專屬慣用語，轉譯為 C++ 開發人員較熟悉的介面。

如要進一步瞭解如何透過 Firebase 提升遊戲效能，請前往 Firebase 遊戲專頁。

是否已將 Firebase 新增至 C++ 專案？請確認您使用的是最新版的 Firebase C++ SDK。


事前準備

  • 安裝您偏好的編輯器或 IDE，例如 Android Studio、IntelliJ 或 VS Code。

  • 取得 Android SDK。

  • 請確認您的專案符合下列規定：

  • 設定實體裝置或使用模擬器來執行應用程式。

    • 模擬器必須使用含有 Google Play 的模擬器映像檔。

    • 部分 C++ 程式庫需要在用戶端裝置上安裝 Google Play 服務，請參閱本頁的清單。

  • 使用 Google 帳戶登入 Firebase。

步驟 2：建立 Firebase 專案

您必須先建立 Firebase 專案，才能將 Firebase 新增至 C++ 專案。請參閱「瞭解 Firebase 專案」一文，進一步瞭解 Firebase 專案。

步驟 3：透過 Firebase 註冊應用程式

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

  1. 前往 Firebase 控制台。

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

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

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

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

步驟 4：新增 Firebase 設定檔

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

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

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

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

  3. (僅限 Gradle 建構) 如要在 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.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 Services 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+) 版本。

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 當機報告

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 服務。

Firebase C++ 程式庫 用戶端裝置是否需要 Google Play 服務？
AdMob 不必提供(通常)
Analytics 非必要
Authentication 必填
Cloud Firestore 必填
Cloud Functions 必填
Cloud Messaging 必填
Cloud Storage 必填
Dynamic Links 必填
Realtime Database 必填
Remote Config 必填

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 產品 程式庫參照 (使用 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 中，程式庫版本會根據以下條件提供：

  • 建構平台：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) 平台的程式庫版本。我們也提供架構，方便您使用。

請注意，我們已使用 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。

後續步驟