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

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

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

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

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


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

  • ثبِّت المحرّر أو IDE المفضّل لديك، مثل "استوديو Android" أو 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 للحصول على ملف إعداد Android في Firebase.

  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: Multithreaded / MT مقابل Multithreaded 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)، تتوفّر إصدارات المكتبة لنظام التشغيل 64 بت (x86_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 بمشروعك. يمكنك الرجوع إلى مستندات المُجمِّع للحصول على مزيد من المعلومات. إذا كنت تنشئ الإصدار باستخدام GCC 5 أو إصدار أحدث، حدِّد -D_GLIBCXX_USE_CXX11_ABI=0.

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