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

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

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

    • 模擬器必須搭配 Google Play 使用模擬器映像檔。

    • 部分 C++ 程式庫必須在用戶端裝置上使用 Google Play 服務；請參閱本頁的清單。

  • 使用 Google 帳戶登入 Firebase。

步驟 2：建立 Firebase 專案

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

步驟 3：向 Firebase 註冊應用程式

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

  1. 前往 Firebase 主控台。

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

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

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

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

步驟 4：新增 Firebase 設定檔

  1. 點選「Download google-services.json」，取得 Firebase Android 設定檔。

  2. 在 IDE 中開啟 C++ 專案，然後將設定檔加入專案中：

  3. (僅限 Gradle 版本) 如要在 C++ 專案中啟用 Firebase 服務，請將 Google 服務外掛程式加入頂層 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 服務 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 主控台會通知您應用程式連線已完成。

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

可用的程式庫

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

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

請注意，本設定網頁的 Apple 平台 (iOS+) 版本列出了 Apple 平台適用的 C++ 程式庫。。

Firebase 產品 程式庫參考資料
(firebaseCpp.dependencies
適用於 build.gradle 個檔案)		 程式庫參考資料
(firebase_libs
適用於 CMakeLists.txt 個檔案)
AdMob admob firebase_admob
(必填) firebase_analytics
(必填) firebase_app
數據分析 analytics firebase_analytics
(必填) firebase_app
App Check appCheck firebase_app_check
(必填) firebase_app
身分驗證 auth firebase_auth
(必填) firebase_app
Cloud Firestore firestore firebase_firestore
(必填) firebase_auth
(必填) firebase_app
Cloud Functions functions firebase_functions
(必填) firebase_app
雲端通訊 messaging firebase_messaging
(建議) firebase_analytics
(必填) firebase_app
Cloud Storage storage firebase_storage
(必填) firebase_app
動態連結 dynamicLinks firebase_dynamic_links
(建議) firebase_analytics
(必填) firebase_app
即時資料庫 database firebase_database
(必填) firebase_app
遠端設定 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、makefiles、Visual Studio 等)，則可利用這個指令碼自動產生 Android 字串資源。

ProGuard

許多 Android 建構系統會在發布模式下使用 ProGuard 進行建構，以縮減應用程式大小並保護 Java 原始碼。

如果您使用 ProGuard，就需要根據在 ProGuard 設定中使用的 Firebase C++ 程式庫，新增相對應的 libs/android/*.pro 檔案。

舉例來說，如果您使用 Gradle，則 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 服務的原因 (並嘗試修正)，可以使用 google_play_services/availability.h 中的函式。

下表列出每項支援的 Firebase 產品，是否在用戶端裝置上需要 Google Play 服務。

Firebase C++ 程式庫 用戶端裝置需要使用 Google Play 服務嗎？
AdMob 非必要 (通常)
數據分析 非必要
驗證機制 必填
Cloud Firestore 必填
Cloud Functions 必填
雲端通訊 必填
Cloud Storage 必填
Dynamic Links 必填
即時資料庫 必填
遠端設定 必填

AdMob 和 Google Play 服務

大多數版本的 Android 專用 Google Mobile Ads SDK 在用戶端裝置上無需 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 驗證和 Firebase 即時資料庫

    1. 將 FIREBASE_CPP_SDK_DIR 環境變數設為解壓縮後的 Firebase C++ SDK 位置。

    2. 在專案的 CMakeLists.txt 檔案中，新增以下內容，包括您要使用的 Firebase 產品適用的程式庫。例如，如要使用 Firebase 驗證和 Firebase 即時資料庫：

      # 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 針對部分功能的電腦版工作流程支援，可讓 Firebase 的特定部分在 Windows、macOS 和 Linux 的獨立桌面版本中使用。

Firebase 產品 程式庫參考資料 (使用 CMake)
App Check firebase_app_check
(必填) firebase_app
身分驗證 firebase_auth
(必填) firebase_app
Cloud Firestore firebase_firestore
firebase_auth
firebase_app
Cloud Functions firebase_functions
(必填) firebase_app
Cloud Storage firebase_storage
(必填) firebase_app
即時資料庫 firebase_database
(必填) firebase_app
遠端設定 firebase_remote_config
(必填) firebase_app

Firebase 提供剩餘的桌面程式庫做為虛設常式 (非功能性) 實作，方便您建構 Windows、macOS 和 Linux。因此，您不需要條件式編譯程式碼即可指定電腦。

即時資料庫桌面

電腦版的 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
驗證機制 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
即時資料庫 advapi32, ws2_32, crypt32, iphlpapi, psapi, userenv
遠端設定 advapi32, ws2_32, crypt32, rpcrt4, ole32

macOS 程式庫

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

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

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

後續步驟