מתחילים לעבוד עם Firebase ב-C++

1. סקירה כללית

ב-codelab הזה נסביר איך לשלב את C++ Firebase Games SDK במשחק לדוגמה ל-Android באמצעות Google Analytics כדוגמה. תוכלו להוסיף את התכונות שאתם צריכים, לשלב לוגיקה בסיסית של ניתוח נתונים כדי למדוד את ההתקדמות של השחקנים ולשתף את המשחק עם בודקים כדי לקבל מהם משוב מוקדם.

הדרכה

כדי לצפות בסרטון שבו המחברים מסבירים איך להשתמש ב-Codelab הזה:

מה תלמדו

• איך מוסיפים את Firebase למשחק שמבוסס על Android CMake.
• איך מבררים אילו תלויות של C++ ו-Gradle צריך.
• איך מתעדים אירועים ב-Analytics.
• איך מנפים באגים באירועים של Analytics.
• איך משתפים את המשחק באמצעות הפצת אפליקציות.

הדרישות

• Android Studio
• קוד לדוגמה
• מכשיר בדיקה או אמולטור עם Google Play Services

2. קבלת קוד לדוגמה

הורדה או Checkout מ-GitHub:

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

הורדת Firebase SDK

‫MacOS/Linux:

sh download.sh

‫Windows (מ-PowerShell):

./download.ps1

אפשר גם להוריד את ה-SDK באופן ידני. אם עושים את זה, צריך לחלץ את Firebase C++ SDK לתוך /third_party כך שבתיקייה בשם firebase_cpp_sdk יהיה הרמה הבסיסית (root) CMakeLists.txt מ-Firebase SDK.

3. הרצת המשחק לדוגמה

קודם כל, משחקים במשחק לדוגמה ומוודאים שהכול פועל. זהו משחק פשוט של ריצה אינסופית עם רמה שנוצרת באופן פרוצדורלי ולחצן יחיד לקפיצה.

1. בוחרים באפשרות File > New > Import Project (קובץ > חדש > ייבוא פרויקט) או באפשרות Import Project (ייבוא פרויקט) ממסך הפתיחה.
2. פותחים את התיקייה proj.android/ שנכללת במאגר.

זה פרויקט Cocos2dx ולא פרויקט Android רגיל. בדרך כלל, קובץ build.gradle נמצא בבסיס המאגר הזה, אבל הוא נמצא בתיקייה proj.android/ כדי שלכל מערכת הפעלה יהיה תהליך build עצמאי משלה.

3. [אופציונלי] פותחים את proj.android/gradle.properties ומחפשים את PROP_APP_ABI. כדי לקצר את זמני הבנייה, אפשר להסיר את כל הארכיטקטורות חוץ מארכיטקטורת היעד. ‫PROP_APP_ABI=x86 יבנה רק עבור האמולטור ‫PROP_APP_ABI=armeabi-v7a יבנה עבור רוב הטלפונים
4. לוחצים על לחצן ניפוי הבאגים כדי ליצור את המשחק ולהריץ אותו. ייקח זמן לבנות את מנוע המשחק Cocos2dx.

מפתחים מנוסים ב-Cocos2dx יכולים להשתמש ב-cocos run -p android אם ה-CLI של Cocos2dx מותקן. מפתחי Android עשויים להעדיף את ./gradlew installDebug. במדריך הזה אני מניח שאתם משתמשים ב-Android Studio כדי לפתח, לבנות ולפרוס.

4. הגדרה של מסוף Firebase

1. יוצרים פרויקט חדש במסוף Firebase.
2. נותנים לו שם כמו "Popsicle Runner" (רץ ארטיקים)
3. הפעלת Analytics
4. הוספה או יצירה של חשבון Analytics
5. הוספת אפליקציית Android חדשה לפרויקט
6. מוסיפים את com.firebase.popsiclerunner כשם החבילה.

לא צריך SHA-1 בשביל ה-Codelab הזה

7. מורידים את הקובץ google-services.json ומעתיקים אותו אל proj.android/app

שירותי אירוח רבים של קוד מקור יסמנו את google-services.json כ'סודות' אם תנסו לבצע commit שלו, אבל שום דבר בקובץ הזה הוא לא סוד אמיתי (במשחק שמופץ, קל מאוד לאחזר את התוכן של הקובץ הזה). אם אתם מתכננים להעלות את הקובץ למאגר קוד פתוח, עדיין כדאי לנקוט משנה זהירות – אם הקובץ יפורסם באופן ציבורי, יהיה הרבה יותר קל למצוא את מסדי הנתונים או את דלי האחסון בענן לפני שתכתבו כללי אבטחה חזקים.

8. מתעלמים מההוראות שמופיעות להוספת Firebase SDK ולוחצים על 'הבא'.
9. כשמתבקשים לאמת את ההתקנה, אפשר ללחוץ על 'דילוג על השלב הזה'.

5. הוספת Firebase למשחק

הוספת 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 שנוצרו ל-Android.

בטבלה הזו מפורטות הספריות שנדרשות לכל תכונה שרוצים להשתמש בה. כך ידעתי שfirebase_analytics דורש firebase_app.

הוספת התוסף Google Services

כדי לחבר את Firebase SDK, צריך להוסיף את הפלאגין Google Services לסקריפט gradle build. כדי לעשות את זה, פותחים את הקובץ project level 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 איפה נמצא Firebase C++ SDK, מוסיפים את השורות הבאות לתחתית הקובץ 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
}

כל C++ SDK מבוסס על גרסה ספציפית של 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. הוספת Analytics

גם בשלבים הראשונים של הפיתוח, ניתוח הנתונים הוא כלי שימושי להערכת האינטראקציות של בודקי הבטא עם המשחק. יש ניתוחים מסוימים שנאספים באופן אוטומטי – כמו דוחות שימור – אבל כדאי להוסיף אירועים מותאמים אישית שמותאמים למשחק הספציפי שלכם.

נקודת התחלה טובה היא רישום ביומן של אירוע Analytics כששחקן מתחיל שלב. אפשר להשתמש במספר האירועים של התחלת שלב כדי לראות באיזו תדירות שחקן עשוי לשחק מחדש במשחק בסשן.

נרשום גם אירוע כשהשחקן מת, עם המרחק שהוא הגיע אליו. כך נוכל לראות איך שינויים שאנחנו מבצעים משפיעים על משך הזמן של סשן יחיד, ונוכל להבין אם השחקנים מעדיפים משחק קצר יותר וקשה יותר או משחק ארוך יותר וקל יותר.

הוספת כותרות של Analytics

פותחים את Classes/PopsicleScene.cpp ומוסיפים כותרות Firebase לחלק העליון כדי שנוכל לבצע קריאות לניתוח נתונים.

PopsicleScene.cpp

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

רישום ביומן של אירוע התחלת רמה

כדי לרשום ביומן אירוע כש-Scene מועבר לסביבת Staging על ידי 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. בדיקת אירועים

אפשר ללחוץ על סמל ניפוי הבאגים עכשיו, אבל יעבור זמן עד שאירועים ידווחו בלוח הבקרה של Analytics. יש לכך שתי סיבות: 1) האירועים נאספים בקבוצות ומועלים בערך פעם בשעה כדי לחסוך בסוללה, ו-2) הדוחות נוצרים כל 24 שעות.

יש מנגנונים שמאפשרים לראות אירועים מהר יותר. אם אירוע מסומן כאירוע המרה, הוא ידווח כמעט בזמן אמת בנסיבות רבות. אפשר גם להגדיר את Google Analytics לייצא ל-BigQuery, שבו הטבלה של נתונים יומיים תהיה מעודכנת עם נתונים מלפני 4 שעות בלבד.

הפעלת מצב ניפוי באגים

עדיין אפשר לנפות באגים באירועים של Analytics על ידי העברת המכשיר למצב ניפוי באגים.

קודם כול, מוודאים שממשק הגישור של Android‏ (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, רואים גם את הפרמטר המותאם אישית 'מרחק' שרשמתם ביומן.

כשאירוע level_end יופיע בסופו של דבר בדוחות האירועים, הוא לא יכלול את המרחק כברירת מחדל. כדי להוסיף את הפרמטר הזה לדוחות האירועים, צריך לבחור באפשרות Events (אירועים) , לאתר את level_end, להרחיב את סמל שלוש הנקודות בצד שמאל ולבחור באפשרות Edit parameter reporting (עריכת הדיווח על פרמטרים). אחרי שתעשו את זה, תוכלו לראות נתונים סטטיסטיים כמו המרחק הממוצע של השחקנים בכל משחק.

8. חיפוש בודקים

לאחר מכן, כדאי להציג את המשחק שלכם לאנשים שונים – בין אם הם עובדים בסטודיו שלכם, חברים קרובים או חברים בקהילה שלכם. הפצת אפליקציות ב-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

ב-Android Studio תופיע תיבת דו-שיח שמאפשרת לאתר את הקובץ שנוצר. אם פספסתם את הקישור, תוכלו ללחוץ על 'יומן אירועים' כדי לקבל אותו שוב.

העלאה אל הפצת אפליקציות ב-Firebase

1. פותחים את הפצת אפליקציות ולוחצים על Get Started (התחלה)
2. גוררים ומשחררים את קובץ ה-APK בתיבה עם הכיתוב 'גוררים לכאן קובץ APK כדי ליצור גרסה חדשה'.
3. מזינים את כתובת האימייל שלכם כבודקים הראשונים.
4. לוחצים על 'הבא'.
5. מוסיפים תיאור ולוחצים על הפצה.

הזמנת בודקים

במקום להזין ידנית את כל כתובות האימייל, אפשר ליצור קישור להזמנה. כשמשתמש נכנס דרך הקישור להזמנה, אפשר גם להוסיף אותו לקבוצת בודקים. לדוגמה, תוכלו להפריד בין בודקים פנימיים לבין בודקים חיצוניים.

1. לוחצים על 'בודקים וקבוצות' .
2. יוצרים קבוצה חדשה ונותנים לה שם כמו "בודקי Android".
3. לוחצים על 'קישורי הזמנה'
4. לוחצים על 'קישור חדש להזמנה'.
5. בתפריט הנפתח, מגדירים את הקבוצה.
6. לוחצים על 'יצירת קישור'.
7. לוחצים על 'העתקת קישור' ומשתפים אותו בכל דרך שרוצים.

9. מזל טוב

הוספתם בהצלחה ניתוח נתונים למשחק שמבוסס על C++‎, הזמנתם חברים לשחק ואתם יודעים איך למצוא ולקשר ספריות Firebase במערכת build שמבוססת על CMake ו-Gradle, שמשמשת בדרך כלל לפיתוח ל-Android.

מה נכלל

• איך מוסיפים את Firebase למשחק שמבוסס על Android CMake.
• איך מבררים אילו תלויות של C++ ו-Gradle צריך.
• איך מתעדים אירועים ב-Analytics.
• איך מנפים באגים באירועים של Analytics.
• איך משתפים את המשחק באמצעות הפצת אפליקציות.

השלבים הבאים

• אפשר לנסות לחבר משתמש באופן אנונימי ולשמור את התוצאה הגבוהה שלו במסד נתונים בזמן אמת.
• רישום אירועים ב-Analytics במשחק שלכם.
• כדאי לנסות להוסיף ניתוח נתונים למשחק ל-iOS.

מידע נוסף

• כדאי לעיין ברשימה של אירועים ספציפיים למשחקים ולחשוב איך אפשר לשלב אותם במשחק שלכם.