Thêm Firebase vào dự án C++

Nâng tầm trò chơi C++ của bạn bằng SDK C++ Firebase. SDK này cung cấp giao diện C++ trên các SDK Firebase.

Truy cập hoàn toàn vào Firebase từ mã C++ mà không cần viết bất kỳ mã gốc nào trên nền tảng. SDK Firebase cũng dịch nhiều thành ngữ dành riêng cho ngôn ngữ mà Firebase sử dụng thành một giao diện quen thuộc hơn với các nhà phát triển C++.

Tìm hiểu thêm thông tin về cách tăng cường trò chơi bằng Firebase tại trang Trò chơi Firebase.

Bạn đã thêm Firebase vào dự án C++ chưa? Đảm bảo rằng bạn đang sử dụng phiên bản mới nhất của SDK Firebase C++.


Điều kiện tiên quyết

  • Cài đặt trình soạn thảo hoặc IDE mà bạn muốn, chẳng hạn như Android Studio, IntelliJ hoặc VS Code.

  • Tải SDK Android.

  • Đảm bảo rằng dự án của bạn đáp ứng các yêu cầu sau:

  • Thiết lập một thiết bị thực hoặc sử dụng trình mô phỏng để chạy ứng dụng.

    • Trình mô phỏng phải sử dụng hình ảnh trình mô phỏng có Google Play.

    • Đối với một số thư viện C++, bạn cần có Dịch vụ Google Play trên thiết bị của ứng dụng; hãy xem danh sách trên trang này.

  • Đăng nhập vào Firebase bằng Tài khoản Google của bạn.

Bước 2: Tạo dự án Firebase

Trước khi có thể thêm Firebase vào dự án C++, bạn cần tạo một dự án Firebase để kết nối với dự án C++. Truy cập vào bài viết Tìm hiểu về dự án Firebase để tìm hiểu thêm về dự án Firebase.

Bước 3: Đăng ký ứng dụng của bạn với Firebase

Để sử dụng Firebase trong ứng dụng Android, bạn cần đăng ký ứng dụng của mình với dự án Firebase. Việc đăng ký ứng dụng thường được gọi là "thêm" ứng dụng vào dự án.

  1. Chuyển đến bảng điều khiển Firebase.

  2. Ở giữa trang tổng quan về dự án, hãy nhấp vào biểu tượng Android () hoặc Thêm ứng dụng để chạy quy trình thiết lập.

  3. Nhập tên gói của ứng dụng vào trường Tên gói Android.

  4. (Không bắt buộc) Nhập thông tin khác về ứng dụng: Biệt hiệu ứng dụng và Chứng chỉ ký gỡ lỗi SHA-1.

  5. Nhấp vào Đăng ký ứng dụng.

Bước 4: Thêm tệp cấu hình Firebase

  1. Nhấp vào Download google-services.json (Tải google-services.json xuống) để lấy tệp cấu hình Firebase Android.

  2. Mở dự án C++ trong IDE, sau đó thêm tệp cấu hình vào dự án:

  3. (Chỉ dành cho bản dựng Gradle) Để bật các dịch vụ Firebase trong dự án C++, hãy thêm trình bổ trợ google-services vào tệp build.gradle cấp cao nhất.

    1. Thêm các quy tắc để đưa trình bổ trợ Gradle cho Dịch vụ Google vào. Kiểm tra để đảm bảo rằng bạn cũng có kho lưu trữ Maven của Google.

        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. Áp dụng trình bổ trợ Dịch vụ Google cho Gradle:

        apply plugin: 'com.android.application'
  // Add the following line:
  apply plugin: 'com.google.gms.google-services'  // Google Services plugin

  android {
    // ...
  }

  4. Bạn đã hoàn tất việc thiết lập các tác vụ trong bảng điều khiển Firebase. Tiếp tục Thêm SDK Firebase C++ ở bên dưới.

Bước 5: Thêm SDK Firebase C++

Các bước trong phần này là ví dụ về cách thêm các sản phẩm Firebase được hỗ trợ vào dự án Firebase C++.

  1. Tải SDK Firebase C++ xuống, sau đó giải nén SDK ở một nơi thuận tiện.

    SDK Firebase C++ không dành riêng cho nền tảng, nhưng chứa các thư viện dành riêng cho nền tảng.

  2. Trong tệp gradle.properties của dự án, hãy chỉ định vị trí của SDK đã giải nén:

    systemProp.firebase_cpp_sdk.dir=full-path-to-SDK

  3. Thêm nội dung sau vào tệp settings.gradle của dự án:

    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. Thêm nội dung sau vào tệp Gradle của mô-đun (cấp ứng dụng) (thường là app/build.gradle).
    Thêm các phần phụ thuộc thư viện cho các sản phẩm Firebase mà bạn muốn sử dụng trong ứng dụng.

    Đã bật 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
}

    Chưa bật 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. Thêm nội dung sau vào tệp CMakeLists.txt của dự án.
    Thêm thư viện cho các sản phẩm Firebase mà bạn muốn sử dụng trong ứng dụng.

    Đã bật 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}")

    Chưa bật 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. Đồng bộ hoá ứng dụng để đảm bảo rằng tất cả phần phụ thuộc đều có các phiên bản cần thiết.

  7. Nếu bạn đã thêm Analytics, hãy chạy ứng dụng để gửi thông tin xác minh cho Firebase rằng bạn đã tích hợp thành công Firebase. Nếu không, bạn có thể bỏ qua bước xác minh.

    Nhật ký thiết bị của bạn sẽ hiển thị thông tin xác minh Firebase rằng quá trình khởi chạy đã hoàn tất. Nếu bạn chạy ứng dụng trên một trình mô phỏng có quyền truy cập mạng, thì bảng điều khiển Firebase sẽ thông báo cho bạn rằng kết nối ứng dụng đã hoàn tất.

Bạn đã hoàn tất! Ứng dụng C++ của bạn đã được đăng ký và định cấu hình để sử dụng các dịch vụ của Firebase.

Thư viện có sẵn

Tìm hiểu thêm về các thư viện Firebase C++ trong tài liệu tham khảo và trong bản phát hành SDK nguồn mở của chúng tôi trên GitHub.

Các thư viện có sẵn cho Android (sử dụng CMake)

Xin lưu ý rằng các thư viện C++ dành cho nền tảng Apple được liệt kê trên phiên bản nền tảng Apple (iOS trở lên) của trang thiết lập này.

Sản phẩm Firebase Tham chiếu thư viện
(firebaseCpp.dependencies
đối với tệp build.gradle)		 Tham chiếu thư viện
(firebase_libs
đối với tệp CMakeLists.txt)
AdMob admob firebase_admob
(bắt buộc) firebase_analytics
(bắt buộc) firebase_app
Analytics analytics firebase_analytics
(bắt buộc) firebase_app
App Check appCheck firebase_app_check
(bắt buộc) firebase_app
Authentication auth firebase_auth
(bắt buộc) firebase_app
Cloud Firestore firestore firebase_firestore
(bắt buộc) firebase_auth
(bắt buộc) firebase_app
Cloud Functions functions firebase_functions
(bắt buộc) firebase_app
Cloud Messaging messaging firebase_messaging
(nên dùng) firebase_analytics
(bắt buộc) firebase_app
Cloud Storage storage firebase_storage
(bắt buộc) firebase_app
Dynamic Links dynamicLinks firebase_dynamic_links
(nên dùng) firebase_analytics
(bắt buộc) firebase_app
Realtime Database database firebase_database
(bắt buộc) firebase_app
Remote Config remoteConfig firebase_remote_config
(nên dùng) firebase_analytics
(bắt buộc) firebase_app

Thông tin bổ sung để thiết lập cho thiết bị di động

Nhận báo cáo sự cố NDK

Firebase Crashlytics hỗ trợ tính năng báo cáo sự cố cho các ứng dụng sử dụng thư viện gốc của Android. Để tìm hiểu thêm, hãy xem phần Nhận báo cáo sự cố Android NDK.

Hệ thống xây dựng tuỳ chỉnh

Firebase cung cấp tập lệnh generate_xml_from_google_services_json.py để chuyển đổi google-services.json thành tài nguyên .xml mà bạn có thể đưa vào dự án. Tập lệnh này áp dụng cùng một phép biến đổi mà trình bổ trợ Gradle của dịch vụ Google Play thực hiện khi tạo ứng dụng Android.

Nếu không tạo bằng Gradle (ví dụ: bạn sử dụng ndk-build, tệp makefile, Visual Studio, v.v.), bạn có thể sử dụng tập lệnh này để tự động tạo Tài nguyên chuỗi Android.

ProGuard

Nhiều hệ thống xây dựng Android sử dụng ProGuard cho các bản dựng ở chế độ Phát hành để rút gọn kích thước ứng dụng và bảo vệ mã nguồn Java.

Nếu sử dụng ProGuard, bạn cần thêm các tệp trong libs/android/*.pro tương ứng với các thư viện Firebase C++ mà bạn đang sử dụng trong cấu hình ProGuard.

Ví dụ: với Gradle, nếu bạn đang sử dụng Google Analytics, thì tệp build.gradle sẽ có dạng như sau:

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
    }
  }
}

Yêu cầu về Dịch vụ Google Play

Hầu hết các thư viện Firebase C++ đều yêu cầu Dịch vụ Google Play phải có trên thiết bị Android của ứng dụng. Nếu thư viện Firebase C++ trả về kInitResultFailedMissingDependency khi khởi chạy, thì tức là Dịch vụ Google Play không có trên thiết bị khách (nghĩa là thiết bị đó cần được cập nhật, kích hoạt lại, khắc phục quyền, v.v.). Bạn không thể sử dụng thư viện Firebase cho đến khi khắc phục được tình huống trên thiết bị của ứng dụng.

Bạn có thể tìm hiểu lý do Dịch vụ Google Play không hoạt động trên thiết bị khách (và cố gắng khắc phục) bằng cách sử dụng các hàm trong google_play_services/availability.h.

Bảng sau đây liệt kê liệu dịch vụ Google Play có bắt buộc trên thiết bị của ứng dụng cho từng sản phẩm Firebase được hỗ trợ hay không.

Thư viện Firebase C++ Có bắt buộc phải có Dịch vụ Google Play trên thiết bị khách không?
AdMob Không bắt buộc (thường)
Analytics Không yêu cầu
Authentication Bắt buộc
Cloud Firestore Bắt buộc
Cloud Functions Bắt buộc
Cloud Messaging Bắt buộc
Cloud Storage Bắt buộc
Dynamic Links Bắt buộc
Realtime Database Bắt buộc
Remote Config Bắt buộc

AdMob và Dịch vụ Google Play

Hầu hết các phiên bản SDK Google Mobile Ads cho Android đều có thể hoạt động đúng cách mà không cần Dịch vụ Google Play trên thiết bị khách. Tuy nhiên, nếu bạn đang sử dụng phần phụ thuộc com.google.android.gms:play-services-ads-lite thay vì phần phụ thuộc com.google.firebase:firebase-ads tiêu chuẩn được liệt kê ở trên, thì bạn bắt buộc phải có Dịch vụ Google Play.

Quá trình khởi tạo AdMob sẽ chỉ trả về kInitResultFailedMissingDependency khi cả hai điều sau đây đều đúng:

  • Dịch vụ Google Play không dùng được trên thiết bị khách.
  • Bạn đang sử dụng com.google.android.gms:play-services-ads-lite.

Thiết lập quy trình làm việc trên máy tính (phiên bản thử nghiệm)

Khi tạo trò chơi, bạn thường dễ dàng kiểm thử trò chơi trên các nền tảng máy tính trước, sau đó triển khai và kiểm thử trên thiết bị di động trong quá trình phát triển. Để hỗ trợ quy trình công việc này, chúng tôi cung cấp một nhóm con của SDK Firebase C++ có thể chạy trên Windows, macOS, Linux và trong trình chỉnh sửa C++.

  1. Đối với quy trình làm việc trên máy tính, bạn cần hoàn tất những việc sau:

    1. Định cấu hình dự án C++ cho CMake.
    2. Tạo dự án Firebase
    3. Đăng ký ứng dụng (iOS hoặc Android) của bạn với Firebase
    4. Thêm tệp cấu hình Firebase cho nền tảng di động

  2. Tạo phiên bản máy tính của tệp cấu hình Firebase:

    • Nếu bạn đã thêm tệp google-services.json của Android – Khi bạn chạy ứng dụng, Firebase sẽ tìm tệp di động này, sau đó tự động tạo tệp cấu hình Firebase máy tính (google-services-desktop.json).

    • Nếu bạn đã thêm tệp GoogleService-Info.plist dành cho iOS – Trước khi chạy ứng dụng, bạn cần chuyển đổi tệp di động này thành tệp cấu hình Firebase máy tính. Để chuyển đổi tệp, hãy chạy lệnh sau trong cùng thư mục với tệp GoogleService-Info.plist:

      generate_xml_from_google_services_json.py --plist -i GoogleService-Info.plist

    Tệp cấu hình dành cho máy tính này chứa mã dự án C++ mà bạn đã nhập trong quy trình thiết lập bảng điều khiển Firebase. Truy cập vào bài viết Tìm hiểu về dự án Firebase để tìm hiểu thêm về tệp cấu hình.

  3. Thêm SDK Firebase vào dự án C++.

    Các bước dưới đây là ví dụ về cách thêm bất kỳ sản phẩm Firebase được hỗ trợ nào vào dự án C++. Trong ví dụ này, chúng ta sẽ hướng dẫn cách thêm Firebase Authentication và Firebase Realtime Database.

    1. Đặt biến môi trường FIREBASE_CPP_SDK_DIR thành vị trí của SDK Firebase C++ đã giải nén.

    2. Thêm nội dung sau vào tệp CMakeLists.txt của dự án, bao gồm cả thư viện cho các sản phẩm Firebase mà bạn muốn sử dụng. Ví dụ: để sử dụng Firebase Authentication và 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. Chạy ứng dụng C++.

Thư viện có sẵn (máy tính)

SDK Firebase C++ bao gồm tính năng hỗ trợ quy trình làm việc trên máy tính cho một số tính năng, cho phép sử dụng một số phần nhất định của Firebase trong các bản dựng máy tính độc lập trên Windows, macOS và Linux.

Sản phẩm Firebase Tài liệu tham khảo thư viện (sử dụng CMake)
App Check firebase_app_check
(bắt buộc) firebase_app
Authentication firebase_auth
(bắt buộc) firebase_app
Cloud Firestore firebase_firestore
firebase_auth
firebase_app
Cloud Functions firebase_functions
(bắt buộc) firebase_app
Cloud Storage firebase_storage
(bắt buộc) firebase_app
Realtime Database firebase_database
(bắt buộc) firebase_app
Remote Config firebase_remote_config
(bắt buộc) firebase_app

Firebase cung cấp các thư viện máy tính để bàn còn lại dưới dạng các phương thức triển khai giả lập (không hoạt động) để thuận tiện khi xây dựng cho Windows, macOS và Linux. Do đó, bạn không cần biên dịch mã có điều kiện để nhắm đến máy tính.

Realtime Database dành cho máy tính

SDK Realtime Database dành cho máy tính sử dụng REST để truy cập vào cơ sở dữ liệu của bạn, vì vậy, bạn phải khai báo các chỉ mục mà bạn sử dụng với Query::OrderByChild() trên máy tính hoặc trình nghe của bạn sẽ không hoạt động.

Thông tin bổ sung để thiết lập trên máy tính

Thư viện Windows

Đối với Windows, các phiên bản thư viện được cung cấp dựa trên những thông tin sau:

  • Nền tảng xây dựng: Chế độ 32 bit (x86) so với 64 bit (x64)
  • Môi trường thời gian chạy Windows: Đa luồng / MT so với DLL đa luồng /MD
  • Mục tiêu: Phát hành so với Gỡ lỗi

Xin lưu ý rằng các thư viện sau đây đã được kiểm thử bằng Visual Studio 2015 và 2017.

Khi tạo ứng dụng C++ cho máy tính trên Windows, hãy liên kết các thư viện SDK Windows sau đây với dự án của bạn. Hãy tham khảo tài liệu về trình biên dịch để biết thêm thông tin.

Thư viện Firebase C++ Phần phụ thuộc thư viện SDK Windows
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

Thư viện macOS

Đối với macOS (Darwin), các phiên bản thư viện được cung cấp cho nền tảng 64 bit (x86_64). Chúng tôi cũng cung cấp các khung để thuận tiện cho bạn.

Xin lưu ý rằng các thư viện macOS đã được kiểm thử bằng Xcode 13.3.1.

Khi tạo ứng dụng C++ cho máy tính trên macOS, hãy liên kết những nội dung sau với dự án của bạn:

  • Thư viện hệ thống pthread
  • CoreFoundation Khung hệ thống macOS
  • Foundation Khung hệ thống macOS
  • Security Khung hệ thống macOS
  • GSS Khung hệ thống macOS
  • Kerberos Khung hệ thống macOS
  • SystemConfiguration Khung hệ thống macOS

Hãy tham khảo tài liệu về trình biên dịch để biết thêm thông tin.

Thư viện Linux

Đối với Linux, các phiên bản thư viện được cung cấp cho nền tảng 32 bit (i386) và 64 bit (x86_64).

Xin lưu ý rằng các thư viện Linux đã được kiểm thử bằng GCC 4.8.0, GCC 7.2.0 và Clang 5.0 trên Ubuntu.

Khi tạo ứng dụng C++ cho máy tính trên Linux, hãy liên kết thư viện hệ thống pthread với dự án của bạn. Hãy tham khảo tài liệu về trình biên dịch để biết thêm thông tin. Nếu bạn đang tạo bằng GCC 5 trở lên, hãy xác định -D_GLIBCXX_USE_CXX11_ABI=0.

Các bước tiếp theo