Hướng dẫn sử dụng TapBrain MGW SDK (`com.mgw.sdk`)

Dành cho Lập trình viên Unity (Junior & Mid)

Chào mừng bạn đến với tài liệu kỹ thuật của MGW SDK (Unity package com.mgw.sdk). Tài liệu này hướng dẫn chi tiết cách cài đặt package vào dự án game của bạn, cấu hình thông số và gọi các API công khai của SDK để vận hành quảng cáo, mua hàng trong ứng dụng, theo dõi chỉ số, cấu hình từ xa và quản lý giao diện.

1. MGW SDK là gì?

Trong phát triển game mobile thương mại, việc tích hợp nhiều SDK bên thứ ba (quảng cáo, thanh toán, phân tích, cấu hình từ xa) thường tốn nhiều thời gian và dễ phát sinh lỗi nghiêm trọng:

Mất đơn hàng IAP: Game bị tắt ngang hoặc mất kết nối mạng khi đang mua hàng khiến người chơi bị trừ tiền nhưng không nhận được vật phẩm.
Treo màn hình mở đầu: Khi mạng chập chờn hoặc dịch vụ đám mây phản hồi chậm, game bị đóng băng vô hạn ở màn hình khởi động.
Tần suất quảng cáo không kiểm soát: Quảng cáo toàn màn hình hiển thị quá dày đặc gây ức chế người chơi.
Sai sót cấu hình: Quên điền mã định danh quảng cáo thật hoặc để sót mã thử nghiệm khi xuất bản bản phát hành.

Package com.mgw.sdk ra đời nhằm giải quyết triệt để các rủi ro này. Đây là một Unity Package (tương thích Unity 2022.3 LTS, iOS và Android) đóng gói toàn bộ hạ tầng dịch vụ cốt lõi:

Facade App.X tinh gọn: Truy cập mọi dịch vụ qua các thuộc tính tĩnh không trạng thái (App.Ads, App.Iap, App.Analytics, App.RemoteConfig, App.Dialogs, App.Scenes...).
Kiến trúc Provider linh hoạt: Chọn chạy trên hạ tầng MGW (Firebase + AppLovin MAX) hoặc SayKit (SayGames) bằng menu chuyển đổi trong Editor (có hộp thoại xác nhận; SDK tự cất/khôi phục gói và biên dịch lại). Mã game gọi qua App.X không đổi; riêng các dịch vụ chỉ có ở MGW phải bọc trong #if !TB_SDK_SAYKIT.
Luồng khởi động an toàn (Boot Pipeline): Mỗi bước khởi động đều được giới hạn thời gian (timeout) và bọc lớp bảo vệ lỗi: bước lỗi hoặc quá giờ chỉ bị ghi log rồi bỏ qua để pipeline chạy tiếp, nên ngoại tuyến hay thiếu key không làm treo màn hình khởi động.
Chốt chặn kiểm tra tự động (Build Guard): Tự động chặn build nếu không có provider nào được biên dịch hoặc cấu hình SayKit sai; với bản Release, còn sót giá trị mặc định (REPLACE_ME) hoặc thiếu file Firebase cũng làm build thất bại (bản Development chỉ cảnh báo).

2. Bản đồ tài liệu (Link Map)

Chương	Tên trang	Nội dung trọng tâm	Đối tượng / Tình huống
Chương 1	Tổng quan & Kiến trúc SDK	Gói UPM, Facade `App.X`, ServiceLocator, Provider MGW / SayKit, Boot Pipeline, Service Readiness.	Tất cả lập trình viên cần nắm trước khi viết code.
Chương 2	Cài đặt & Cấu hình	Cài đặt UPM qua Git Tag, gói phụ thuộc, `CoreConfig`, Scripting Defines, chốt chặn Build Guard.	Lần đầu cài SDK vào dự án hoặc chuẩn bị cấu hình xuất bản.
Chương 3	Quảng cáo (App.Ads)	Banner, Interstitial, Rewarded, App Open, chính sách tần suất AdsPolicy, xóa quảng cáo, Mediation Debugger.	Gắn vị trí quảng cáo thưởng, màn hình kết thúc màn chơi.
Chương 4	In-App Purchase (App.Iap)	Hợp đồng `PurchaseGrantHandler`, quy trình 2 bước chống mất đơn, Local Receipt Validation (tangles), khôi phục mua hàng.	Dựng hệ thống bán gói vật phẩm, mua tiền tệ, tính năng xóa quảng cáo.
Chương 5	Analytics & Tracking	API sự kiện thống nhất, bảng ánh xạ tham số tự động, đo lường `duration_sec`, sự kiện doanh thu tự động.	Gắn tracking tiến độ màn chơi, luồng hướng dẫn, chi tiêu tiền tệ.
Chương 6	Remote Config	Cơ chế Typed `Bind<T>`, giá trị mặc định ngoại tuyến, ép dải kiểu số an toàn, sự kiện cập nhật.	Cân bằng game từ xa, A/B testing các chỉ số kinh tế.
Chương 7	Hạ tầng & UI	ServiceLocator, DialogService, DialogQueue, SceneLoader, UIOverlay, LocalStorage, Audio, Haptic, CoreHost.	Quản lý hàng đợi popup, chuyển scene mượt mà, lưu trữ dữ liệu nội bộ.
Chương 8	Dịch vụ nền tảng & MGW-only	ATT (iOS), Đánh giá App, Cập nhật App, Search Ads, Firebase, Realtime DB, BI Profile, Thông báo cục bộ.	Triển khai tính năng đánh giá, nhắc nhở giờ chơi, đồng bộ hồ sơ BI.
Chương 9	Chọn & Chuyển Provider	So sánh MGW vs SayKit, menu chuyển đổi trong Editor, kỹ thuật viết code tương thích cả 2 nền tảng.	Khi studio hợp tác cùng SayGames hoặc xuất bản độc lập với MGW.
Chương 10	Thực hành End-to-End	Bài thực hành mẫu hoàn chỉnh: cấp phát IAP, gắn remote config, xem video nhận x2 thưởng, kích hoạt mua hàng.	Dành cho bạn mới: làm theo từng bước để nắm trọn luồng vận hành.
Chương 11	Kiểm tra & Gỡ lỗi	Chuỗi log khởi động chuẩn, phân biệt log bình thường vs lỗi, bảng chẩn đoán triệu chứng - nguyên nhân - cách sửa.	Khi gặp lỗi biên dịch, build thất bại hoặc dịch vụ không phản hồi.
Chương 12	Tra cứu nhanh & Quy chuẩn	Bảng tra cứu toàn bộ thành viên `App.X`, quy tắc vàng cho mã nguồn game, bảng thuật ngữ, câu hỏi thường gặp (FAQ).	Tra cứu nhanh khi đang code hoặc rà soát tiêu chuẩn trước khi tạo PR.

3. Lộ trình học gợi ý trong 7 ngày

Ngày 1: Nắm vững Kiến trúc, Boot Pipeline & Cài đặt

Đọc Chương 1 và Chương 2. Hiểu cách package vận hành độc lập, quy trình khởi động (tối đa 11 bước với MGW, 4 bước với SayKit) và cách cấu hình file CoreConfig.asset.

Ngày 2: Quảng cáo & Chính sách tần suất

Đọc Chương 3. Nắm vững hợp đồng của TryShowInterstitial (callback đóng luôn gọi đúng 1 lần) và ShowRewarded (chỉ trao thưởng khi kết quả là RewardedResult.Rewarded).

Ngày 3: In-App Purchase & Cơ chế chống mất đơn hàng

Đọc Chương 4. Hiểu quy trình 2 bước: SetGrantHandler chỉ trả về true khi đã cộng vật phẩm và lưu file thành công; tìm hiểu tính năng tự động vô hiệu hóa quảng cáo khi mua Remove Ads.

Ngày 4: Analytics & Remote Config

Đọc Chương 5 và Chương 6. Sử dụng bộ sự kiện chuẩn của App.Analytics; dùng cơ chế App.RemoteConfig.Bind để tự động ánh xạ cấu hình từ xa vào class C#.

Ngày 5: Hạ tầng UI & Dịch vụ nền tảng

Đọc Chương 7 và Chương 8. Sử dụng DialogQueue để hiển thị popup theo độ ưu tiên, chuyển scene an toàn với SceneLoader, và cấu hình thông báo cục bộ với NotificationService (chỉ có ở provider MGW).

Ngày 6: Provider MGW vs SayKit & Thực hành End-to-End

Đọc Chương 9 và làm theo hướng dẫn tại Chương 10 để tích hợp toàn bộ các dịch vụ trên vào một vòng lặp game hoàn chỉnh.

Ngày 7: Kiểm tra, Gỡ lỗi & Rà soát quy chuẩn

Đọc Chương 11 và Chương 12. Ghi nhớ các quy chuẩn viết code hiệu năng cao, cách đọc thông báo của Build Guard và xử lý các tình huống lỗi thường gặp.

4. Bảng tra cứu các lệnh thường dùng

Nhu cầu thực hiện	Dòng code hoặc thao tác tương ứng
Hiện quảng cáo chèn (Interstitial)	`App.Ads.TryShowInterstitial("level_end", () => OnNextLevel());`
Hiện quảng cáo nhận thưởng (Rewarded)	`App.Ads.ShowRewarded("double_reward", res => { if (res == RewardedResult.Rewarded) GrantReward(); });`
Khởi tạo mua gói IAP	`App.Iap.Purchase("coin_pack_small", res => UpdateShopUI(res));`
Đăng ký bộ xử lý trao thưởng IAP (chỉ trả về `true` khi đã giao vật phẩm và lưu xong)	`App.Iap.SetGrantHandler(productId => Inventory.Deliver(productId));`
Gửi sự kiện kết thúc màn chơi	`App.Analytics.LevelCompleted(level: 5, score: 1200);`
Ánh xạ biến Remote Config tự động	`App.RemoteConfig.Bind(myConfigInstance);`
Mở một hộp thoại (Popup)	`App.Dialogs.Show<ShopDialog>();`
Chuyển Scene có hiệu ứng mờ dần (Fade)	`App.Scenes.Load(buildIndex: 1);`
Lưu dữ liệu máy người chơi an toàn	`LocalStorage.SetInt("game.coins", 500); LocalStorage.Save();`
Kiểm tra tính hợp lệ của cấu hình SDK	Unity Menu: `TapBrain > Validate Core Config`
Mở cửa sổ thiết lập Scripting Defines	Unity Menu: `TapBrain > SDK Settings...`
Chuyển đổi Provider sang SayKit hoặc MGW	Unity Menu: `TapBrain > SDK > Switch To SayKit... / Switch To MGW...`