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

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

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

הדרכה מפורטת

אם אתם רוצים לעבור על הקוד הזה יחד עם המחברים, צפו בסרטון הבא:

מה תלמדו

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

למה תזדקק?

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

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

תשלום או הורדה מ-GitHub:

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

מורידים את Firebase SDK

MacOS/Linux:

sh download.sh

Windows (מ-PowerShell):

./download.ps1

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

3. הפעלת המשחק לדוגמה

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

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

זהו פרויקט של Cocos2dx ולא פרויקט טיפוסי של Android. בדרך כלל קובץ build.gradle היה אמור להופיע ברמה הבסיסית (root) של המאגר הזה, אבל הוא קטן מ-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 אם מותקן על ידי Cocos2dx 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 כ"סודות" אם תנסו לשמור את הקובץ הזה, אבל שום דבר בקובץ הזה לא נחשב לסוד אמיתי (במשחק משלוחים, לא כדאי לפספס את התוכן של הקובץ הזה). עדיין צריך להיות זהירים אם אתם מתכננים להתחייב למאגר של קוד מקור ציבורי – יהיה לכם הרבה יותר קל למצוא את מסדי הנתונים או הקטגוריות של Cloud Storage לפני שתכתבו כללי אבטחה חזקים אם הקובץ הזה יפורסם באופן ציבורי.

8. מתעלמים מההוראות להוספת ה-SDK של Firebase ולוחצים על 'הבא'
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 כולל את ה-SDK של Firebase C++ והוא זמין למשחק הזה

target_link_libraries 'כלבו את המשחק' עם ספריות ה-C++ של Firebase שמיועדות ל-Android.

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

הוספת הפלאגין של שירותי Google

כדי לחבר את Firebase SDK, צריך להוסיף את הפלאגין של שירותי Google לסקריפט של תהליך Gradle. כדי לעשות זאת, פותחים את הקובץ build.gradle ברמת הפרויקט (תיקייה proj.android). ולהוסיף את classpath 'com.google.gms:google-services:4.3.3' כתלות בסקריפט build.

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

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

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

PopsicleScene.cpp

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

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

כדי לתעד אירוע כשהסצנה הזו מבוים על ידי הבמאי של Cocos2dx, צריך לחפש את הפונקציה המחושבת PopsicleScene::onEnter(). צריך להזין את הקוד הבא כדי לתעד כאן את האירוע 'התחלת רמה':

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

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

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

בניית בינארי עצמאי

קודם כול צריך לפתח APK נפרד ולשתף אותו מ-Build > חבילות Build / חבילות APK > בניית חבילות APK

אם שיניתם בעבר את מסנן ה-ABI, חשוב לחזור אל gradle.properties ולשנות את PROP_APP_ABI כך שיכלול כל מכשיר שבו אתם מתכננים לבדוק:

PROP_APP_ABI=armeabi-v7a:arm64-v8a:x86

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

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

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

הזמנת בודקים

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

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

9. מזל טוב

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

מה כללנו

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

השלבים הבאים

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

מידע נוסף

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