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

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

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

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

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


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

  • ثبِّت المحرِّر أو بيئة التطوير المتكاملة المفضّلة لديك، مثل Android Studio أو IntelliJ أو VS Code.

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

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

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

    • يستخدم 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. (اختياري) أدخِل معلومات التطبيق الأخرى: اسم التطبيق المعرِّف وشهادة توقيع تصحيح الأخطاء بتنسيق SHA-1.

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

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

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

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

  3. (عمليات إنشاء Gradle فقط) لتفعيل خدمات Firebase في مشروعك المكتوب بلغة C++، أضِف مكوّن google-services المكوّن إلى ملف 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.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. تابِع إلى إضافة حِزم تطوير البرامج (SDK) لمنصّة Firebase C++ أدناه.

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

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

  1. نزِّل حزمة SDK لنظام التشغيل Firebase C++، ثم فك ضغط حزمة SDK في مكان مناسب.

    لا تقتصر حزمة 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)
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 يمكنك تضمينها في مشروعك. يطبّق هذا النص البرمجي عملية التحويل نفسها التي ينفّذها المكوّن الإضافي Gradle لخدمات Google Play عند إنشاء تطبيقات Android.

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

ProGuard

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

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

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

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

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

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

AdMob و"خدمات Google Play"

يمكن أن تعمل معظم إصدارات حزمة تطوير البرامج (SDK) لنظام التشغيل Android بشكل سليم بدون "خدمات Google Play" على جهاز العميل.Google Mobile Ads ومع ذلك، إذا كنت تستخدم تبعية 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

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

عند إنشاء لعبة، غالبًا ما يكون من الأسهل اختبارها على منصات الكمبيوتر المكتبي أولاً، ثم نشرها واختبارها على الأجهزة الجوّالة في مرحلة التطوير اللاحقة. لدعم سير العمل هذا، نوفّر مجموعة فرعية من حِزم 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).

    • في حال إضافة ملف GoogleService-Info.plist لنظام التشغيل iOS: قبل تشغيل تطبيقك، عليك تحويل هذا الملف المخصّص للأجهزة الجوّالة إلى ملف إعدادات لأجهزة الكمبيوتر في 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 غير المضغوطة من Firebase C++.

    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 الكمبيوتر المكتبي

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

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

مكتبات Windows

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

  • منصة الإنشاء: وضع 32 بت (x86) مقابل وضع 64 بت (x64)
  • بيئة التشغيل في Windows: تطبيقات متعددة المعالجة / MT مقارنةً بمكتبات DLL متعددة المعالجة /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)، يتم توفير إصدارات المكتبة للنظام الأساسي (x86_64) بسعة 64 بت. نوفّر أيضًا إطارات عمل لتسهيل الأمر عليك.

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

عند إنشاء تطبيقات C++ للكمبيوتر المكتبي على نظام التشغيل macOS، عليك ربط ما يلي بمشروعك:

  • مكتبة نظام pthread
  • CoreFoundation إطار عمل نظام التشغيل macOS
  • Foundation إطار عمل نظام التشغيل macOS
  • Security إطار عمل نظام التشغيل macOS
  • GSS إطار عمل نظام التشغيل macOS
  • Kerberos إطار عمل نظام التشغيل macOS
  • SystemConfiguration إطار عمل نظام التشغيل macOS

يمكنك الرجوع إلى مستندات المُجمِّع للحصول على مزيد من المعلومات.

مكتبات 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.

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