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

عزِّز قدرات ألعاب C++ الخاصة بك باستخدام حزم SDK لـ Firebase C++ التي توفر واجهة C++ فوق حزم Firebase SDK.

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

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

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

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

  • ثبِّت المحرّر أو IDE المفضّل لديك، مثل "استوديو Android" أو IntelliJ أو VS Code.

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

  • تأكد من أن مشروعك يلبي هذه المتطلبات:

    • استهداف المستوى 19 من واجهة برمجة التطبيقات (KitKat) أو أعلى

    • تستخدم 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++ في بيئة تطوير متكاملة (IDE)، ثم أضف ملف التهيئة إلى مشروعك:

  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. تطبيق المكوّن الإضافي لنظام Gradle لخدمات Google:

        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 المطلوب استخدامها في تطبيقك.

    تفعيل الإحصاءات 

    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
}

    عدم تفعيل الإحصاءات 

    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 المطلوب استخدامها في تطبيقك.

    تفعيل الإحصاءات 

    # 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}")

    عدم تفعيل الإحصاءات 

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

    ستعرض سجلات جهازك رسالة تحقق من Firebase باكتمال عملية الإعداد. إذا شغّلت تطبيقك على محاكي لديه إمكانية الوصول إلى الشبكة، ستُعلمك وحدة تحكم Firebase باكتمال اتصال التطبيق.

اكتملت عملية الإعداد تم تسجيل تطبيق C++ وإعداده لاستخدام خدمات Firebase.

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

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

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

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

منتج Firebase مراجع المكتبة
(firebaseCpp.dependencies
لملف build.gradle)		 مراجع المكتبة
(firebase_libs
لملف CMakeLists.txt)
AdMob admob firebase_admob
(مطلوب) firebase_analytics
(مطلوب) firebase_app
إحصاءات Google analytics firebase_analytics
(مطلوب) firebase_app
فحص التطبيقات appCheck firebase_app_check
(مطلوب) firebase_app
المصادقة auth firebase_auth
(مطلوب) firebase_app
Cloud Firestore firestore firebase_firestore
(مطلوب) firebase_auth
(مطلوب) firebase_app
الوظائف السحابية functions firebase_functions
(مطلوب) firebase_app
المراسلة عبر السحابة الإلكترونية messaging firebase_messaging
(موصى بها) firebase_analytics
(مطلوبة) firebase_app
التخزين في السحابة الإلكترونية 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 موارد يمكنك تضمينها في مشروعك. يطبِّق هذا النص البرمجي عملية التحويل نفسها التي يجريها المكوّن الإضافي Gradle لخدمات Google Play عند إنشاء تطبيقات Android.

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

ProGuard

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

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

على سبيل المثال، في نظام Gradle، إذا كنت تستخدم "إحصاءات Google"، سيبدو ملف 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 غير مطلوب (عادةً)
إحصاءات Google غير مطلوبة
المصادقة مطلوب
Cloud Firestore مطلوب
وظائف السحابة الإلكترونية مطلوب
خدمة المراسلة عبر السحابة الإلكترونية مطلوب
Cloud Storage مطلوب
الروابط الديناميكية مطلوب
قاعدة بيانات الوقت الفعلي مطلوب
الإعداد عن بُعد مطلوب

AdMob وخدمات Google Play

يمكن أن تعمل معظم إصدارات حزمة "SDK لإعلانات Google على الأجهزة الجوّالة" لنظام التشغيل Android بشكل صحيح بدون "خدمات 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.

إعداد سير عمل أجهزة كمبيوتر سطح المكتب (إصدار تجريبي)

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

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

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

منتج Firebase مراجع المكتبة (باستخدام أداة CMake)
فحص التطبيقات firebase_app_check
(مطلوب) firebase_app
المصادقة firebase_auth
(مطلوب) firebase_app
Cloud Firestore firebase_firestore
firebase_auth
firebase_app
الوظائف السحابية firebase_functions
(مطلوب) firebase_app
التخزين في السحابة الإلكترونية firebase_storage
(مطلوب) firebase_app
قاعدة بيانات الوقت الفعلي firebase_database
(مطلوب) firebase_app
الإعداد عن بُعد firebase_remote_config
(مطلوب) firebase_app

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

قاعدة بيانات الوقت الفعلي لسطح المكتب

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

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

مكتبات Windows

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

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

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

عند إنشاء تطبيقات سطح مكتب C++ على Windows، قم بربط مكتبات Windows SDK التالية بمشروعك. راجع وثائق برنامج التجميع لمزيد من المعلومات.

مكتبة Firebase C++ ملحقات مكتبة SDK لنظام التشغيل Windows
فحص التطبيقات advapi32, ws2_32, crypt32
المصادقة advapi32, ws2_32, crypt32
Cloud Firestore advapi32, ws2_32, crypt32, rpcrt4, ole32, shell32
وظائف السحابة الإلكترونية 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.

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

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

للحصول على مزيد من المعلومات، يمكنك الرجوع إلى وثائق برنامج التجميع.

مكتبات Linux

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

تجدر الإشارة إلى أنّه تمّ اختبار مكتبات Linux باستخدام الإصدارات 4.8.0 من GCC وGCC 7.2.0 وClang 5.0 على نظام التشغيل Ubuntu.

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

الخطوات اللاحقة