با Firebase در C++

۱. مرور کلی

در این آزمایشگاه کد، یاد خواهید گرفت که چگونه SDK بازی‌های C++ Firebase را در یک بازی اندروید نمونه با استفاده از Google Analytics به عنوان مثال ادغام کنید. شما قادر خواهید بود ویژگی‌های مورد نیاز خود را اضافه کنید، برخی از منطق‌های تحلیلی اولیه را برای اندازه‌گیری پیشرفت بازیکن خود ادغام کنید و بازی را با آزمایش‌کنندگان به اشتراک بگذارید تا بازخورد اولیه را دریافت کنید.

پیاده روی

اگر می‌خواهید با نویسندگان این آزمایشگاه کد آشنا شوید، این ویدیو را تماشا کنید:

آنچه یاد خواهید گرفت

• چگونه Firebase را به بازی مبتنی بر CMake اندروید خود اضافه کنیم؟
• چگونه بفهمیم به کدام وابستگی‌های C++ و Gradle نیاز داریم.
• نحوه ثبت رویدادهای آنالیتیکس
• نحوه اشکال‌زدایی رویدادهای تحلیلی.
• نحوه اشتراک گذاری بازی خود با App Distribution

آنچه نیاز دارید

• اندروید استودیو
• کد نمونه
• یک دستگاه یا شبیه‌ساز آزمایشی با سرویس‌های گوگل پلی

۲. کد نمونه را دریافت کنید

پرداخت یا دانلود از گیت‌هاب :

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

دانلود کیت توسعه نرم‌افزار فایربیس (Firebase SDK)

مک او اس/لینوکس:

sh download.sh

ویندوز (از طریق پاورشل):

./download.ps1

همچنین می‌توانید SDK را به صورت دستی دانلود کنید . در این صورت، SDK مربوط به Firebase C++ باید در مسیر /third_party استخراج شود، به طوری که پوشه‌ای به نام firebase_cpp_sdk حاوی فایل ریشه CMakeLists.txt از SDK مربوط به Firebase باشد.

۳. بازی نمونه را اجرا کنید

ابتدا، بازی نمونه را اجرا کنید و مطمئن شوید که همه چیز درست کار می‌کند. این یک بازی دونده بی‌نهایت ساده با یک مرحله تولید شده به صورت رویه‌ای و یک دکمه برای پرش است.

1. فایل > جدید > وارد کردن پروژه را انتخاب کنید (یا از صفحه شروع، گزینه وارد کردن پروژه را انتخاب کنید)
2. پوشه proj.android/ موجود در مخزن را باز کنید.

این یک پروژه Cocos2dx است نه یک پروژه معمولی اندروید. معمولاً انتظار دارید یک فایل build.gradle را در ریشه این مخزن ببینید، اما این فایل در مسیر proj.android/ قرار دارد، بنابراین هر سیستم عامل هدف می‌تواند فرآیند ساخت مستقل خود را داشته باشد.

3. [اختیاری] proj.android/gradle.properties باز کنید و PROP_APP_ABI اصلاح کنید. می‌توانید همه معماری‌ها به جز معماری هدف خود را حذف کنید تا زمان ساخت کاهش یابد. PROP_APP_ABI=x86 فقط برای شبیه‌ساز ساخته می‌شود. PROP_APP_ABI=armeabi-v7a برای اکثر گوشی‌ها ساخته می‌شود.
4. روی دکمه اشکال‌زدایی کلیک کنید برای ساخت و اجرای بازی. این کار برای ساخت موتور بازی Cocos2dx زمان می‌برد.

توسعه‌دهندگان باتجربه Cocos2dx در صورت نصب رابط خط فرمان Cocos2dx ، می‌توانند از دستور cocos run -p android استفاده کنند. توسعه‌دهندگان اندروید ممکن است ./gradlew installDebug ترجیح دهند. در این آموزش، فرض می‌کنم که شما از اندروید استودیو برای توسعه، ساخت و استقرار استفاده می‌کنید.

۴. تنظیمات کنسول فایربیس

1. یک پروژه جدید در کنسول Firebase ایجاد کنید.
2. یه اسم بهش بده مثل "دونده بستنی یخی"
3. فعال کردن آنالیتیکس
4. یک حساب تحلیلی اضافه یا ایجاد کنید
5. یک برنامه اندروید جدید به پروژه خود اضافه کنید
6. com.firebase.popsiclerunner به عنوان نام بسته خود اضافه کنید.

برای این آزمایشگاه کد به SHA-1 نیاز نخواهید داشت

7. فایل google-services.json را دانلود کنید و آن را در proj.android/app کپی کنید.

بسیاری از سرویس‌های میزبانی منبع، اگر بخواهید google-services.json را commit کنید، آن را به عنوان "راز" علامت‌گذاری می‌کنند، اما هیچ چیز در این فایل یک راز واقعی نیست (در یک بازی حمل و نقل، بازیابی محتوای این فایل امری بدیهی است). اگر قصد دارید آن را در یک مخزن کد منبع عمومی commit کنید، همچنان باید احتیاط کنید - اگر این فایل به صورت عمومی منتشر شود، پیدا کردن پایگاه‌های داده یا مخازن ذخیره‌سازی ابری شما قبل از اینکه قوانین امنیتی قوی بنویسید، بسیار آسان‌تر خواهد بود.

8. دستورالعمل‌های داده شده برای اضافه کردن Firebase SDK را نادیده بگیرید و روی بعدی کلیک کنید.
9. وقتی از شما خواسته شد نصب خود را تأیید کنید، می‌توانید روی «رد شدن از این مرحله» کلیک کنید.

۵. فایربیس را به بازی خود اضافه کنید

Firebase SDK را به 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 شامل Firebase C++ SDK است و آن را برای این بازی در دسترس قرار می‌دهد.

target_link_libraries بازی را با کتابخانه‌های C++ فایربیس که برای اندروید ساخته شده‌اند، متصل می‌کند.

از این جدول برای فهمیدن اینکه برای هر ویژگی که می‌خواهید استفاده کنید به کدام کتابخانه‌ها نیاز دارید استفاده کنید. اینگونه بود که فهمیدم firebase_analytics به firebase_app نیاز دارد.

افزونه سرویس‌های گوگل را اضافه کنید

برای اتصال Firebase SDK، باید افزونه Google Services را به اسکریپت ساخت gradle خود اضافه کنید. برای انجام این کار، فایل build.gradle سطح پروژه را باز کنید (این فایل در پوشه proj.android قرار دارد). و classpath 'com.google.gms:google-services:4.3.3' را به عنوان یک وابستگی ساخت اسکریپت اضافه کنید.

ساخت.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'

ساخت.gradle

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

SDK مربوط به C++ را در Gradle پیدا کنید

برای اینکه به Gradle بگویید کجا می‌تواند Firebase C++ SDK را پیدا کند، خطوط زیر را به انتهای فایل settings.gradle اضافه کنید.

تنظیمات.gradle

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

این باید به همان مکانی اشاره کند که فراخوانی add_subdirectory در CMake به آن اشاره می‌کرد.

وابستگی‌های اندروید را اضافه کنید

برای اتصال وابستگی‌های اندروید برای Firebase، فایل gradle سطح ماژول را برای popsicle_runner (در proj.android/app/build.gradle ) باز کنید و موارد زیر را درست قبل از بخش معمول dependences { در انتها اضافه کنید:

ساخت.gradle

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

هر SDK مربوط به C++ بر اساس یک نسخه خاص از SDK اندروید ساخته شده است. firebaseCpp.dependencies یک تابع کمکی است که وابستگی‌های لازم برای gradle را کشف و پیکربندی می‌کند تا از پیکربندی تأیید شده اطمینان حاصل شود.

اندروید ایکس و جتیفایر

با باز کردن gradle.properties و اضافه کردن این کد به انتهای آن، پشتیبانی از AndroidX و Jetifier را اضافه کنید:

خواص gradle

android.useAndroidX = true
android.enableJetifier = true

مقداردهی اولیه فایربیس در بازی شما

با باز کردن 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 را به‌روزرسانی کنید، باید بعد از حدود یک دقیقه یک کاربر جدید ظاهر شود.

۶. اضافه کردن تجزیه و تحلیل

حتی در اوایل توسعه، تجزیه و تحلیل ابزاری مفید برای سنجش نحوه تعامل آزمایش‌کنندگان بتا با بازی است. برخی از تجزیه و تحلیل‌ها به صورت خودکار جمع‌آوری می‌شوند - مانند گزارش‌های نگهداری - اما اضافه کردن رویدادهای سفارشی متناسب با بازی خاص شما مفید است.

یک نقطه شروع خوب، ثبت یک رویداد تحلیلی هنگام شروع یک مرحله توسط بازیکن است. می‌توانیم از تعداد رویدادهای شروع مرحله استفاده کنیم تا ببینیم یک بازیکن چند بار ممکن است در یک جلسه بازی را دوباره انجام دهد.

ما همچنین رویدادی را که بازیکن در آن می‌میرد، به همراه میزان پیشروی او ثبت خواهیم کرد. این به ما اجازه می‌دهد ببینیم تغییراتی که اعمال می‌کنیم چگونه مدت زمان یک جلسه را تغییر می‌دهد و به ما کمک می‌کند تا تعیین کنیم که آیا بازیکنان یک بازی کوتاه‌تر/سخت‌تر می‌خواهند یا طولانی‌تر/آسان‌تر.

اضافه کردن هدرهای تحلیلی

Classes/PopsicleScene.cpp باز کنید و هدرهای Firebase را به بالای آن اضافه کنید تا بتوانیم فراخوانی‌های تحلیلی انجام دهیم.

صحنه پاپسیکل.cpp

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

ثبت رویداد شروع سطح

برای ثبت رویدادی که این صحنه توسط Cocos2dx Director اجرا می‌شود، تابع PopsicleScene::onEnter() را که در کد آن نامی وجود ندارد، پیدا کنید. کد زیر را برای ثبت رویداد Level Start در اینجا وارد کنید:

صحنه پاپسیکل.cpp

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

ثبت رویداد پایان سطح

برای اینکه ببینیم یک بازیکن چقدر خوب عمل می‌کند، بیایید یک رویداد پایان سطح (Level End) را ثبت کنیم که نشان می‌دهد بازیکن تا زمان مرگ چقدر پیشرفت کرده است. برای انجام این کار، PopsicleScene::gameOver() را پیدا کنید و این را به انتهای بلوک if(!_gameOver) { قبل از تنظیم _gameOver = true; اضافه کنید:

صحنه پاپسیکل.cpp

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

kEventLevelEnd رویداد پایان مرحله است. در حالی که "distance" یک "پارامتر رویداد" است. ما در اینجا آخرین مسافت ثبت شده را اضافه می‌کنیم که تقریب خوبی برای مسافتی است که یک بازیکن قبل از مرگ طی کرده است.

۷. آزمایش رویدادها

می‌توانید روی اشکال‌زدایی کلیک کنید الان، اما گزارش شدن هر رویدادی در داشبورد آنالیتیکس زمان می‌برد. دو دلیل برای این امر وجود دارد: ۱) رویدادها دسته‌بندی شده و تقریباً هر ساعت یک بار آپلود می‌شوند تا باتری ذخیره شود و ۲) گزارش‌ها هر ۲۴ ساعت یکبار ایجاد می‌شوند.

مکانیسم‌هایی وجود دارد که می‌توانید رویدادها را سریع‌تر مشاهده کنید. اگر رویدادی به عنوان یک رویداد تبدیل علامت‌گذاری شود، تحت بسیاری از شرایط تقریباً به صورت آنی گزارش می‌شود. همچنین می‌توانید گوگل آنالیتیکس را طوری پیکربندی کنید که به BigQuery خروجی دهد ، که در آن جدول روزانه فقط حدود ۴ ساعت از تاریخ انقضا عقب خواهد بود.

فعال کردن حالت اشکال‌زدایی

هنوز هم می‌توان با قرار دادن دستگاه در حالت اشکال‌زدایی، رویدادهای آنالیتیکس را اشکال‌زدایی کرد.

ابتدا مطمئن شوید که 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 Analytics می‌گوید که رویدادها را فوراً ثبت کند و به طور خودکار آنها را از گزارش‌های عادی شما حذف می‌کند تا از آلوده شدن رویدادهای زنده شما هنگام آزمایش جلوگیری شود. اگر می‌خواهید این اقدام را بعداً لغو کنید، کافیست بنویسید:

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

مشاهده رویدادها

"DebugView" را در کنسول Firebase خود باز کنید.

روی اشکال‌زدایی کلیک کنید و بازی را انجام دهید. تقریباً بلافاصله پس از وقوع رویدادهای جدید در بازی، باید شاهد ظاهر شدن آنها باشید.

اگر رویداد level_end را باز کنید، پارامتر سفارشی "distance" که ثبت کرده‌اید را نیز خواهید دید.

وقتی رویداد level_end در نهایت وارد گزارش‌های رویدادهای شما شود، به طور پیش‌فرض مسافت را ثبت نمی‌کند. شما باید Events را انتخاب کنید. ، level_end را پیدا کنید، سه نقطه سمت راست را باز کنید ، و انتخاب کنید گزارش پارامتر را ویرایش کنید تا آن را به عنوان یک پارامتر در گزارش‌های رویداد خود اضافه کنید. پس از انجام این کار، می‌توانید آمارهایی مانند میانگین مسافت بازیکنان خود در هر بازی را مشاهده کنید.

۸. پیدا کردن آزمایش‌کنندگان

در مرحله بعد، چه در داخل استودیوی شما، چه در بین دوستان نزدیک یا از جامعه شما، باید بازی خود را تماشا کنید. توزیع برنامه Firebase راهی عالی برای دعوت از بازیکنان برای انجام بازی شما فراهم می‌کند.

ساخت یک فایل باینری مستقل

ابتدا یک APK مستقل برای اشتراک‌گذاری از مسیر Build > Build Bundles(s) / APK(s) > Build APK(s) بسازید.

اگر قبلاً فیلتر ABI خود را تغییر داده‌اید، به یاد داشته باشید که به gradle.properties برگردید و PROP_APP_ABI طوری تغییر دهید که شامل هر دستگاهی باشد که قصد دارید روی آن آزمایش کنید:

PROP_APP_ABI=armeabi-v7a:arm64-v8a:x86

اندروید استودیو یک کادر محاوره‌ای باز می‌کند که به شما امکان می‌دهد فایل ساخته شده را پیدا کنید. اگر آن را پیدا نکردید، می‌توانید روی «گزارش رویداد» کلیک کنید تا دوباره لینک را دریافت کنید.

آپلود در توزیع برنامه Firebase

1. توزیع برنامه را باز کنید و روی «شروع» کلیک کنید
2. فایل .apk خود را کشیده و در کادری که نوشته شده «برای ایجاد یک نسخه جدید، هر فایل .apk را اینجا بکشید» رها کنید.
3. آدرس ایمیل خود را به عنوان اولین آزمایش کننده وارد کنید.
4. روی بعدی کلیک کنید.
5. توضیحی اضافه کنید و روی توزیع کلیک کنید

دعوت از آزمایش‌کنندگان

به جای اینکه مجبور باشید هر آدرس ایمیل را به صورت دستی وارد کنید، می‌توانید یک لینک دعوت ایجاد کنید. وقتی کاربری را با این لینک دعوت جذب می‌کنید، می‌توانید او را به گروهی از آزمایش‌کنندگان نیز اضافه کنید. به عنوان مثال، این به شما امکان می‌دهد آزمایش‌کنندگان داخلی را از آزمایش‌کنندگان خارجی جدا کنید.

1. روی «آزمایش‌کنندگان و گروه‌ها» کلیک کنید
2. ایجاد یک گروه جدید و نامی مانند «آزمایش‌کنندگان اندروید» به آن بدهید.
3. روی «لینک‌های دعوت» کلیک کنید
4. روی «لینک دعوت جدید» کلیک کنید
5. گروه را از منوی کشویی اینجا تنظیم کنید.
6. روی «ایجاد پیوند» کلیک کنید
7. روی «کپی پیوند» کلیک کنید و آن را به هر شکلی که می‌خواهید به اشتراک بگذارید

۹. تبریک

شما با موفقیت تجزیه و تحلیل را به بازی مبتنی بر C++ خود اضافه کرده‌اید، از برخی از دوستان خود برای بازی دعوت کرده‌اید، و می‌دانید که چگونه کتابخانه‌های Firebase را در یک سیستم ساخت مبتنی بر CMake و Gradle که در توسعه اندروید رایج است، پیدا کرده و پیوند دهید.

آنچه پوشش داده‌ایم

• چگونه Firebase را به بازی مبتنی بر CMake اندروید خود اضافه کنیم؟
• چگونه بفهمیم به کدام وابستگی‌های C++ و Gradle نیاز داریم.
• نحوه ثبت رویدادهای آنالیتیکس
• نحوه اشکال‌زدایی رویدادهای تحلیلی.
• نحوه اشتراک گذاری بازی خود با App Distribution

مراحل بعدی

• سعی کنید یک کاربر را به صورت ناشناس وارد سیستم کنید و امتیاز بالای او را در پایگاه داده Realtime ذخیره کنید.
• رویدادهای تحلیلی را در بازی خودتان ثبت کنید.
• سعی کنید تجزیه و تحلیل را به یک بازی iOS اضافه کنید.

اطلاعات بیشتر

• فهرست رویدادهای خاص بازی‌ها را ببینید و بررسی کنید که چگونه می‌توانند در بازی شما جای بگیرند.