Chương 11: Kiểm tra & Gỡ lỗi (Verification & Troubleshooting)

Hướng dẫn toàn diện về quy trình kiểm chứng quá trình tích hợp SDK trong Unity Editor và trên thiết bị thực tế: nhận biết chính xác chuỗi log khởi động theo từng stack, phân biệt log cảnh báo dự kiến khi chưa có key với các lỗi nghiêm trọng, tra cứu nhanh triệu chứng - nguyên nhân - cách khắc phục, tuân thủ chốt chặn Build Guard và xử lý sự cố biên dịch.

1. Mục đích & Nguyên tắc kiểm thử

Một thay đổi mã nguồn trong dự án chỉ được coi là hoàn tất khi đã vượt qua các bước kiểm chứng hành vi thực thi thực tế (runtime behavior). Việc dự án biên dịch thành công (0 compile errors) chưa bao giờ là đủ, bởi các assembly bị giới hạn bởi Scripting Defines có thể bị bỏ qua âm thầm khi biên dịch.

1.1. Luôn bấm Play từ Loading Scene (Build Index 0)

Trong vòng đời khởi động, Bootstrapper.Boot() được đăng ký thực thi tự động đồng bộ tại thời điểm RuntimeInitializeLoadType.BeforeSceneLoad. Điều này đảm bảo toàn bộ hệ thống dịch vụ App.X được khởi tạo trước khi bất kỳ scene nào được nạp.

Vì vậy, code gameplay tuyệt đối không được giả định rằng khi scene nạp xong thì toàn bộ dịch vụ đã sẵn sàng. Hãy luôn kiểm tra thuộc tính trạng thái (IsReady, IsInitialized, IsFetched) hoặc lắng nghe các sự kiện (Ready, Initialized, Updated).

// In a game screen script
void Start()
{
    // Dangerous: when Play starts directly from this scene, IAP and Ads may not be ready yet.
    // IsOwned() cannot see store purchases before IAP is ready, and on MGW ShowBanner() before
    // the ads SDK is initialized only records the intent (nothing is shown yet).
    buyButton.interactable = !App.Iap.IsOwned("vip_pass");
    App.Ads.ShowBanner();
}

// In a game screen script
void OnEnable()
{
    UpdateButtonState();
    App.Iap.Ready += UpdateButtonState;
    App.Ads.Initialized += OnAdsInitialized;
    // Initialized fires only once: handle the case where ads are already up.
    if (App.Ads.IsInitialized) OnAdsInitialized();
}

void OnDisable()
{
    // These services live for the whole app: always unsubscribe, otherwise a destroyed
    // screen stays subscribed and its handler throws MissingReferenceException later.
    App.Iap.Ready -= UpdateButtonState;
    App.Ads.Initialized -= OnAdsInitialized;
}

void UpdateButtonState()
{
    if (App.Iap.IsReady) buyButton.interactable = !App.Iap.IsOwned("vip_pass");
}

void OnAdsInitialized() => App.Ads.ShowBanner();

1.2. Kiểm thử trên thiết bị thật (Device Verification)

Nhiều tính năng native không thể giả lập trọn vẹn trong Unity Editor:

• iOS App Tracking Transparency (ATT): Hộp thoại cấp quyền của hệ điều hành chỉ xuất hiện trên thiết bị iOS vật lý (iOS 14.5+). Ngoài iOS (kể cả trong Editor khi build target không phải iOS), bước ATT kết thúc ngay và AttService.Status trả về NOT_SUPPORTED.
• Quảng cáo mediation thực tế (AppLovin MAX / SayKit): Chỉ kiểm chứng được hành vi thật (banner, video interstitial, callback trả thưởng) trên thiết bị. Trong Editor, với MGW chưa điền MAX key thì App.Ads.IsInitialized luôn false, TryShowInterstitial trả về false và ShowRewarded trả NotReady; khi đã có key, hành vi trong Editor do package MAX/SayKit quyết định nên không dùng làm bằng chứng nghiệm thu.
• Xác thực biên lai hóa đơn (IAP In-App Purchase): Editor dùng Fake Store của Unity IAP. Nếu game chưa đăng ký IReceiptValidator thì SDK nhận biên lai mà không xác thực cục bộ; kiểm tra luồng thanh toán và xác thực chữ ký Tangle phải chạy bản build Sandbox trên iOS TestFlight hoặc Google Play Internal Testing.
• Rung phản hồi (HapticService): Rung qua Vibrator (Android) và UIFeedbackGenerator (iOS) chỉ hoạt động trên thiết bị di động thật.

2. Trình tự Boot Log chuẩn (Expected Boot Sequence)

Hầu hết thông điệp log của SDK được ghi qua lớp CoreLog theo định dạng [Tag] message; một vài thông điệp lỗi (như [Boot] Missing Resources/CoreConfig.asset, [Boot] No SDK provider compiled in, [Boot] SDK module ... failed, [Sdk] Two SDK providers ...) dùng Debug.LogError trực tiếp nhưng cùng định dạng. Khi bật Play mode từ scene Loading với console được dọn sạch, hệ sinh thái khởi động sẽ in ra chuỗi log có cấu trúc rõ ràng.

2.1. Chuỗi Log khởi động cho MGW Stack

Đối với cấu hình tiêu chuẩn MGW (Firebase + AppLovin MAX + IAP), thứ tự thực thi của các bước boot và thông điệp chuẩn xác tại console như sau:

[IAP] No IReceiptValidator registered: receipts accepted without local validation                (only if the game registered no validator)
[Boot] ATT done in 0.00s
[Firebase] App creation failed, Firebase disabled for this session. Add the per-game config (Assets/google-services.json, Assets/GoogleService-Info.plist; see Documentation~/KEYS.md in com.mgw.sdk): ...   (dự kiến nếu chưa thêm file cấu hình Firebase)
[Boot] Firebase done in 0.05s
[Boot] Auth done in 0.00s
[Boot] RemoteConfig done in 0.00s
[Boot] RealtimeDb+BI done in 0.00s
[Ads] MAX SDK key not set in CoreConfig, ads disabled                                             (dự kiến nếu key còn để REPLACE_ME)
[Boot] Ads done in 0.00s
[AppMetrica] API key not set in CoreConfig, AppMetrica disabled                                   (dự kiến nếu bật module nhưng chưa điền key)
[Boot] AppMetrica done in 0.00s
[Boot] GameAnalytics done in 0.00s                                                                (thứ tự giữa AppMetrica và GameAnalytics không cố định)
[IAP] Unity Gaming Services init failed (project not linked?), continuing without it: ...         (dự kiến nếu chưa liên kết Unity Cloud Project)
[IAP] Ready, 2 products
[Boot] IAP done in 0.42s
[Boot] Notifications done in 0.00s
[Boot] Background done in 0.00s
[Boot] Completed, user=17300000001234 new=True session=1

2.2. Chuỗi Log khởi động cho SayKit Stack

Khi dự án được cấu hình chuyển sang stack SayKit (nhà phát hành SayGames), quy trình khởi động gọn hơn vì SayKit tự quản lý consent và tích hợp mediation riêng:

[IAP] No IReceiptValidator registered: receipts accepted without local validation                (only if the game registered no validator)
[SayKit] App key is still a placeholder in SayKitApp.cs; SayKit will not serve real ads          (dự kiến nếu chưa điền key thật)
[Boot] SayKit done in 0.12s
[RemoteConfig] SayKit game config ready (14 fields)
[Boot] RemoteConfig done in 0.00s
[IAP] Ready, 2 products
[Boot] IAP done in 0.35s
[Boot] Background done in 0.00s
[Boot] Completed, user=17300000005678 new=False session=2

Lưu ý: Trên stack SayKit, không có bước ATT (do SayKit sở hữu màn hình GDPR/ATT riêng), không có bước Notifications cục bộ của MGW và không có các bước Firebase/Auth/Ads/GameAnalytics/AppMetrica (quảng cáo được khởi tạo trong bước SayKit). Nếu SayKit không khởi tạo kịp trong CoreConfig.sayKitInitTimeout (mặc định 10 giây), bạn sẽ thấy thêm [Boot] SayKit timed out after 10s, continuing (cảnh báo, game vẫn vào được).

2.3. Quy chuẩn định dạng thời gian và xử lý Timeout

Mỗi bước trong pipeline khởi động InitPipeline được giới hạn thời gian chạy (time-boxed) bằng một ngưỡng timeout riêng. Một số ngưỡng cấu hình được trong CoreConfig, số còn lại cố định trong code (bảng bên dưới):

• Nếu bước hoàn thành kịp thời hạn: Log in ra theo cấu trúc chính xác: [Boot] <Tên_Bước> done in X.XXs (ví dụ: [Boot] IAP done in 0.38s).
• Nếu bước chạy quá thời gian giới hạn: Coroutine của bước đó bị dừng lại, console in cảnh báo: [Boot] <Tên_Bước> timed out after Xs, continuing. Tiến trình khởi động không bị treo mà tiếp tục chuyển sang bước kế tiếp để đảm bảo người chơi luôn vào được màn hình chính của game.
• Nếu bước ném ngoại lệ (Exception): Lỗi được chặn lại bởi cơ chế Guard an toàn: console in lỗi [Boot] <Tên_Bước> threw: <Exception>, bước bị coi là kết thúc (vẫn in tiếp dòng done in ...) và pipeline tiếp tục chạy.

3. Các Log bình thường khi dự án chưa điền Key

3.1. Dự án không có Key là trạng thái hợp lệ

Trong giai đoạn phát triển ban đầu hoặc khi lập trình viên chỉ cần kiểm tra logic gameplay/meta, dự án hoàn toàn có thể hoạt động mà chưa cần gắn các key dịch vụ thật (Firebase, MAX key, AppMetrica, IAP tangles). SDK được thiết kế phòng vệ chặt chẽ:

3.2. Bảng đối chiếu Log dự kiến vs Lỗi thực sự

Bảng dưới đây giúp bạn phân biệt rõ ràng giữa các log cảnh báo bình thường khi chưa có key và những lỗi kỹ thuật thật sự cần khắc phục:

4. Bảng tra cứu Triệu chứng -> Nguyên nhân -> Giải pháp

4.1. Sự cố Khởi động và Hệ thống Core

4.2. Sự cố Quảng cáo (App.Ads)

4.3. Sự cố In-App Purchase (App.Iap)

4.4. Sự cố Remote Config & Firebase

4.5. Sự cố Dialog & Scene Loader

5. Chốt chặn Build Guard (CoreConfigTools)

Một trong những sự cố tồi tệ nhất khi vận hành game là việc xuất bản bản build release ra chợ ứng dụng nhưng vẫn mang theo các ad unit test, thiếu cấu hình Firebase hoặc chưa đổi định danh ứng dụng. Để ngăn chặn hoàn toàn rủi ro này, SDK tích hợp hệ thống kiểm tra tự động trước khi đóng gói: Build Guard (triển khai qua IPreprocessBuildWithReport trong CoreConfigTools.cs).

5.1. Cơ chế hoạt động: Development vs Release

Hành vi của Build Guard được phân tách rõ ràng tùy thuộc vào chế độ đóng gói:

• Bản build thử nghiệm (Development Build): Với danh sách placeholder ([CoreConfig] Placeholders left), Build Guard chỉ in cảnh báo (Debug.LogWarning) để không cản trở quá trình debug nội bộ. Lưu ý các lỗi cứng ở bảng dưới (không có provider, SayKitApp sai, còn package MGW trên SayKit) vẫn chặn cả Development Build.
• Bản build phát hành (Release Build): Nếu phát hiện bất kỳ trường placeholder nào chưa được điền đầy đủ, Build Guard sẽ ném ra BuildFailedException và chặn đứng quá trình đóng gói ngay lập tức. Chế độ Development được xác định theo tùy chọn của chính bản build đó (kể cả build qua script/CI), không phải ô tích trong Build Settings.

5.2. Toàn bộ điều kiện kiểm tra và thông báo lỗi

Dưới đây là danh sách toàn bộ các điều kiện kiểm tra nghiêm ngặt của Build Guard:

Chi tiết từng mục có thể bị liệt kê trong thông báo [CoreConfig] Placeholders left::

• Missing Resources/CoreConfig.asset: Chưa tạo file cấu hình trong Resources.
• Assets/google-services.json (Firebase Android config): (MGW) build Android khi bật enableFirebase nhưng thiếu file cấu hình.
• Assets/GoogleService-Info.plist (Firebase iOS config): (MGW) build iOS khi bật enableFirebase nhưng thiếu file cấu hình.
• MAX SDK key (Android) / (iOS): (MGW) khi bật enableAds, SDK Key của AppLovin MAX chưa được điền. Cả hai nền tảng đều được kiểm tra, bất kể nền tảng đang build.
• Banner ad unit, Interstitial ad unit, Rewarded ad unit (Android / iOS): (MGW) Ad Unit ID chưa được cấu hình.
• AppMetrica API key (Android) / (iOS): khi module AppMetrica được biên dịch (TB_USE_APPMETRICA) và enableAppMetrica bật nhưng chưa điền API Key.
• SayKitApp.APP_KEY_ANDROID / SayKitApp.APP_KEY_IOS / SayKitApp.APP_NAME_IOS / SayKitApp.APP_BUNDLE_IOS: (SayKit) các hằng số trong SayKitApp.cs còn chứa dấu < ở đầu hoặc để trống.
• iOS App Store id: CoreConfig.iosAppStoreId chưa điền. Kiểm tra cho cả hai provider và mọi nền tảng build, kể cả build Android.
• Bundle id is still the template id: Application Identifier trong PlayerSettings vẫn bắt đầu bằng com.tapbrain.template. Hãy đặt định danh gói chính thức.

5.3. Kiểm tra chủ động qua Editor Menu

Bạn không cần phải thực hiện một tiến trình Build đầy đủ tốn nhiều thời gian chỉ để kiểm tra các thông số. Hãy sử dụng menu có sẵn của SDK:

TapBrain > Validate Core Config

Menu này chạy phần kiểm tra placeholder của Build Guard (cùng danh sách mục ở trên) cho nền tảng đang kích hoạt trong Build Settings. Nó không chạy các kiểm tra cứng (có provider, SayKitApp, package MGW còn sót trên SayKit): những kiểm tra đó chỉ chạy khi build.

• Nếu mọi thứ đã chuẩn chỉnh: Console in [CoreConfig] OK, no placeholders left.
• Nếu còn thiếu sót: Console in cảnh báo vàng [CoreConfig] Placeholders left: kèm danh sách từng mục cần bổ sung.

6. Sự cố Biên dịch & Scripting Defines

6.1. Nguyên tắc quản lý Defines

SDK sử dụng các Scripting Define Symbols để điều khiển việc biên dịch các assembly:

• Không có define: Sử dụng MGW Provider mặc định (assembly TapBrain.Sdk.MGW có điều kiện ràng buộc là !TB_SDK_SAYKIT).
• TB_SDK_SAYKIT: Kích hoạt stack SayKit, assembly của MGW sẽ tự động bị loại khỏi quá trình biên dịch.
• TB_USE_GA: Biên dịch module tích hợp GameAnalytics (chỉ hoạt động với MGW).
• TB_USE_APPMETRICA: Biên dịch module tích hợp AppMetrica (chỉ hoạt động với MGW).

6.2. Các lỗi biên dịch thường gặp và cách sửa

7. Cách đọc Unity Stack Trace cho các Frame thuộc SDK

Khi một ngoại lệ xảy ra trong Unity Console, việc phân biệt frame thuộc mã nguồn game của bạn hay thuộc SDK sẽ giúp khoanh vùng nguyên nhân nhanh chóng:

ArgumentNullException: Value cannot be null.
Parameter name: key
  at System.Collections.Generic.Dictionary`2[TKey,TValue].FindEntry (TKey key) [0x00008] in <...>:0
  at TapBrain.Core.Services.IapService.Purchase (System.String productId, System.Action`1[T] onDone) [0x00010] in Packages/com.mgw.sdk/Runtime/Core/Services/IAP/IapService.cs:NN
  at MyGame.UI.ShopScreen.OnBuyClicked () [0x00012] in Assets/Scripts/UI/ShopScreen.cs:45
  at UnityEngine.Events.InvokableCall.Invoke () [0x00000] in <...>:0

Stack trace luôn liệt kê frame đang chạy ở trên cùng, rồi tới nơi gọi nó. Ví dụ trên (minh họa, số dòng không thật) là một productId null bị truyền từ UI vào SDK: frame đầu thuộc .NET, frame kế là SDK, frame tiếp theo là mã game đã gọi.

Quy tắc phân tích:

1. Namespace TapBrain.Core.*: Nằm trong gói package com.mgw.sdk. Đây là các dịch vụ hạ tầng cốt lõi (Bootstrap, InitPipeline, ServiceLocator, IapService, SceneLoader, DialogService...). Nếu lỗi xuất phát từ đây, hãy kiểm tra xem bạn đã truyền tham số hợp lệ vào API hay chưa (ví dụ: Product ID có null/rỗng không, callback có bị null không).
2. Namespace TapBrain.Sdk.Mgw.*, TapBrain.Sdk.SayGames.* hoặc TapBrain.Sdk.Analytics.* (GameAnalytics/AppMetrica): Các lớp adapter kết nối với SDK bên thứ ba (Firebase, MAX, SayKit, GameAnalytics, AppMetrica). Lỗi ở đây thường liên quan tới trạng thái kết nối mạng, khởi tạo native hoặc thiếu key.
3. Frame thuộc mã nguồn game của bạn (ví dụ MyGame.*): Điểm kích hoạt lệnh gọi (nằm bên dưới frame SDK trong stack). Hãy kiểm tra các đối tượng UI, biến tham chiếu hoặc delegate được truyền vào SDK.

8. Checklist nghiệm thu từng tính năng trước khi Release

Trước khi xuất bản bản build chính thức lên cửa hàng ứng dụng, hãy hoàn thành bảng kiểm tra nghiệm thu từng tính năng dưới đây: