เริ่มต้นใช้งาน Firebase ใน C+#43;

1. ภาพรวม

ใน Codelab นี้ คุณจะได้เรียนรู้วิธีผสานรวม C++ Firebase Games SDK ในเกม Android ตัวอย่างโดยใช้ Google Analytics เป็นตัวอย่าง คุณจะเพิ่มฟีเจอร์ที่ต้องการ ผสานรวมตรรกะการวิเคราะห์พื้นฐานบางอย่างเพื่อวัดความคืบหน้าของผู้เล่น และแชร์เกมกับผู้ทดสอบเพื่อรับความคิดเห็นล่วงหน้าได้

คำแนะนำแบบทีละขั้น

หากคุณต้องการดู Codelab นี้กับผู้เขียน โปรดดูวิดีโอนี้

สิ่งที่คุณจะได้เรียนรู้

• วิธีเพิ่ม Firebase ลงในเกมที่ใช้ Android CMake
• วิธีหาทรัพยากร Dependency ของ C++ และ Gradle
• วิธีบันทึกเหตุการณ์ Analytics
• วิธีแก้ไขข้อบกพร่องเหตุการณ์ Analytics
• วิธีแชร์เกมกับ App Distribution

สิ่งที่ต้องมี

• Android Studio
• โค้ดตัวอย่าง
• อุปกรณ์ทดสอบหรือโปรแกรมจำลองที่มีบริการ Google Play

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 ด้วยตนเองได้ด้วย หากทําเช่นนี้ ต้องมีการแยก Firebase C++ SDK ลงใน /third_party เพื่อให้โฟลเดอร์ชื่อ firebase_cpp_sdk มีรูท CMakeLists.txt จาก Firebase SDK ในโฟลเดอร์นั้น

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 Studio เพื่อพัฒนา สร้าง และทำให้ใช้งานได้

4. การตั้งค่าคอนโซล Firebase

1. สร้างโปรเจ็กต์ใหม่ในคอนโซล Firebase
2. ตั้งชื่ออย่าง "เกมวิ่งป๊อป"
3. เปิดใช้ Analytics
4. เพิ่มหรือสร้างบัญชี Analytics
5. เพิ่มแอป Android ใหม่ลงในโปรเจ็กต์ของคุณ
6. เพิ่ม com.firebase.popsiclerunner เป็นชื่อแพ็กเกจของคุณ

คุณไม่จำเป็นต้องใช้ SHA-1 สำหรับ Codelab นี้

7. ดาวน์โหลด google-services.json และคัดลอกไปยัง proj.android/app

บริการโฮสติ้งแหล่งที่มาจำนวนมากจะแจ้งว่า google-services.json เป็น "ข้อมูลลับ" หากคุณพยายามส่ง แต่ไฟล์นี้ไม่ได้เป็นความลับจริงๆ (ในเกมการจัดส่ง การเรียกเนื้อหาของไฟล์นี้เป็นเรื่องเล็กๆ) คุณควรใช้ความระมัดระวังหากวางแผนที่จะดำเนินการดังกล่าวไปยังที่เก็บซอร์สโค้ดสาธารณะ คุณจะค้นหาฐานข้อมูลหรือที่เก็บข้อมูลของพื้นที่เก็บข้อมูลระบบคลาวด์ได้ง่ายขึ้นมากก่อนที่จะเขียนกฎความปลอดภัยที่เข้มงวดหากเผยแพร่ไฟล์นี้ต่อสาธารณะ

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.gradle (อยู่ในโฟลเดอร์ proj.android) และเพิ่ม classpath 'com.google.gms:google-services:4.3.3' เป็นทรัพยากร Dependency ของบิลด์

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 หา 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

เพิ่มทรัพยากร Dependency ของ Android

หากต้องการเชื่อมต่อทรัพยากร Dependency ของ 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 เป็นฟังก์ชันอำนวยความสะดวกที่จะค้นพบและกำหนดค่าทรัพยากร Dependency ของ 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 คุณจะเห็นผู้ใช้ใหม่ปรากฏขึ้นหลังจากผ่านไปประมาณ 1 นาที

6. เพิ่ม Analytics

แม้ในช่วงเริ่มต้นของการพัฒนา 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 ซึ่งเกิดจากสาเหตุ 2 ประการ ได้แก่ 1) เหตุการณ์ได้รับการจัดกลุ่มรวมกันและได้รับการอัปโหลดประมาณ 1 ครั้งต่อชั่วโมงเพื่อประหยัดแบตเตอรี่ และ 2) ระบบสร้างรายงานทุก 24 ชั่วโมง

มีกลไกที่คุณสามารถดูกิจกรรมได้เร็วขึ้น หากมีการทําเครื่องหมายเหตุการณ์เป็นเหตุการณ์ Conversion ระบบจะรายงานเหตุการณ์นั้นแบบเกือบเรียลไทม์ภายใต้หลายสถานการณ์ คุณยังกําหนดค่า Google Analytics เพื่อส่งออกไปยัง BigQuery ได้ด้วย โดยตารางระหว่างวันจะล้าสมัยเพียง 4 ชั่วโมงเท่านั้น

การเปิดใช้โหมดแก้ไขข้อบกพร่อง

คุณยังแก้ไขข้อบกพร่องเหตุการณ์ Analytics ได้โดยทำให้อุปกรณ์เข้าสู่โหมดแก้ไขข้อบกพร่อง

ก่อนอื่นให้ตรวจสอบว่าคุณติดตั้งและตั้งค่า 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 คุณจะเห็น "ระยะทาง" ที่กําหนดเองด้วย ที่คุณบันทึกไว้ วันที่

เมื่อเหตุการณ์ level_end รวมอยู่ในรายงานเหตุการณ์ในที่สุด เหตุการณ์นั้นจะไม่คำนวณระยะทางโดยค่าเริ่มต้น คุณจะต้องเลือกเหตุการณ์ ค้นหา level_end ขยายจุด 3 จุดทางด้านขวา แล้วเลือกแก้ไขการรายงานพารามิเตอร์เพื่อเพิ่มเป็นพารามิเตอร์ในรายงานเหตุการณ์ หลังจากทำแล้ว คุณจะเห็นสถิติต่างๆ เช่น สถิติผู้เล่น ระยะทางเฉลี่ยต่อเกม

8. การค้นหาผู้ทดสอบ

ถัดไป คุณจะต้องรับชมเกม ไม่ว่าพวกเขาจะจากภายในสตูดิโอ ในกลุ่มเพื่อนสนิท หรือจากชุมชน Firebase App Distribution เป็นช่องทางที่ยอดเยี่ยมในการเชิญผู้เล่นให้มาเล่นเกมของคุณ

การสร้างไบนารีแบบสแตนด์อโลน

ก่อนอื่นให้สร้าง APK แบบสแตนด์อโลนเพื่อแชร์จาก Build > สร้างชุด / APK > สร้าง APK

หากคุณเปลี่ยนตัวกรอง ABI ก่อนหน้านี้ อย่าลืมกลับไปที่ gradle.properties และเปลี่ยน PROP_APP_ABI เพื่อรวมอุปกรณ์ที่คุณวางแผนจะทดสอบ

PROP_APP_ABI=armeabi-v7a:arm64-v8a:x86

Android Studio จะแสดงกล่องโต้ตอบจะปรากฏขึ้นเพื่อให้คุณค้นหาไฟล์ที่สร้างขึ้นแล้ว ถ้าพลาดไป คุณสามารถคลิก "บันทึกเหตุการณ์" เพื่อรับลิงก์อีกครั้ง

อัปโหลดไปยัง Firebase App Distribution

1. เปิด App Distribution แล้วคลิก "เริ่มต้นใช้งาน"
2. ลากและวางไฟล์ .apk ในช่องที่ระบุว่า "ลาก .apk ใดก็ได้มาที่นี่เพื่อสร้างรุ่นใหม่"
3. ป้อนอีเมลของคุณเป็นผู้ทดสอบรายแรก
4. คลิก "ถัดไป"
5. เพิ่มคำอธิบายและคลิก "เผยแพร่"

เชิญผู้ทดสอบ

คุณสร้างลิงก์คำเชิญได้โดยไม่ต้องกรอกอีเมลทุกฉบับด้วยตนเอง เมื่อจับภาพผู้ใช้ด้วยลิงก์คำเชิญนี้ คุณจะเพิ่มผู้ใช้ไปยังกลุ่มผู้ทดสอบได้อีกด้วย การดำเนินการนี้จะช่วยให้คุณแยกผู้ทดสอบภายในออกจากผู้ทดสอบภายนอกได้ เป็นต้น

1. คลิก "ผู้ทดสอบและ Groups"
2. สร้างกลุ่มใหม่ และตั้งชื่อ เช่น "ผู้ทดสอบ Android"
3. คลิก "ลิงก์คำเชิญ"
4. คลิก "ลิงก์คำเชิญใหม่"
5. ตั้งกลุ่มที่นี่จากเมนูแบบเลื่อนลง
6. คลิก "สร้างลิงก์"
7. คลิก "คัดลอกลิงก์" และแชร์ออกได้ตามต้องการ

9. ขอแสดงความยินดี

คุณเพิ่ม Analytics ลงในเกมที่ใช้ C++ ได้สำเร็จแล้ว และชวนเพื่อนมาเล่นด้วยกัน และทราบวิธีค้นหาและลิงก์ไลบรารี Firebase ในระบบบิลด์ที่ใช้ CMake และ Gradle ที่ใช้กันโดยทั่วไปในการพัฒนา Android

สรุปประเด็นที่ได้พูดถึง

• วิธีเพิ่ม Firebase ลงในเกมที่ใช้ Android CMake
• วิธีหาทรัพยากร Dependency ของ C++ และ Gradle
• วิธีบันทึกเหตุการณ์ Analytics
• วิธีแก้ไขข้อบกพร่องเหตุการณ์ Analytics
• วิธีแชร์เกมกับ App Distribution

ขั้นตอนถัดไป

• ลองล็อกอินผู้ใช้โดยไม่ระบุชื่อและบันทึกคะแนนสูงสุดของผู้ใช้ดังกล่าวใน Realtime Database
• บันทึกเหตุการณ์ Analytics ในเกมของคุณเอง
• ลองเพิ่ม Analytics ลงในเกม iOS

ดูข้อมูลเพิ่มเติม

• ดูรายการเหตุการณ์เฉพาะเกมและพิจารณาว่าเหตุการณ์ดังกล่าวเหมาะกับเกมของคุณได้อย่างไร