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

1. نظرة عامة

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

جولة تفصيلية

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

ما ستتعرَّف عليه

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

المتطلبات

• استوديو 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) يدويًا. في حال تنفيذ ذلك، يجب استخراج حزمة تطوير البرامج (SDK) لمنصة Firebase C++ إلى /third_party كي يتضمّن المجلد الذي يحمل اسم firebase_cpp_sdk الجذر CMakeLists.txt من حزمة تطوير البرامج (SDK) لمنصة Firebase.

3- تشغيل نموذج اللعبة

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

1. حدد ملف > جديد > استيراد مشروع (أو اختيار "استيراد مشروع" من شاشة البداية)
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. أضِف اسمًا له، مثل "لعبة Popsicle Runner"
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' كتبعية خاصة بالنص البرمجي.

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

تحديد موقع حزمة C++ SDK في Gradle

لإعلام Gradle بمكان العثور على حزمة تطوير البرامج (SDK) لـ Firebase C++، أضِف الأسطر التالية إلى أسفل ملف 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++ وفقًا لإصدار معيّن من حزمة Android SDK. 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، ابحث عن الدالة التي تم استئصالها 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" طريقة رائعة لدعوة اللاعبين لتشغيل لعبتك.

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

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

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

PROP_APP_ABI=armeabi-v7a:arm64-v8a:x86

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

التحميل إلى Firebase App Distribution

1. افتح App Distribution وانقر على "البدء" (Get Started)
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"
• كيفية تصحيح أخطاء أحداث الإحصاءات
• كيفية مشاركة لعبتك باستخدام App Distribution

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

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

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

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