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

1. ภาพรวม

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

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

หากต้องการทำตาม Codelab นี้กับผู้เขียน โปรดดูวิดีโอนี้

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

• วิธีเพิ่ม Firebase ลงในเกมที่ใช้ CMake ของ Android
• วิธีดูว่าคุณต้องใช้ทรัพยากร 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. ตั้งชื่อ เช่น "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 เป็น "ความลับ" หากคุณพยายามคอมมิต แต่ไม่มีสิ่งใดในไฟล์นี้ที่เป็นความลับจริงๆ (ในเกมการจัดส่ง การดึงเนื้อหาของไฟล์นี้เป็นเรื่องง่าย) คุณยังคงต้องใช้ความระมัดระวังหากวางแผนที่จะส่งไปยังที่เก็บซอร์สโค้ดสาธารณะ เนื่องจากจะค้นหาฐานข้อมูลหรือที่เก็บข้อมูลในระบบคลาวด์ได้ง่ายขึ้นมากก่อนที่คุณจะเขียนกฎความปลอดภัยที่รัดกุม หากมีการเผยแพร่ไฟล์นี้ต่อสาธารณะ

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

หากต้องการเชื่อมต่อ Firebase SDK คุณต้องเพิ่มปลั๊กอินบริการของ Google ลงในสคริปต์บิลด์ Gradle โดยให้เปิดไฟล์ 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

ค้นหา 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

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

6. เพิ่ม Analytics

แม้ในช่วงแรกของการพัฒนา Analytics ก็เป็นเครื่องมือที่มีประโยชน์ในการวัดวิธีที่ผู้ทดสอบเวอร์ชันเบต้าโต้ตอบกับเกม มีข้อมูลวิเคราะห์บางอย่างที่รวบรวมโดยอัตโนมัติ เช่น รายงานการคงผู้ใช้ แต่การเพิ่มเหตุการณ์ที่กําหนดเองซึ่งปรับให้เหมาะกับเกมของคุณโดยเฉพาะก็มีประโยชน์เช่นกัน

จุดเริ่มต้นที่ดีคือการบันทึกเหตุการณ์การวิเคราะห์เมื่อผู้เล่นเริ่มเลเวล เราสามารถใช้จำนวนเหตุการณ์การเริ่มด่านเพื่อดูความถี่ที่ผู้เล่นอาจเล่นเกมซ้ำในเซสชัน

นอกจากนี้ เราจะบันทึกเหตุการณ์เมื่อผู้เล่นตายพร้อมกับระยะทางที่ผู้เล่นไปถึง ซึ่งจะช่วยให้เราเห็นว่าการเปลี่ยนแปลงที่เราทำนั้นส่งผลต่อระยะเวลาของเซสชันเดียวอย่างไร และช่วยให้เราทราบว่าผู้เล่นต้องการเกมที่สั้น/ยากขึ้นหรือยาว/ง่ายขึ้น

เพิ่มส่วนหัวของ Analytics

เปิด Classes/PopsicleScene.cpp แล้วเพิ่มส่วนหัวของ Firebase ที่ด้านบนเพื่อให้เราเรียกใช้ข้อมูลวิเคราะห์ได้

PopsicleScene.cpp

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

บันทึกเหตุการณ์ Level Start

หากต้องการบันทึกเหตุการณ์เมื่อ Cocos2dx Director จัดฉากนี้ ให้ค้นหาฟังก์ชันที่สร้างขึ้น 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 > 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 App Distribution

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

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

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

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

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

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

สิ่งที่เราได้พูดถึงไปแล้ว

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

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

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

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

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