Bắt đầu sử dụng Firebase trong C++

1. Tổng quan

Trong lớp học lập trình này, bạn sẽ tìm hiểu cách tích hợp C++ Firebase Games SDK vào một trò chơi mẫu trên Android bằng Google Analytics làm ví dụ. Bạn có thể thêm các tính năng cần thiết, tích hợp một số logic phân tích cơ bản để đo lường tiến trình của người chơi và chia sẻ trò chơi với người kiểm thử để nhận được ý kiến phản hồi sớm.

Hướng dẫn từng bước

Nếu bạn muốn tham gia lớp học lập trình này cùng với các tác giả, hãy xem video này:

Kiến thức bạn sẽ học được

• Cách thêm Firebase vào trò chơi dựa trên CMake trên Android.
• Cách xác định những phần phụ thuộc C++ và Gradle mà bạn cần.
• Cách ghi lại sự kiện Analytics.
• Cách gỡ lỗi sự kiện Analytics.
• Cách chia sẻ trò chơi của bạn bằng App Distribution.

Bạn cần có

• Android Studio
• Mã mẫu
• Một thiết bị thử nghiệm hoặc trình mô phỏng có Dịch vụ Google Play

2. Nhận mã mẫu

Kiểm tra hoặc tải xuống từ GitHub:

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

Tải Firebase SDK xuống

MacOS/Linux:

sh download.sh

Windows (từ PowerShell):

./download.ps1

Bạn cũng có thể tải SDK xuống theo cách thủ công. Nếu bạn làm như vậy, SDK C++ của Firebase phải được trích xuất vào /third_party sao cho thư mục có tên firebase_cpp_sdk có thư mục gốc CMakeLists.txt từ Firebase SDK trong đó.

3. Chạy trò chơi mẫu

Trước tiên, hãy chơi trò chơi mẫu và đảm bảo mọi thứ đều hoạt động. Đây là một trò chơi chạy vô tận đơn giản với cấp độ được tạo theo quy trình và một nút duy nhất để nhảy.

1. Chọn File > New > Import Project (Tệp > Mới > Nhập dự án) (hoặc chọn Import Project (Nhập dự án) trên màn hình khởi động)
2. Mở thư mục proj.android/ có trong kho lưu trữ

Đây là một dự án Cocos2dx chứ không phải là một dự án Android thông thường. Thông thường, bạn sẽ thấy một tệp build.gradle ở gốc của kho lưu trữ này, nhưng tệp đó nằm trong proj.android/ để mỗi hệ điều hành mục tiêu có thể có quy trình xây dựng độc lập riêng.

3. [Không bắt buộc] Mở proj.android/gradle.properties và tìm PROP_APP_ABI. Bạn có thể xoá tất cả trừ kiến trúc mục tiêu để giảm thời gian tạo bản dựng. PROP_APP_ABI=x86 sẽ chỉ tạo cho trình mô phỏng PROP_APP_ABI=armeabi-v7a sẽ tạo cho hầu hết các điện thoại
4. Nhấp vào nút Debug (Gỡ lỗi) để tạo và chạy trò chơi. Quá trình này sẽ mất thời gian để xây dựng công cụ phát triển trò chơi Cocos2dx.

Các nhà phát triển Cocos2dx có kinh nghiệm có thể chọn sử dụng cocos run -p android nếu bạn đã cài đặt Cocos2dx CLI. Nhà phát triển Android có thể ưu tiên ./gradlew installDebug. Trong hướng dẫn này, tôi sẽ giả định rằng bạn đang sử dụng Android Studio để phát triển, tạo và triển khai.

4. Thiết lập Bảng điều khiển của Firebase

1. Tạo một dự án mới trong Bảng điều khiển của Firebase.
2. Đặt tên cho ứng dụng, chẳng hạn như "Popsicle Runner"
3. Bật Analytics
4. Thêm hoặc tạo tài khoản Analytics
5. Thêm một ứng dụng Android mới vào dự án
6. Thêm com.firebase.popsiclerunner làm tên gói.

Bạn sẽ không cần SHA-1 cho lớp học lập trình này

7. Tải tệp google-services.json xuống rồi sao chép vào proj.android/app

Nhiều dịch vụ lưu trữ nguồn sẽ gắn cờ google-services.json là "bí mật" nếu bạn cố gắng cam kết tệp này, nhưng không có nội dung nào trong tệp này là bí mật thực sự (trong một trò chơi đang phát hành, việc truy xuất nội dung của tệp này là không đáng kể). Bạn vẫn nên thận trọng nếu dự định xác nhận (commit) tệp này vào một kho lưu trữ mã nguồn công khai. Nếu tệp này được xuất bản công khai, thì việc tìm thấy cơ sở dữ liệu hoặc bộ nhớ trên đám mây của bạn sẽ dễ dàng hơn nhiều trước khi bạn viết các quy tắc bảo mật mạnh mẽ.

8. Bỏ qua hướng dẫn đã cho về cách thêm Firebase SDK rồi nhấp vào "Tiếp theo"
9. Bạn có thể nhấp vào "Bỏ qua bước này" khi được yêu cầu xác minh quá trình cài đặt

5. Thêm Firebase vào trò chơi

Thêm Firebase SDK vào CMakeLists.txt

Mở CMakeLists.txt ở cấp gốc. Tệp này phải có mã sau ở gần đầu

CMakeLists.txt

cmake_minimum_required(VERSION 3.6)

set(APP_NAME popsiclerunner)

project(${APP_NAME})

rồi thêm các dòng sau vào cuối tệp 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 bao gồm SDK C++ của Firebase và cung cấp SDK này cho trò chơi

target_link_libraries Kết nối trò chơi với các thư viện C++ của Firebase được xây dựng cho Android.

Hãy sử dụng bảng này để tìm ra những thư viện bạn cần cho từng tính năng mà bạn muốn sử dụng. Đây là cách tôi biết rằng firebase_analytics yêu cầu firebase_app.

Thêm trình bổ trợ Google Services

Để kết nối Firebase SDK, bạn phải thêm trình bổ trợ Dịch vụ của Google vào tập lệnh bản dựng gradle. Để thực hiện việc này, hãy mở tệp build.gradle cấp dự án (tệp này nằm trong thư mục proj.android). Và thêm classpath 'com.google.gms:google-services:4.3.3' làm phần phụ thuộc 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
    }
}

Sau đó, hãy thêm trình bổ trợ vào tệp build.gradle ở cấp mô-đun (tệp này nằm trong thư mục proj.android/app). Thêm apply plugin: 'com.google.gms.google-services' bên dưới apply plugin: 'com.android.application':

build.gradle

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

Xác định vị trí của C++ SDK trong Gradle

Để cho Gradle biết nơi tìm SDK C++ của Firebase, hãy thêm các dòng sau vào cuối tệp settings.gradle.

settings.gradle

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

Thư mục này phải trỏ đến cùng một vị trí như lệnh gọi add_subdirectory trong CMake.

Thêm các phần phụ thuộc Android

Để kết nối các phần phụ thuộc Android cho Firebase, hãy mở tệp gradle cấp mô-đun cho popsicle_runner (trong proj.android/app/build.gradle) rồi thêm nội dung sau ngay trước phần dependences { thông thường ở cuối:

build.gradle

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

Mỗi SDK C++ được xây dựng dựa trên một phiên bản cụ thể của SDK Android. firebaseCpp.dependencies là một hàm tiện lợi sẽ khám phá và định cấu hình các phần phụ thuộc gradle cần thiết để đảm bảo bạn có một cấu hình đã xác minh.

AndroidX và Jetifier

Thêm tính năng hỗ trợ AndroidX và Jetifier bằng cách mở gradle.properties rồi thêm nội dung này vào cuối:

gradle.properties

android.useAndroidX = true
android.enableJetifier = true

Khởi động Firebase trong trò chơi

Khởi động Firebase trong trò chơi bằng cách mở Classes/AppDelegate.cpp. Thêm các chỉ thị #include sau đây vào đầu:

AppDelegate.cpp

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

Sau đó, hãy thêm App::Create và khởi động các tính năng Firebase mà bạn cần. Để thực hiện việc này, hãy tìm AppDelegate::applicationDidFinishLaunching rồi thêm mã này trước auto scene = MainMenuScene::createScene():

AppDelegate.cpp

{
    using namespace firebase;
    auto app = App::Create(JniHelper::getEnv(), JniHelper::getActivity());
    analytics::Initialize(*app);
}

Tôi muốn sử dụng một khối ẩn danh {} để hạn chế phạm vi của các câu lệnh using như using namespace firebase;.

Nếu gỡ lỗi trò chơi và làm mới trang tổng quan Firebase, bạn sẽ thấy một người dùng mới xuất hiện sau khoảng một phút.

6. Thêm Analytics

Ngay từ giai đoạn đầu phát triển, số liệu phân tích là một công cụ hữu ích để đánh giá cách người kiểm thử phiên bản thử nghiệm tương tác với trò chơi. Có một số số liệu phân tích được thu thập tự động (chẳng hạn như báo cáo giữ chân người dùng), nhưng bạn nên thêm các sự kiện tuỳ chỉnh phù hợp với trò chơi cụ thể của mình.

Một điểm xuất phát tốt là ghi lại một sự kiện phân tích khi người chơi bắt đầu một cấp độ. Chúng ta có thể sử dụng số lượng sự kiện bắt đầu cấp để xem tần suất người chơi có thể chơi lại trò chơi trong một phiên.

Chúng ta cũng sẽ ghi lại một sự kiện khi người chơi chết, cùng với thông tin về quãng đường họ đã đi được. Điều này sẽ giúp chúng tôi biết những thay đổi mà chúng tôi thực hiện có ảnh hưởng như thế nào đến thời lượng của một phiên và giúp chúng tôi xác định xem người chơi muốn một trò chơi ngắn/khó hơn hay dài/dễ hơn.

Thêm tiêu đề Analytics

Mở Classes/PopsicleScene.cpp và thêm tiêu đề Firebase vào đầu để chúng ta có thể thực hiện các lệnh gọi phân tích.

PopsicleScene.cpp

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

Ghi nhật ký sự kiện Bắt đầu cấp độ

Để ghi nhật ký một sự kiện khi Cảnh này được Đạo diễn Cocos2dx dàn dựng, hãy tìm hàm mã giả lập PopsicleScene::onEnter(). Nhập mã sau đây để ghi nhật ký sự kiện Level Start tại đây:

PopsicleScene.cpp

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

Ghi lại sự kiện Kết thúc cấp độ

Để xem người chơi đang làm tốt đến mức nào, hãy ghi lại sự kiện Kết thúc cấp độ cùng với quãng đường mà người chơi đã đi được khi cuối cùng họ chết. Để thực hiện việc này, hãy tìm PopsicleScene::gameOver() rồi thêm mã này vào cuối khối if(!_gameOver) { trước khi đặt _gameOver = true;:

PopsicleScene.cpp

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

kEventLevelEnd là sự kiện kết thúc cấp độ. Trong khi "distance" là "tham số sự kiện". Chúng tôi sẽ thêm khoảng cách đã ghi lại gần đây nhất vào đây. Đây là một giá trị gần đúng cho biết khoảng cách mà người chơi đã di chuyển trước khi chết.

7. Sự kiện kiểm thử

Bạn có thể nhấp vào Gỡ lỗi ngay bây giờ, nhưng sẽ mất một khoảng thời gian để mọi sự kiện được báo cáo trên trang tổng quan Analytics. Có 2 lý do cho việc này: 1) các sự kiện được xử lý theo lô và tải lên khoảng một lần mỗi giờ để tiết kiệm pin và 2) báo cáo được tạo 24 giờ một lần.

Có những cơ chế giúp bạn xem các sự kiện nhanh hơn. Nếu được đánh dấu là sự kiện chuyển đổi, thì sự kiện sẽ được báo cáo gần như theo thời gian thực trong nhiều trường hợp. Bạn cũng có thể thiết lập Google Analytics để xuất sang BigQuery, trong đó bảng trong ngày sẽ chỉ bị trễ khoảng 4 giờ.

Bật Chế độ gỡ lỗi

Bạn vẫn có thể gỡ lỗi sự kiện Analytics bằng cách chuyển thiết bị sang chế độ gỡ lỗi.

Trước tiên, hãy đảm bảo bạn đã cài đặt và thiết lập Android Debug Bridge (ADB). Khi bạn nhập adb devices, thiết bị mà bạn sẽ kiểm thử sẽ xuất hiện:

$ adb devices
List of devices attached
emulator-5554   device

Sau đó, hãy chạy lệnh adb shell sau:

adb shell setprop debug.firebase.analytics.app com.firebase.popsiclerunner

Thao tác này yêu cầu Firebase Analytics ghi lại các sự kiện ngay lập tức và tự động loại trừ các sự kiện đó khỏi báo cáo thông thường để tránh làm ảnh hưởng đến các sự kiện trực tiếp khi kiểm thử. Nếu bạn muốn huỷ thao tác này sau, chỉ cần viết:

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

Xem sự kiện

Mở "DebugView" trong Bảng điều khiển của Firebase

Nhấp vào Gỡ lỗi rồi chơi trò chơi. Bạn sẽ thấy các sự kiện mới xuất hiện gần như ngay lập tức sau khi chúng xảy ra trong trò chơi.

Nếu mở rộng sự kiện level_end, bạn cũng sẽ thấy thông số tuỳ chỉnh "distance" mà bạn đã ghi lại.

Khi sự kiện level_end xuất hiện trong báo cáo Sự kiện, theo mặc định, sự kiện này sẽ không ghi nhận khoảng cách. Bạn cần chọn Sự kiện , tìm level_end, mở rộng dấu ba chấm ở bên phải rồi chọn Chỉnh sửa báo cáo tham số để thêm tham số này vào báo cáo sự kiện. Sau khi làm như vậy, bạn có thể xem các số liệu thống kê như khoảng cách trung bình của người chơi trong mỗi trận đấu.

8. Tìm người kiểm thử

Tiếp theo, bạn nên cho mọi người xem trò chơi của mình, cho dù đó là người trong nhóm phát triển, bạn bè thân thiết hay cộng đồng của bạn. Firebase App Distribution là một cách tuyệt vời để mời người chơi tham gia trò chơi của bạn.

Tạo tệp nhị phân độc lập

Trước tiên, hãy tạo một tệp APK độc lập để chia sẻ từ Build > Build Bundles(s) / APK(s) > Build APK(s) (Tạo > Tạo gói/tệp APK > Tạo tệp APK)

Nếu trước đó bạn đã thay đổi bộ lọc ABI, hãy nhớ quay lại gradle.properties và thay đổi PROP_APP_ABI để thêm mọi thiết bị mà bạn dự định kiểm thử:

PROP_APP_ABI=armeabi-v7a:arm64-v8a:x86

Android Studio sẽ bật một hộp thoại cho phép bạn xác định vị trí của tệp đã tạo. Nếu bỏ lỡ, bạn có thể nhấp vào "Nhật ký sự kiện" để lấy lại đường liên kết.

Tải lên Firebase App Distribution

1. Mở App Distribution rồi nhấp vào "Bắt đầu"
2. Kéo và thả tệp .apk vào hộp có nội dung "Kéo tệp .apk bất kỳ vào đây để tạo bản phát hành mới".
3. Nhập địa chỉ email của bạn làm người kiểm thử đầu tiên.
4. Nhấp vào Tiếp theo.
5. Thêm nội dung mô tả rồi nhấp vào Phân phối

Mời người kiểm thử

Thay vì phải nhập từng địa chỉ email theo cách thủ công, bạn có thể tạo một đường liên kết của lời mời. Khi thu nạp người dùng bằng đường liên kết mời này, bạn cũng có thể thêm họ vào một nhóm người kiểm thử. Ví dụ: bạn có thể tách người thử nghiệm nội bộ khỏi người thử nghiệm bên ngoài.

1. Nhấp vào "Người kiểm thử và nhóm"
2. Tạo một nhóm mới và đặt tên cho nhóm đó, chẳng hạn như "Người kiểm thử Android".
3. Nhấp vào "Đường liên kết mời"
4. Nhấp vào "Đường liên kết mời mới"
5. Đặt nhóm tại đây trong trình đơn thả xuống.
6. Nhấp vào "Tạo đường liên kết"
7. Nhấp vào "Sao chép đường liên kết" rồi chia sẻ theo cách bạn muốn

9. Xin chúc mừng

Bạn đã thêm thành công tính năng phân tích vào trò chơi dựa trên C++, mời một số bạn bè chơi và biết cách tìm cũng như liên kết các thư viện Firebase trong hệ thống xây dựng dựa trên CMake và Gradle thường gặp trong quá trình phát triển Android.

Nội dung đã đề cập

• Cách thêm Firebase vào trò chơi dựa trên CMake trên Android.
• Cách xác định những phần phụ thuộc C++ và Gradle mà bạn cần.
• Cách ghi lại sự kiện Analytics.
• Cách gỡ lỗi sự kiện Analytics.
• Cách chia sẻ trò chơi của bạn bằng App Distribution.

Các bước tiếp theo

• Thử đăng nhập người dùng ẩn danh và lưu điểm cao của họ trong Cơ sở dữ liệu theo thời gian thực.
• Ghi nhật ký các sự kiện Analytics trong trò chơi của riêng bạn.
• Hãy thử thêm số liệu phân tích vào một trò chơi iOS.

Tìm hiểu thêm

• Xem danh sách các sự kiện cụ thể của trò chơi và cân nhắc cách chúng có thể phù hợp với trò chơi của bạn.