إضافة Firebase إلى مشروع C++ الخاص بك

يمكنك تحسين أداء ألعابك المصمّمة بلغة C++‎ باستخدام Firebase C++ SDK التي توفّر واجهة C++‎ بالإضافة إلى Firebase SDK.

يمكنك الوصول إلى Firebase بالكامل من خلال رمز C++‎، بدون الحاجة إلى كتابة أي رمز برمجي أصلي للمنصة. تترجم حزمة Firebase SDK أيضًا العديد من المصطلحات الخاصة باللغة التي تستخدمها Firebase إلى واجهة مألوفة أكثر لمطوّري C++‎.

يمكنك الاطّلاع على مزيد من المعلومات حول تحسين ألعابك باستخدام Firebase في صفحة ألعاب Firebase.

هل سبق لك إضافة Firebase إلى مشروع C++‎؟ تأكَّد من استخدام أحدث إصدار من حزمة تطوير البرامج (SDK) لـ Firebase C++.


المتطلبات الأساسية

  • ثبِّت أداة التعديل أو بيئة التطوير المتكاملة (IDE) المفضّلة لديك، مثل "استوديو Android" أو IntelliJ أو VS Code.

  • احصل على حزمة تطوير البرامج (SDK) لنظام التشغيل Android.

  • تأكَّد من أنّ مشروعك يستوفي المتطلبات التالية:

    • يستهدف المستوى 24 من واجهة برمجة التطبيقات (Nougat) أو الإصدارات الأحدث

    • يستخدم Gradle ويتم ضبطه باستخدام CMake

  • اضبط جهازًا فعليًا أو استخدِم محاكيًا لتشغيل تطبيقك.

    • يجب أن تستخدم المحاكيات صورة محاكي مع Google Play.

    • بالنسبة إلى بعض مكتبات C++‎، يجب توفُّر "خدمات Google Play" على جهاز العميل. يمكنك مراجعة القائمة في هذه الصفحة.

  • سجِّل الدخول إلى Firebase باستخدام حسابك على Google.

الخطوة 2: إنشاء مشروع Firebase

قبل إضافة Firebase إلى مشروع C++‎، عليك إنشاء مشروع Firebase لربطه بمشروع C++‎. انتقِل إلى مقالة فهم مشاريع Firebase لمزيد من المعلومات عن مشاريع Firebase.

الخطوة 3: تسجيل تطبيقك في Firebase

لاستخدام Firebase في تطبيق Android، عليك تسجيل تطبيقك في مشروع Firebase. غالبًا ما يُطلق على تسجيل تطبيقك اسم "إضافة" تطبيقك إلى مشروعك.

  1. انتقِل إلى وحدة تحكّم Firebase.

  2. في منتصف صفحة النظرة العامة على المشروع، انقر على رمز Android () أو إضافة تطبيق لبدء عملية الإعداد.

  3. أدخِل اسم حزمة تطبيقك في حقل اسم حزمة Android.

  4. (اختياري) أدخِل اسمًا مستعارًا للتطبيق، وهو معرّف داخلي مريح لا يظهر إلا لك في وحدة تحكّم Firebase.

  5. انقر على تسجيل التطبيق.

الخطوة 4: إضافة ملف إعدادات Firebase

  1. انقر على تنزيل google-services.json للحصول على ملف إعداد Firebase Android.

  2. افتح مشروع C++‎ في بيئة تطوير متكاملة (IDE)، ثم أضِف ملف الإعداد إلى مشروعك:

  3. (إصدارات Gradle فقط) لتفعيل خدمات Firebase في مشروع C++‎، أضِف المكوّن الإضافي Gradle لخدمات Google إلى ملف build.gradle ذي المستوى الأعلى.

    1. أضِف قواعد لتضمين المكوّن الإضافي Gradle لخدمات Google. تأكَّد من توفّر مستودع Maven من 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.5.0'  // Google services Gradle plugin
      implementation 'com.google.android.gms:18.11.1'
    }
  }

  allprojects {
    // ...

    repositories {
      // Check that you have the following line (if not, add it):
      google()  // Google's Maven repository
      // ...
    }
  }

    2. طبِّق المكوّن الإضافي Gradle لخدمات Google:

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

  android {
    // ...
  }

  4. لقد أكملت مهام الإعداد في وحدة تحكّم Firebase. انتقِل إلى قسم إضافة حزم تطوير البرامج (SDK) لـ Firebase C++‎ أدناه.

الخطوة 5: إضافة حِزم تطوير البرامج (SDK) لـ Firebase C++‎

الخطوات الواردة في هذا القسم هي مثال على كيفية إضافة منتجات Firebase المتوافقة إلى مشروع Firebase C++‎.

  1. نزِّل حزمة تطوير البرامج (SDK) لـ Firebase C++، ثم فُكّ ضغطها في مكان مناسب.

    لا تقتصر حزمة تطوير البرامج (SDK) لـ Firebase C++ على نظام أساسي معيّن، ولكنّها تحتوي على مكتبات مخصّصة لأنظمة أساسية معيّنة.

  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.

المكتبات المتاحة

يمكنك الاطّلاع على مزيد من المعلومات حول مكتبات Firebase بلغة C++‎ في المستندات المرجعية وفي إصدار حزمة تطوير البرامج (SDK) المفتوحة المصدر على GitHub.

المكتبات المتاحة لنظام التشغيل Android (باستخدام CMake)

يُرجى العِلم أنّ مكتبات C++‎ لأنظمة Apple الأساسية مُدرَجة في إصدار أنظمة Apple الأساسية (iOS+) من صفحة الإعداد هذه.

منتج Firebase مراجع المكتبة
(firebaseCpp.dependencies
لملف build.gradle)		 مراجع المكتبة
(firebase_libs
لملف CMakeLists.txt)
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
Realtime Database database firebase_database
(مطلوب) firebase_app
Remote Config remoteConfig firebase_remote_config
(يُنصح به) firebase_analytics
(مطلوب) firebase_app
المكتبات المتوقفة نهائيًا أو غير المتوافقة
Dynamic Links dynamicLinks firebase_dynamic_links
(يُنصح به) firebase_analytics
(مطلوب) firebase_app

معلومات إضافية حول الإعداد على الأجهزة الجوّالة

الحصول على تقارير أعطال NDK

يتيح Firebase Crashlytics إعداد تقارير الأعطال للتطبيقات التي تستخدم مكتبات Android مجمّعة من رموز برمجية أصلية. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة الحصول على تقارير الأعطال في Android NDK.

أنظمة الإنشاء المخصّصة

يوفّر Firebase النص البرمجي generate_xml_from_google_services_json.py لتحويل موارد google-services.json إلى موارد .xml يمكنك تضمينها في مشروعك. يطبّق هذا النص البرمجي عملية التحويل نفسها التي ينفّذها المكوّن الإضافي Gradle لخدمات Google Play عند إنشاء تطبيقات Android.

إذا لم تكن تستخدم Gradle في عملية الإنشاء (على سبيل المثال، إذا كنت تستخدم ndk-build أو ملفات makefile أو Visual Studio أو غير ذلك)، يمكنك استخدام هذا النص البرمجي لإنشاء موارد سلاسل Android تلقائيًا.

ProGuard

تستخدم العديد من أنظمة إصدارات Android أداة ProGuard للإصدارات في وضع الإصدار لتقليص أحجام التطبيقات وحماية الرمز المصدر لـ Java.

إذا كنت تستخدم ProGuard، عليك إضافة الملفات في libs/android/*.pro المقابلة لمكتبات Firebase C++‎ التي تستخدمها في إعدادات ProGuard.

على سبيل المثال، إذا كنت تستخدم Google Analytics مع 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++‎ تثبيت خدمات Google Play على جهاز Android الخاص بالعميل. إذا عرضت مكتبة Firebase C++‎ القيمة kInitResultFailedMissingDependency عند الإعداد، يعني ذلك أنّ "خدمات Google Play" غير متاحة على جهاز العميل (أي أنّها بحاجة إلى التحديث أو إعادة التفعيل أو إصلاح الأذونات أو غير ذلك). لا يمكن استخدام مكتبة Firebase إلى أن يتم تصحيح الوضع على جهاز العميل.

يمكنك معرفة سبب عدم توفّر "خدمات Google Play" على جهاز العميل (ومحاولة حلّ المشكلة) باستخدام الدوال في google_play_services/availability.h.

يوضّح الجدول التالي ما إذا كانت "خدمات Google Play" مطلوبة على جهاز العميل لكل منتج من منتجات Firebase المتوافقة.

مكتبة Firebase C++‎ هل "خدمات Google Play" مطلوبة على جهاز العميل؟
Analytics غير مطلوب
Authentication مطلوب
Cloud Firestore مطلوب
Cloud Functions مطلوب
Cloud Messaging مطلوب
Cloud Storage مطلوب
Dynamic Links مطلوب
Realtime Database مطلوب
Remote Config مطلوب

إعداد سير عمل على الكمبيوتر المكتبي (إصدار تجريبي)

عند إنشاء لعبة، غالبًا ما يكون من الأسهل اختبارها على أجهزة الكمبيوتر المكتبي أولاً، ثم نشرها واختبارها على الأجهزة الجوّالة في مرحلة لاحقة من عملية التطوير. ولدعم سير العمل هذا، نقدّم مجموعة فرعية من حِزم تطوير البرامج (SDK) الخاصة بـ Firebase C++ التي يمكن تشغيلها على أنظمة التشغيل Windows وmacOS وLinux ومن داخل محرِّر C++‎.

  1. بالنسبة إلى سير العمل على أجهزة الكمبيوتر المكتبي، عليك إكمال ما يلي:

    1. اضبط مشروع C++‎ لاستخدام CMake.
    2. إنشاء مشروع Firebase
    3. تسجيل تطبيقك (iOS أو Android) في Firebase
    4. إضافة ملف إعداد Firebase للأجهزة الجوّالة

  2. أنشئ نسخة لأجهزة الكمبيوتر من ملف إعدادات Firebase:

    • إذا أضفت ملف google-services.json لنظام التشغيل Android: عند تشغيل تطبيقك، يحدّد 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

    يحتوي ملف الإعداد هذا على رقم تعريف مشروع C++‎ الذي أدخلته في سير عمل إعداد وحدة تحكّم Firebase. انتقِل إلى مقالة فهم مشاريع Firebase لمعرفة المزيد عن ملفات الإعداد.

  3. أضِف حزم تطوير البرامج (SDK) لمنصة Firebase إلى مشروع C++‎.

    الخطوات أدناه هي مثال على كيفية إضافة أي منتج متوافق من Firebase إلى مشروع C++‎. في هذا المثال، سنشرح كيفية إضافة Firebase Authentication وFirebase Realtime Database.

    1. اضبط متغيّر البيئة FIREBASE_CPP_SDK_DIR على موقع حزمة تطوير البرامج (SDK) لـ C++ Firebase التي تم فك ضغطها.

    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++‎.

المكتبات المتاحة (على الكمبيوتر المكتبي)

تتضمّن حزمة تطوير البرامج (SDK) لمنصّة Firebase C++ إمكانية استخدام سير العمل على الكمبيوتر المكتبي لمجموعة فرعية من الميزات، ما يتيح استخدام أجزاء معيّنة من Firebase في إصدارات الكمبيوتر المكتبي المستقلة على أنظمة التشغيل Windows وmacOS وLinux.

منتج 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 مكتبات أجهزة الكمبيوتر المكتبي المتبقية كعمليات تنفيذ موجزة (غير وظيفية) لتسهيل عملية الإنشاء لأنظمة التشغيل Windows وmacOS وLinux. لذلك، لست بحاجة إلى تجميع الرمز بشكل مشروط لاستهداف أجهزة الكمبيوتر المكتبي.

جهاز كمبيوتر مكتبي واحد (Realtime Database)

تستخدم حزمة تطوير البرامج (SDK) لخدمة Realtime Database على أجهزة الكمبيوتر REST للوصول إلى قاعدة بياناتك، لذا عليك تعريف الفهارس التي تستخدمها مع Query::OrderByChild() على أجهزة الكمبيوتر، وإلا ستتعطّل أدوات الاستماع.

معلومات إضافية حول الإعداد على الكمبيوتر المكتبي

مكتبات Windows

بالنسبة إلى نظام التشغيل Windows، يتم توفير إصدارات المكتبة استنادًا إلى ما يلي:

  • النظام الأساسي للإصدار: وضع 32 بت (x86) مقابل وضع 64 بت (x64)
  • بيئة تشغيل Windows: سلاسل تعليمات متعددة / MT مقابل مكتبة الربط الديناميكي لسلاسل التعليمات المتعددة /MD
  • الهدف: الإصدار مقابل تصحيح الأخطاء

يُرجى العِلم أنّه تم اختبار المكتبات التالية باستخدام Visual Studio 2015 و2017.

عند إنشاء تطبيقات C++‎ متوافقة مع أجهزة الكمبيوتر المكتبي على نظام التشغيل Windows، يجب ربط مكتبات حزمة تطوير البرامج (SDK) التالية لنظام التشغيل Windows بمشروعك. يُرجى الرجوع إلى مستندات برنامج التجميع للحصول على مزيد من المعلومات.

مكتبة Firebase C++‎ الاعتماديات الخاصة بمكتبات حزم تطوير البرامج (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

مكتبات macOS

بالنسبة إلى نظام التشغيل macOS (Darwin)، يتم توفير إصدارات المكتبة للنظام الأساسي 64 بت (x86_64). يتم أيضًا توفير أُطر عمل لتسهيل الأمر عليك.

يُرجى العِلم أنّه تم اختبار مكتبات macOS باستخدام Xcode 26.2.

عند إنشاء تطبيقات C++‎ متوافقة مع أجهزة الكمبيوتر المكتبي على نظام التشغيل macOS، اربط ما يلي بمشروعك:

  • مكتبة نظام واحدة (pthread)
  • إطار عمل نظام macOS واحد (CoreFoundation)
  • إطار عمل نظام macOS واحد (Foundation)
  • إطار عمل نظام macOS واحد (Security)
  • إطار عمل نظام macOS واحد (GSS)
  • إطار عمل نظام macOS واحد (Kerberos)
  • إطار عمل نظام macOS واحد (SystemConfiguration)

يُرجى الرجوع إلى مستندات برنامج التجميع لمزيد من المعلومات.

مكتبات Linux

بالنسبة إلى نظام التشغيل Linux، يتم توفير إصدارات المكتبة للأنظمة الأساسية 32 بت (i386) و64 بت (x86_64).

يُرجى العِلم أنّه تم اختبار مكتبات Linux باستخدام GCC 4.8.0 وGCC 7.2.0 وClang 5.0 على Ubuntu.

عند إنشاء تطبيقات C++‎ متوافقة مع أجهزة الكمبيوتر المكتبي على نظام التشغيل Linux، اربط مكتبة النظام pthread بمشروعك. يُرجى الرجوع إلى مستندات برنامج التجميع لمزيد من المعلومات. إذا كنت تستخدم الإصدار 5 من GCC أو إصدارًا أحدث، حدِّد -D_GLIBCXX_USE_CXX11_ABI=0.

الخطوات التالية