بدء استخدام Firebase في C++

1. نظرة عامة

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

جولة إرشادية

إذا أردت الاطّلاع على هذا الدرس التطبيقي حول الترميز مع المؤلّفين، شاهِد هذا الفيديو:

أهداف الدورة التعليمية

• كيفية إضافة Firebase إلى لعبة Android المستندة إلى CMake
• كيفية تحديد تبعيات C++ وGradle التي تحتاج إليها
• كيفية تسجيل أحداث "إحصاءات Google"
• كيفية تصحيح أخطاء أحداث الإحصاءات
• كيفية مشاركة لعبتك مع "توزيع التطبيقات"

المتطلبات

• استوديو Android
• الرمز النموذجي
• جهاز اختبار أو محاكي مزوّد بـ "خدمات Google Play"

2. الحصول على الرمز النموذجي

تنزيل أو استخراج من GitHub:

git clone https://github.com/FirebaseExtended/cmake-way-for-firebase.git

تنزيل حزمة تطوير البرامج (SDK) لمنصة Firebase

نظام التشغيل MacOS/Linux:

sh download.sh

نظام التشغيل Windows (من PowerShell):

./download.ps1

يمكنك أيضًا تنزيل حزمة تطوير البرامج (SDK) يدويًا. في حال إجراء ذلك، يجب استخراج Firebase C++ SDK إلى /third_party بحيث يحتوي مجلد باسم firebase_cpp_sdk على الجذر CMakeLists.txt من Firebase SDK.

3- تشغيل اللعبة التجريبية

أولاً، شغِّل اللعبة التجريبية وتأكَّد من أنّ كل شيء يعمل. إنّها لعبة بسيطة لا نهاية لها تتضمّن مستوى تم إنشاؤه إجرائيًا وزرًا واحدًا للقفز.

1. انقر على "ملف" (File) > "جديد" (New) > "استيراد مشروع" (Import Project) (أو انقر على "استيراد مشروع" (Import Project) من شاشة البداية)
2. افتح مجلد proj.android/ المضمّن في المستودع

هذا مشروع Cocos2dx وليس مشروع Android عاديًا. من المفترض عادةً أن يظهر ملف build.gradle في جذر هذا المستودع، ولكنّه يقع ضمن proj.android/، لذا يمكن أن يكون لكل نظام تشغيل مستهدف عملية إنشاء مستقلة.

3. [اختياري] افتح proj.android/gradle.properties وابحث عن PROP_APP_ABI. يمكنك إزالة جميع البنى باستثناء البنية المستهدَفة لتقليل أوقات الإنشاء. سيتم إنشاء PROP_APP_ABI=x86 فقط للمحاكي، وسيتم إنشاء PROP_APP_ABI=armeabi-v7a لمعظم الهواتف
4. انقر على الزر "تصحيح الأخطاء" لإنشاء اللعبة وتشغيلها. سيستغرق ذلك بعض الوقت لإنشاء محرّك ألعاب Cocos2dx.

يمكن للمطوّرين ذوي الخبرة في Cocos2dx اختيار استخدام cocos run -p android إذا كان لديك Cocos2dx CLI مثبّت. قد يفضّل مطوّرو تطبيقات Android استخدام ./gradlew installDebug. في هذا البرنامج التعليمي، سأفترض أنّك تستخدم "استوديو Android" لتطوير التطبيق وإنشائه ونشره.

4. إعداد "وحدة تحكّم Firebase"

1. أنشِئ مشروعًا جديدًا في وحدة تحكّم Firebase.
2. أدخِل اسمًا، مثل "سباق المصاصات".
3. تفعيل "إحصاءات Google"
4. إضافة حساب على "إحصاءات Google" أو إنشاؤه
5. إضافة تطبيق Android جديد إلى مشروعك
6. أضِف com.firebase.popsiclerunner كاسم للحزمة.

لن تحتاج إلى SHA-1 لهذا الدرس التطبيقي حول الترميز.

7. نزِّل ملف google-services.json وانسخه إلى proj.android/app

ستصنّف العديد من خدمات استضافة المصادر google-services.json على أنّها "أسرار" إذا حاولت إرسالها، ولكن لا يتضمّن هذا الملف أي أسرار فعلية (في لعبة جاهزة للإصدار، من السهل استرداد محتوى هذا الملف). ومع ذلك، يجب توخّي الحذر إذا كنت تخطّط لإرسالها إلى مستودع رموز مصدرية متاح للجميع، إذ سيكون من الأسهل بكثير العثور على قواعد البيانات أو حِزم التخزين في السحابة الإلكترونية قبل كتابة قواعد أمان قوية إذا تم نشر هذا الملف بشكل علني.

8. تجاهل التعليمات المقدَّمة لإضافة حزمة تطوير البرامج (SDK) لمنصة Firebase وانقر على "التالي".
9. يمكنك النقر على "تخطّي هذه الخطوة" عندما يُطلب منك تأكيد عملية التثبيت.

5- إضافة Firebase إلى لعبتك

إضافة حزمة تطوير البرامج (SDK) لمنصة Firebase إلى ملف CMakeLists.txt

افتح مستوى الجذر CMakeLists.txt. يجب أن يتضمّن الرمز التالي بالقرب من أعلى الصفحة

CMakeLists.txt

cmake_minimum_required(VERSION 3.6)

set(APP_NAME popsiclerunner)

project(${APP_NAME})

وأضِف الأسطر التالية إلى نهاية ملف CMakeLists.txt

CMakeLists.txt

add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/third_party/firebase_cpp_sdk)
target_link_libraries(${APP_NAME} firebase_analytics firebase_app)

يتضمّن add_subdirectory حزمة تطوير البرامج (SDK) لنظام Firebase بلغة C++، ويتيح استخدامها في هذه اللعبة.

target_link_libraries يربط اللعبة بمكتبات C++‎ في Firebase المصمَّمة لنظام التشغيل Android.

استخدِم هذا الجدول لمعرفة المكتبات التي تحتاج إليها لكل ميزة تريد استخدامها. هذه هي الطريقة التي عرفتُ بها أنّ firebase_analytics تتطلّب firebase_app.

تثبيت المكوّن الإضافي "خدمات Google"

لربط حزمة تطوير البرامج (SDK) من Firebase، يجب إضافة المكوّن الإضافي "خدمات Google" إلى نص برمجة Gradle. لإجراء ذلك، افتح ملف مستوى المشروع build.gradle (يقع هذا الملف في المجلد proj.android). وأضِف classpath 'com.google.gms:google-services:4.3.3' كعنصر تابع لبرنامج buildscript.

build.gradle

buildscript {
    repositories {
        google()
        jcenter()
    }

    dependencies {
        classpath 'com.android.tools.build:gradle:4.0.1'

        // NOTE: Do not place your application dependencies here; they belong
        // in the individual module build.gradle files
        classpath 'com.google.gms:google-services:4.3.3'  // Google Services plugin
    }
}

بعد ذلك، أضِف المكوّن الإضافي إلى ملف build.gradle على مستوى الوحدة (يقع هذا الملف في مجلد proj.android/app). أضِف apply plugin: 'com.google.gms.google-services' أسفل apply plugin: 'com.android.application':

build.gradle

apply plugin: 'com.android.application'
apply plugin: 'com.google.gms.google-services'  // Google Services plugin

تحديد موقع حزمة تطوير البرامج (SDK) الخاصة بلغة C++‎ في Gradle

لإخبار Gradle بمكان العثور على حزمة تطوير البرامج (SDK) للغة C++ في Firebase، أضِف الأسطر التالية إلى أسفل الملف settings.gradle.

settings.gradle

gradle.ext.firebase_cpp_sdk_dir = "$settingsDir/../third_party/firebase_cpp_sdk/"
includeBuild "$gradle.ext.firebase_cpp_sdk_dir"

يجب أن يشير ذلك إلى الموقع الجغرافي نفسه الذي أشارت إليه استدعاءات add_subdirectory في CMake.

إضافة حِزم Android التابعة

لربط التبعيات في Android الخاصة بـ Firebase، افتح ملف Gradle على مستوى الوحدة popsicle_runner (في proj.android/app/build.gradle) وأضِف ما يلي قبل القسم dependences { المعتاد في النهاية مباشرةً:

build.gradle

apply from: "$gradle.firebase_cpp_sdk_dir/Android/firebase_dependencies.gradle"
firebaseCpp.dependencies {
    analytics
}

يتم إنشاء كل حزمة تطوير برامج (SDK) بلغة C++‎ استنادًا إلى إصدار معيّن من حزمة تطوير البرامج (SDK) لنظام التشغيل Android. ‫firebaseCpp.dependencies هي دالة ملائمة ستعثر على تبعيات Gradle الضرورية وتضبطها لضمان توفّر إعدادات تم التحقّق منها.

‫AndroidX وJetifier

أضِف توافق AndroidX وJetifier من خلال فتح gradle.properties وإضافة ما يلي إلى النهاية:

gradle.properties

android.useAndroidX = true
android.enableJetifier = true

إعداد Firebase في لعبتك

ابدأ بإعداد Firebase في اللعبة من خلال فتح Classes/AppDelegate.cpp. أضِف توجيهات #include التالية إلى الأعلى:

AppDelegate.cpp

#include <firebase/app.h>
#include <firebase/analytics.h>

بعد ذلك، أضِف App::Create وأعِد إعداد ميزات Firebase التي تحتاج إليها. لإجراء ذلك، ابحث عن AppDelegate::applicationDidFinishLaunching وأضِف هذا الرمز قبل auto scene = MainMenuScene::createScene():

AppDelegate.cpp

{
    using namespace firebase;
    auto app = App::Create(JniHelper::getEnv(), JniHelper::getActivity());
    analytics::Initialize(*app);
}

أفضّل استخدام كتلة مجهولة الهوية {} لحصر نطاق عبارات using مثل using namespace firebase;.

إذا صحّحت أخطاء اللعبة وأعدت تحميل لوحة بيانات Firebase، من المفترض أن يظهر مستخدم جديد بعد دقيقة أو نحو ذلك.

6. إضافة "إحصاءات Google"

حتى في المراحل الأولى من التطوير، تُعدّ الإحصاءات أداة مفيدة لقياس كيفية تفاعل مختبِري الإصدار التجريبي مع اللعبة. هناك بعض الإحصاءات التي يتم جمعها تلقائيًا، مثل تقارير الاحتفاظ بالمستخدمين، ولكن من المفيد إضافة أحداث مخصّصة مصمّمة خصيصًا للعبتك.

نقطة البداية الجيدة هي تسجيل حدث إحصائي عندما يبدأ اللاعب مستوى معيّنًا. يمكننا استخدام عدد أحداث بدء المستوى لمعرفة عدد المرات التي قد يعيد فيها اللاعب تشغيل اللعبة في جلسة واحدة.

سنسجّل أيضًا حدثًا عند موت اللاعب مع المسافة التي قطعها. سيسمح لنا ذلك بمعرفة كيف تؤثر التغييرات التي نجريها في مدة الجلسة الواحدة، وسيساعدنا في تحديد ما إذا كان اللاعبون يفضّلون لعبة أقصر وأصعب أو أطول وأسهل.

إضافة عناوين "إحصاءات Google"

افتح Classes/PopsicleScene.cpp وأضِف عناوين Firebase في الأعلى حتى نتمكّن من إجراء طلبات الإحصاءات.

PopsicleScene.cpp

#include <firebase/analytics.h>
#include <firebase/analytics/event_names.h>

تسجيل حدث "بدء المستوى"

لتسجيل حدث عند عرض هذا المشهد من خلال Cocos2dx Director، ابحث عن الدالة PopsicleScene::onEnter() التي تم إنشاؤها. أدخِل الرمز التالي لتسجيل الحدث Level Start هنا:

PopsicleScene.cpp

using namespace firebase;
analytics::LogEvent(analytics::kEventLevelStart);

تسجيل حدث "نهاية المستوى"

لمعرفة مدى تقدّم اللاعب، لننسخ حدث "نهاية المستوى" مع مدى تقدّم اللاعب عندما يموت أخيرًا. لإجراء ذلك، ابحث عن PopsicleScene::gameOver() وأضِفه إلى نهاية حظر if(!_gameOver) { قبل ضبط _gameOver = true;:

PopsicleScene.cpp

{
    using namespace firebase;
    analytics::LogEvent(analytics::kEventLevelEnd, "distance", _lastDistance);
}

‫kEventLevelEnd هو حدث نهاية المستوى. في حين أنّ "distance" هي "مَعلمة خاصة بالحدث". نضيف هنا المسافة الأخيرة التي تم تسجيلها، وهي تقدير جيد للمسافة التي قطعها اللاعب قبل أن يموت.

7. أحداث الاختبار

يمكنك النقر على "تصحيح الأخطاء" الآن، ولكن سيستغرق الأمر بعض الوقت قبل أن يتم تسجيل أي أحداث في لوحة بيانات "إحصاءات Google". هناك سببان لذلك: 1) يتم تجميع الأحداث وتحميلها مرة واحدة كل ساعة تقريبًا للحفاظ على البطارية، و2) يتم إنشاء التقارير كل 24 ساعة.

تتوفّر آليات يمكنك من خلالها عرض الأحداث بشكل أسرع. إذا تمّ تصنيف حدث على أنّه حدث إحالة ناجحة، سيتمّ تسجيله في الوقت الفعلي تقريبًا في العديد من الحالات. يمكنك أيضًا ضبط "إحصاءات Google" للتصدير إلى BigQuery، حيث لن يكون الجدول اليومي قديمًا إلا بحوالي 4 ساعات.

تفعيل "وضع تصحيح الأخطاء"

سيظلّ بإمكانك تصحيح أخطاء أحداث "إحصاءات Google" من خلال تفعيل وضع تصحيح الأخطاء على جهازك.

تأكَّد أولاً من تثبيت Android Debug Bridge (ADB) وإعداده. يجب أن يؤدي كتابة adb devices إلى عرض الجهاز الذي ستجري الاختبار عليه:

$ adb devices
List of devices attached
emulator-5554   device

بعد ذلك، شغِّل أمر adb shell التالي:

adb shell setprop debug.firebase.analytics.app com.firebase.popsiclerunner

يؤدي ذلك إلى توجيه "إحصاءات Firebase" لتسجيل الأحداث على الفور، وسيتم استبعادها تلقائيًا من تقاريرك العادية لتجنُّب إفساد أحداثك المباشرة عند الاختبار. إذا أردت التراجع عن هذا الإجراء لاحقًا، ما عليك سوى كتابة:

adb shell setprop debug.firebase.analytics.app .none.

عرض الأحداث

افتح "DebugView" في "وحدة تحكّم Firebase"

انقر على "تصحيح الأخطاء" وشغِّل اللعبة. من المفترض أن تظهر الأحداث الجديدة فور وقوعها في اللعبة تقريبًا.

إذا وسّعت الحدث level_end، ستظهر لك أيضًا المَعلمة المخصّصة "المسافة" التي سجّلتها.

عندما يظهر الحدث level_end في تقارير الأحداث، لن يتم تلقائيًا تسجيل المسافة. عليك اختيار "الأحداث" ، ثمّ البحث عن level_end، ثمّ توسيع النقاط الثلاث على الجانب الأيسر ، ثمّ اختيار تعديل إعداد التقارير عن المَعلمات لإضافتها كمَعلمة في تقارير الأحداث. بعد إجراء ذلك، يمكنك الاطّلاع على إحصاءات مثل متوسط المسافة التي يقطعها اللاعبون في كل مباراة.

8. العثور على مختبِرين

بعد ذلك، عليك عرض لعبتك على الآخرين، سواء كانوا من داخل الاستوديو أو من بين الأصدقاء المقرّبين أو من المنتدى. توفّر لك خدمة Firebase App Distribution طريقة رائعة لدعوة اللاعبين إلى لعب لعبتك.

إنشاء برنامج ثنائي مستقل

عليك أولاً إنشاء حِزمة APK مستقلة لمشاركتها من خلال "إنشاء" > "إنشاء حِزم التطبيقات/حِزم APK" > "إنشاء حِزم APK"

إذا سبق لك تغيير فلتر ABI، تذكَّر الرجوع إلى gradle.properties وتغيير PROP_APP_ABI لتضمين أي جهاز تخطّط للاختبار عليه:

PROP_APP_ABI=armeabi-v7a:arm64-v8a:x86

سيفتح "استوديو Android" مربّع حوار يتيح لك تحديد موقع الملف الذي تم إنشاؤه. إذا فاتك ذلك، يمكنك النقر على "سجلّ الأحداث" للحصول على الرابط مرة أخرى.

تحميل التطبيق إلى Firebase App Distribution

1. افتح "توزيع التطبيقات" وانقر على "البدء"
2. اسحب ملف ‎ .apk وأفلِته في المربّع الذي يظهر فيه "اسحب أي ملف ‎ .apk هنا لإنشاء إصدار جديد".
3. أدخِل عنوان بريدك الإلكتروني كأول مختبِر.
4. انقر على "التالي".
5. إضافة وصف والنقر على "توزيع"

دعوة مختبِرين

بدلاً من الاضطرار إلى إدخال كل عنوان بريد إلكتروني يدويًا، يمكنك إنشاء رابط دعوة. عند جذب مستخدم باستخدام رابط الدعوة هذا، يمكنك أيضًا إضافته إلى مجموعة من المختبِرين. سيسمح لك ذلك بفصل المختبِرين الداخليين عن المختبِرين الخارجيين، على سبيل المثال.

1. انقر على "المختبِرون والمجموعات" .
2. أنشئ مجموعة جديدة ، وأعطِها اسمًا مثل "مختبِرو Android".
3. انقر على "روابط الدعوة"
4. انقر على "رابط دعوة جديد".
5. اضبط المجموعة هنا من القائمة المنسدلة.
6. انقر على "إنشاء رابط".
7. انقر على "نسخ الرابط" وشارِكه بالطريقة التي تريدها

9- تهانينا

لقد نجحت في إضافة إحصاءات إلى لعبتك المستندة إلى C++، ودعوت بعض الأصدقاء للعب، وتعرف كيفية العثور على مكتبات Firebase وربطها في نظام تصميم مستند إلى CMake وGradle، وهو نظام شائع في تطوير تطبيقات Android.

المواضيع التي تناولناها

• كيفية إضافة Firebase إلى لعبة Android المستندة إلى CMake
• كيفية تحديد تبعيات C++ وGradle التي تحتاج إليها
• كيفية تسجيل أحداث "إحصاءات Google"
• كيفية تصحيح أخطاء أحداث الإحصاءات
• كيفية مشاركة لعبتك مع "توزيع التطبيقات"

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

• جرِّب تسجيل دخول مستخدم بشكل مجهول وحفظ أعلى نتيجة له في قاعدة بيانات الوقت الفعلي.
• تسجيل أحداث "إحصاءات Play" في لعبتك
• جرِّب إضافة إحصاءات إلى لعبة iOS.

مزيد من المعلومات

• اطّلِع على قائمة الأحداث الخاصة بالألعاب وفكِّر في كيفية دمجها في لعبتك.