Chương 5: Analytics (App.Analytics)

Hướng dẫn toàn diện về dịch vụ thu thập và phân tích dữ liệu người chơi qua App.Analytics (giao diện IAnalyticsService). Tìm hiểu mô hình Fan-out Hub chuyển phát sự kiện đa luồng, cơ chế tự động đo lường thời gian chơi, bảng ánh xạ chuẩn hoá sang Firebase Analytics, GameAnalytics, AppMetrica và SayKit.

1. Mục đích & Mô hình kiến trúc (Mental Model)

Trong phát triển game di động thương mại, việc chuyển đổi qua lại giữa các nhà phát hành (Publishers) hoặc thay đổi công cụ phân tích (Firebase, GameAnalytics, AppMetrica, SayKit) thường dẫn đến việc phải viết lại toàn bộ mã nguồn theo dõi dữ liệu. MGW SDK giải quyết triệt để vấn đề này thông qua kiến trúc Fan-out Hub và Ngôn ngữ sự kiện thống nhất:

• Một điểm gọi duy nhất (Single Point of Tracking): Mã nguồn game chỉ tương tác với duy nhất Facade App.Analytics (trả về IAnalyticsService thuộc namespace TapBrain.Core.Services). Lập trình viên không bao giờ gọi trực tiếp SDK của bên thứ ba trong logic game.
• Trung tâm điều phối Fan-out Hub: Bên dưới Facade, lớp nội bộ AnalyticsService giữ vai trò trung tâm phân phối (Hub). Khi một sự kiện được kích hoạt, Hub sẽ đóng gói thành cấu trúc TrackEvent và chuyển lần lượt (đồng bộ, trên luồng chính) tới các bộ thu nhận (Sinks) đã sẵn sàng; sink chưa sẵn sàng bị bỏ qua.
• Cầu nối tương thích ngữ nghĩa (Tracking Bridge):
  • Provider SayKit: Lớp SayKitAnalyticsSink hiện thực giao diện ITrackingSink, tiếp nhận trực tiếp TrackEvent và chuyển thẳng tới các hàm gốc như SayKit.trackLevelStarted, SayKit.trackSoftIncome...
  • Provider MGW: Các Sink như FirebaseAnalyticsSink, GameAnalyticsSink, AppMetricaSink tiếp nhận tên sự kiện generic và từ điển tham số đã được chuẩn hoá bởi lớp TrackEventMapper.ToGeneric().

2. Quy trình tích hợp từng bước

Bước 1: Theo dõi vòng đời màn chơi (Levels & Stages)

Khi bắt đầu một màn chơi mới, gọi App.Analytics.LevelStarted(level, tag). Khi người chơi hoàn thành hoặc thất bại, gọi LevelCompleted hoặc LevelFailed. Trên các sink của Provider MGW, SDK tự tính thời lượng chơi (giây) từ mốc bắt đầu và đính kèm vào sự kiện kết thúc dưới dạng duration_sec.

using TapBrain.Core;
using UnityEngine;

namespace MyGame.Gameplay
{
    public class LevelCoordinator : MonoBehaviour
    {
        public void StartNewLevel(int levelNumber)
        {
            // Start the level (level numbers start at 1)
            App.Analytics.LevelStarted(levelNumber, tag: "campaign");
        }

        public void FinishLevel(int levelNumber, int earnedScore, bool isVictory)
        {
            if (isVictory)
            {
                // On MGW sinks duration_sec is measured from LevelStarted and attached automatically
                App.Analytics.LevelCompleted(levelNumber, score: earnedScore, tag: "campaign");
            }
            else
            {
                App.Analytics.LevelFailed(levelNumber, score: earnedScore, tag: "campaign");
            }
        }
    }
}

Bước 2: Theo dõi biến động kinh tế ảo (Virtual Currency)

Bất cứ khi nào số dư tiền tệ của người chơi thay đổi (nhận thưởng hoàn thành màn chơi, xem quảng cáo, mua lượt chơi hoặc nâng cấp trang bị), hãy ghi nhận bằng CurrencyIncome hoặc CurrencyOutcome. Phân loại tiền tệ sử dụng enum CurrencyType.Soft (tiền vàng/bạc kiếm được trong game) hoặc CurrencyType.Hard (kim cương/ngọc quý mua bằng tiền thật).

using TapBrain.Core;
using TapBrain.Core.Services;

namespace MyGame.Economy
{
    public class BankManager
    {
        private int _goldBalance = 500;

        public void AddReward(int amount, string placement)
        {
            _goldBalance += amount;
            App.Analytics.CurrencyIncome(CurrencyType.Soft, amount, _goldBalance, place: placement);
        }

        public bool SpendGold(int cost, string itemKey)
        {
            if (_goldBalance < cost) return false;
            _goldBalance -= cost;
            App.Analytics.CurrencyOutcome(CurrencyType.Soft, cost, _goldBalance, place: $"shop_{itemKey}");
            return true;
        }
    }
}

Bước 3: Gửi sự kiện tuỳ chỉnh (Custom Event)

Khi cần ghi nhận các hành vi đặc thù của game không nằm trong các hàm dựng sẵn, bạn có hai lựa chọn:

• Khuyên dùng: App.Analytics.Event(name, param1, param2, extra1, extra2) — Thiết kế theo cấu trúc vị trí cố định (Fixed-slot architecture). Cả 4 slot được gửi đủ lên Firebase, AppMetrica và SayKit. GameAnalytics chỉ nhận param1 (dưới khoá value, khi khác 0); param2, extra1, extra2 bị bỏ trên GameAnalytics. Trên MGW, slot bằng 0 hoặc rỗng không được gửi.
• Linh hoạt: App.Analytics.LogEvent(eventName, parameters) — Nhận từ điển tự do IReadOnlyDictionary<string, object>. Lưu ý: trên SayKit chỉ tham số số đầu tiên và chuỗi đầu tiên được giữ lại; trên GameAnalytics chỉ tham số có khoá "value" (kiểu số) được trích xuất. LogEvent không đi qua cầu nối TrackEvent và không kiểm tra tên sự kiện.

3. Bảng tra cứu toàn bộ API (App.Analytics)

Tất cả các phương thức dưới đây đều thuộc giao diện IAnalyticsService (namespace TapBrain.Core.Services), được truy xuất thông qua Facade tĩnh App.Analytics:

4. Bảng ánh xạ sự kiện chi tiết (TrackEventMapper & Generic Events)

Khi chạy trên Provider MGW, các lệnh gọi từ App.Analytics được lớp TrackEventMapper chuyển đổi sang định dạng sự kiện Generic (tương thích GA4 / Firebase) trước khi chuyển phát đến Firebase Analytics, GameAnalytics và AppMetrica. Lưu ý: bảng dưới là tập tham số mà Firebase và AppMetrica nhận; GameAnalytics chỉ nhận tên sự kiện kèm tham số số value (nếu có):

Cơ chế tự động đo duration_sec và kế thừa level

Trong AnalyticsService, biến nội bộ _currentLevel ghi nhớ màn chơi đang hoạt động khi LevelStarted được gọi. Mốc thời gian thực _levelStartedAt = Time.realtimeSinceStartup cũng được kích hoạt.

• Khi gọi StageStarted(number), SDK tự gán tham số level = _currentLevel mà không yêu cầu bạn phải truyền lại. Đồng thời kích hoạt bộ đếm thời gian riêng _stageStartedAt cho chặng.
• Khi kết thúc màn chơi qua LevelCompleted hoặc LevelFailed, SDK tính toán:

  int seconds = Mathf.RoundToInt(Time.realtimeSinceStartup - _levelStartedAt);
  _levelStartedAt = -1f; // Reset after use

  Nếu chưa gọi LevelStarted (hoặc mốc đã bị xoá bởi lần kết thúc trước đó, ví dụ chơi lại mà không gọi LevelStarted), thời gian là -1 và tham số duration_sec bị lược bỏ hoàn toàn. Cơ chế tương tự áp dụng cho StageStarted → StageCompleted/StageFailed qua mốc riêng của chặng.
• duration_sec và việc tự điền level cho sự kiện stage nằm trong bản ánh xạ generic nên chỉ tác động tới các sink MGW (Firebase, AppMetrica; GameAnalytics không nhận tham số này). Sink SayKit nhận lệnh gọi gốc (SayKit.trackLevelCompleted...) và không được SDK truyền duration_sec.

Sự khác biệt cốt lõi: Event vs LogEvent

Quy tắc kiểu dữ liệu tham số & Giới hạn nền tảng

• Các kiểu dữ liệu được hỗ trợ: int, long, float, double, bool, string. Kiểu khác được chuyển thành chuỗi bằng ToString() trên Firebase và AppMetrica, và bị bỏ qua trên GameAnalytics và SayKit.
• Chuyển đổi kiểu Boolean: FirebaseAnalyticsSink ép boolean thành 1L (true) hoặc 0L (false); null thành chuỗi rỗng.
• AppMetrica dùng JSON tự dựng: AppMetricaSink ghép từ điển thành chuỗi JSON rồi gọi AppMetrica.ReportEvent(name, jsonString). Chỉ int, long, float, double được ghi dạng số; bool và mọi kiểu khác thành chuỗi (bool thành "True"/"False"). Chỉ ký tự " trong giá trị được escape: dấu \ và xuống dòng không được escape nên có thể tạo JSON không hợp lệ, hãy tránh các ký tự này trong giá trị chuỗi.
• Sự kiện không có tên (Nameless Event): Chỉ Event(name, ...) bị kiểm tra: nếu name là chuỗi rỗng hoặc null, hệ thống bỏ qua sự kiện và ghi cảnh báo [Analytics] Custom event without a name ignored. LogEvent không kiểm tra tên: tên rỗng vẫn được chuyển tới các sink (Firebase sẽ ghi lỗi [Firebase] LogEvent ... failed), nên hãy tự đảm bảo tên không rỗng.
• Quy tắc đặt tên và giới hạn của từng nền tảng (độ dài tên, số tham số tối đa của Firebase/GA...) do nhà cung cấp quy định và không được SDK kiểm tra: hãy tra tài liệu của nền tảng tương ứng.

5. Các sự kiện SDK tự động ghi nhận (Tuyệt đối không gửi trùng lặp)

6. Cơ chế hoạt động Runtime & Hợp đồng vận hành

Trạng thái sẵn sàng của Sink & Cơ chế loại bỏ sự kiện sớm

Trong suốt chu kỳ khởi động của ứng dụng, các module phân tích cần thời gian để kết nối mạng và giải quyết phụ thuộc:

• Firebase Analytics: Chỉ kích hoạt khi CoreConfig.enableFirebase = true. IsReady chỉ thành true sau khi CheckAndFixDependenciesAsync trả về Available và FirebaseApp.DefaultInstance tạo được. Sự kiện (và SetUserProperty) gọi trước thời điểm đó bị bỏ qua và mất hẳn: hub chỉ chuyển cho sink đã sẵn sàng, không đệm lại.
• AppMetrica: Chỉ có khi project bật define TB_USE_APPMETRICA và cài package io.appmetrica.analytics, và CoreConfig.enableAppMetrica = true. Sink sẵn sàng khi appMetricaApiKey đã được điền (khác rỗng và khác REPLACE_ME); nếu không, hệ thống ghi cảnh báo và sink bị tắt trong phiên chạy đó.
• GameAnalytics: Chỉ có khi bật define TB_USE_GA và cài package com.gameanalytics.sdk, và CoreConfig.enableGameAnalytics = true. Khi kích hoạt, sink tạo GameObject GameAnalytics nếu cảnh chưa có, rồi khởi tạo SDK. Khoá lấy từ cửa sổ cấu hình GameAnalytics, không phải CoreConfig.
• SayKit: Lớp SayKitAnalyticsSink luôn trả về IsReady = true vì bản thân SDK của SayKit đã tích hợp sẵn cơ chế đệm sự kiện trong bộ nhớ (Memory Buffering) trước khi hoàn tất kết nối máy chủ.

So sánh tổng hợp giữa Provider MGW và SayKit

7. Nhật ký Console chuẩn (Expected Log Lines)

Dưới đây là các dòng log xuất ra cửa sổ Unity Console qua lớp CoreLog với định dạng [Tag] Message:

8. So sánh Code Đúng vs Code Sai

// 1. WRONG: completing a level without calling LevelStarted first
void OnVictory()
{
    // Consequence: no duration_sec on the event (no start time was recorded)
    App.Analytics.LevelCompleted(5, score: 100);
}

// 2. WRONG: sending the IAP event manually
void OnPurchaseSuccess(string id)
{
    // Dangerous: double counts revenue on the dashboard.
    // IapService already reports the purchase to every sink.
    App.Analytics.Event("purchase", extra1: id);
}

// 3. WRONG: sending an event from Update on every frame
void Update()
{
    // Fires ~60 events per second: floods the sinks and buries real data in noise
    App.Analytics.Event("player_x", (long)transform.position.x);
}

// 1. RIGHT: start the level before finishing it
void OnStartGame()
{
    App.Analytics.LevelStarted(5, tag: "normal");
}

void OnVictory()
{
    // MGW sinks receive duration_sec measured since LevelStarted
    App.Analytics.LevelCompleted(5, score: 100, tag: "normal");
}

// 2. RIGHT: only deliver the content, the SDK reports the purchase
void OnPurchaseSuccess(string id)
{
    // The SDK reports the purchase to the active sinks (Firebase, GameAnalytics, AppMetrica).
    // Game code only unlocks the feature and updates the UI.
    UnlockPremiumFeature(id);
}

// 3. RIGHT: track only meaningful, user-triggered actions
public void OnUpgradeButtonClicked()
{
    App.Analytics.Click("shop_screen", "btn_upgrade_sword");
}

9. Ví dụ thực hành mẫu (C# Realistic Examples)

Ví dụ 1: Quản lý trọn vẹn luồng màn chơi (LevelFlowManager)

Script mẫu minh hoạ cách tích hợp đầy đủ chu trình: Bắt đầu màn chơi, hoàn thành các chặng con (Stages) và kết thúc màn chơi có thưởng tiền tệ ảo:

using TapBrain.Core;
using TapBrain.Core.Services;
using UnityEngine;

namespace MyGame.Gameplay
{
    public class LevelFlowManager : MonoBehaviour
    {
        private int _currentLevel = 1;
        private int _currentStage = 1;
        private int _playerCoins = 250;

        public void StartCampaignLevel(int level)
        {
            _currentLevel = level;
            _currentStage = 1;

            // 1. Track the start of the main level
            App.Analytics.LevelStarted(_currentLevel, tag: "dungeon");

            // 2. Start the first stage (the SDK fills in the current level)
            App.Analytics.StageStarted(_currentStage, tag: "dungeon");
            Debug.Log($"[MyGame] Started Level {_currentLevel}, Stage {_currentStage}");
        }

        public void PassCurrentStage()
        {
            // Complete the stage (MGW sinks get its duration_sec)
            App.Analytics.StageCompleted(_currentStage, score: 50, tag: "dungeon");

            _currentStage++;
            // Start the next stage
            App.Analytics.StageStarted(_currentStage, tag: "dungeon");
        }

        public void CompleteLevel(bool isSuccess)
        {
            if (isSuccess)
            {
                // Complete the last stage
                App.Analytics.StageCompleted(_currentStage, score: 100, tag: "dungeon");

                // Complete the main level (MGW sinks get duration_sec since LevelStarted)
                App.Analytics.LevelCompleted(_currentLevel, score: 1000, tag: "dungeon");

                // Reward virtual currency on victory
                int rewardCoins = 100;
                _playerCoins += rewardCoins;
                App.Analytics.CurrencyIncome(CurrencyType.Soft, rewardCoins, _playerCoins, place: "level_victory");
            }
            else
            {
                // Fail the current stage, then the level
                App.Analytics.StageFailed(_currentStage, score: 10, tag: "dungeon");
                App.Analytics.LevelFailed(_currentLevel, score: 150, tag: "dungeon");
            }
        }
    }
}

Ví dụ 2: Mua và nâng cấp trang bị trong Cửa hàng (ShopItemController)

Script mẫu minh hoạ quy trình người chơi mở giao diện cửa hàng, tiêu tiền ảo để mua sắm vật phẩm và gửi sự kiện nâng cấp tuỳ biến:

using TapBrain.Core;
using TapBrain.Core.Services;
using UnityEngine;

namespace MyGame.Shop
{
    public class ShopItemController : MonoBehaviour
    {
        private int _softGems = 1200;

        public void OpenShopView()
        {
            // Track opening the shop screen
            App.Analytics.Screen("shop_weapon_view");
        }

        public void BuyItem(string itemId, int cost, int targetTier)
        {
            // Track the tap on the buy button
            App.Analytics.Click("shop_weapon_view", "buy_button");

            if (_softGems < cost)
            {
                Debug.LogWarning("[MyGame] Not enough gems to purchase!");
                return;
            }

            // 1. Spend the currency and track it
            _softGems -= cost;
            App.Analytics.CurrencyOutcome(CurrencyType.Soft, cost, _softGems, place: "shop_buy");

            // 2. Track the new item
            App.Analytics.ItemReceived(itemId);

            // 3. Custom event with the four fixed slots (GameAnalytics keeps only param1)
            // param1: cost, param2: upgrade tier, extra1: item id, extra2: purchase source
            App.Analytics.Event(
                name: "item_upgrade",
                param1: cost,
                param2: targetTier,
                extra1: itemId,
                extra2: "shop_dialog"
            );

            Debug.Log($"[MyGame] Successfully purchased {itemId} tier {targetTier}");
        }
    }
}

10. Các lỗi phổ biến & Cách khắc phục

• Lỗi mất tham số duration_sec: Xảy ra khi gọi LevelCompleted hoặc LevelFailed nhưng trước đó bỏ quên LevelStarted, hoặc khi chơi lại mà không gọi lại LevelStarted (mốc bị xoá sau lần kết thúc đầu). Hãy gọi LevelStarted cho mỗi lượt chơi.
• Dùng LogEvent với nhiều tham số trên Provider SayKit: SayKit chỉ ghi nhận 1 số và 1 chuỗi đầu tiên từ từ điển tham số. Giải pháp: dùng App.Analytics.Event(name, p1, p2, e1, e2) để cả 4 slot đến được SayKit (lưu ý GameAnalytics chỉ nhận p1).
• Tự log sự kiện doanh thu quảng cáo hoặc IAP: Làm trùng dữ liệu doanh thu trên các nền tảng phân tích. Hãy để SDK (MaxAdsService, IapService) tự báo.
• Gửi sự kiện quá thường xuyên: Tránh gọi Analytics trong Update(), FixedUpdate() hoặc mỗi bước di chuyển của nhân vật: mỗi lệnh gọi phát một sự kiện tới mọi sink đang sẵn sàng, làm nhiễu dữ liệu và tốn tài nguyên. Chỉ theo dõi các mốc có ý nghĩa phân tích. Giới hạn số sự kiện/tham số của từng nền tảng do nhà cung cấp quy định, SDK không kiểm tra.

11. Checklist kiểm tra nhanh