Chương 2: Cài đặt & Cấu hình SDK

Hướng dẫn tích hợp gói UPM com.mgw.sdk cố định theo Git Tag, cài đặt các SDK bên thứ ba tương ứng, thiết lập thông số tập trung trong CoreConfig.asset, quản lý Scripting Defines qua cửa sổ SDK Settings và vượt qua các bài kiểm tra của chốt chặn Build Guard.

1. Mục đích & Quy chuẩn cài đặt

Để đảm bảo dự án game hoạt động ổn định và dễ dàng nâng cấp trong tương lai, SDK được phân phối dưới dạng gói Git UPM. Tất cả các dự án game khi cài đặt SDK bắt buộc phải ghim chặt (pin) vào một Git Tag phiên bản cụ thể (ví dụ #v0.1.0), tuyệt đối không trỏ vào nhánh main để tránh bị ảnh hưởng khi SDK cập nhật các thay đổi đột ngột.

2. Hướng dẫn cài đặt từng bước

Bước 1: Khai báo Package trong Packages/manifest.json

Mở file Packages/manifest.json trong thư mục dự án Unity của bạn và thêm dòng khai báo sau vào khối dependencies:

{
  "dependencies": {
    "com.mgw.sdk": "https://<git-host>/<org>/mgw-sdk.git#v0.1.0"
  }
}

Thay <git-host>/<org> bằng địa chỉ kho SDK mà team cung cấp. Các gói Unity mà SDK cần (com.unity.purchasing 5.3.1, com.unity.textmeshpro 3.0.9, com.unity.ugui 1.0.0, com.unity.ads.ios-support 1.0.0) được khai báo trong package.json của SDK nên Unity tự cài, bạn không cần thêm thủ công. Để nâng cấp, chỉ đổi tag (ví dụ #v0.1.0 sang #v0.2.0), đọc CHANGELOG.md của gói rồi để Unity resolve lại.

Bước 2: Cài đặt các SDK bên thứ ba theo Provider

Tùy thuộc vào Provider được chọn cho dự án, bạn cần cài đặt các gói thư viện tương ứng:

• Cho cả hai Provider: Google Play Plugins đặt trong Assets/GooglePlayPlugins/ (các asmdef Google.Play.Common, Google.Play.Core, Google.Play.AppUpdate, Google.Play.Review). Đây không phải gói UPM và không nằm trong package.json, nhưng TapBrain.Core luôn tham chiếu chúng: thiếu thì SDK không biên dịch được.
• Khi dùng Provider MGW (Mặc định):
  • AppLovin MAX SDK (thông qua Scoped Registry của AppLovin: gói com.applovin.mediation.ads).
  • Firebase Unity SDK bản 12.x (các gói tarball .tgz gồm: app, analytics, auth, crashlytics, database, remote-config).
  • External Dependency Manager for Unity (EDM4U).
  • Unity Mobile Notifications (com.unity.mobile.notifications).
  • Tùy chọn bổ trợ: GameAnalytics (com.gameanalytics.sdk) và AppMetrica (io.appmetrica.analytics).
• Khi dùng Provider SayKit:
  • SayKit SDK (gói io.saygames.saykit được tải qua SayKit Version Manager).
  • Lưu ý quan trọng: SayKit yêu cầu xóa bỏ hoàn toàn các gói AppLovin MAX, Firebase, EDM, GameAnalytics và AppMetrica khỏi dự án (Build Guard chặn build nếu còn sót). Menu TapBrain > SDK > Switch To SayKit... tự gỡ và cất chúng sang một thư mục lưu trữ ngoài Assets/ (khôi phục khi chuyển lại MGW); lần chuyển đầu tiên đòi hỏi gói io.saygames.saykit đã được cài sẵn.

Bước 3: Tạo và định vị CoreConfig.asset

SDK yêu cầu một file cấu hình duy nhất dạng ScriptableObject tên là CoreConfig.asset nằm trong bất kỳ thư mục Resources/ nào của dự án (ví dụ: Assets/Resources/CoreConfig.asset).

Trong Unity Editor, bạn chỉ cần chọn menu:

TapBrain > Select Core Config

Nếu file chưa tồn tại, công cụ sẽ tự động tạo mới file tại Assets/Resources/CoreConfig.asset và ping chọn file đó trong cửa sổ Project. (Editor cũng tự tạo file mặc định này sau mỗi lần biên dịch lại nếu dự án chưa có Resources/CoreConfig.asset.) Nếu có hơn một file Resources/CoreConfig.asset, SDK cảnh báo [CoreConfig] More than one Resources/CoreConfig.asset; keep one: hãy giữ lại đúng một file.

3. Bảng phân nhóm toàn bộ các trường trong CoreConfig

Class CoreConfig (namespace TapBrain.Core) là trung tâm lưu trữ toàn bộ các mã định danh và thiết lập thời gian chạy của SDK:

4. Cửa sổ SDK Settings & Scripting Defines

Các hằng số tiền xử lý biên dịch (Scripting Defines) quyết định assembly nào được đưa vào bản build. Để tránh xung đột nền tảng, tuyệt đối không chỉnh sửa Define Symbols thủ công trong Project Settings. Hãy sử dụng cửa sổ chuyên dụng của SDK:

TapBrain > SDK Settings...

Cửa sổ này hiển thị Provider hiện tại, nút Switch To ... (cùng hộp thoại xác nhận như menu TapBrain > SDK > Switch To ...) và các checkbox của provider đang dùng: với MGW là Use GameAnalytics / Use AppMetrica, với SayKit là SayKit push notifications (GameAnalytics và AppMetrica luôn tắt). Khi bạn nhấn Apply (recompiles), hệ thống đồng bộ cùng lúc cho cả 3 nền tảng: Android, iOS và Standalone (Editor) rồi biên dịch lại. Bỏ chọn một module chỉ loại code của nó khỏi build; gói SDK vẫn nằm trong dự án cho tới khi bạn gỡ.

Bảng ý nghĩa các Scripting Define Symbols

5. Danh mục Key & File cấu hình mỗi Game phải cung cấp

Gói com.mgw.sdk được phát hành công khai hoàn toàn không chứa bất kỳ key hoặc file bí mật nào. Mỗi game khi chuẩn bị phát hành cần tự điền các thông số sau:

A. Dành riêng cho Provider MGW

• Firebase Android Config: File Assets/google-services.json tải từ Firebase Console. Build Guard kiểm tra file này khi build Android (nếu enableFirebase bật).
• Firebase iOS Config: File Assets/GoogleService-Info.plist tải từ Firebase Console. Build Guard kiểm tra khi build iOS.
• Cấu hình trên Firebase Console (không phải file): bật Anonymous Auth, tạo Realtime Database với rule auth != null và tạo các key Remote Config trùng tên với key game đọc. Build Guard không kiểm tra mục này.
• AppLovin MAX SDK Key & Ad Units: Điền vào các trường tương ứng trong CoreConfig.asset. Ngoài ra cần dán SDK Key vào cửa sổ AppLovin > Integration Manager.
• AdMob App ID: Cấu hình trong cửa sổ AppLovin > Integration Manager (phải là ID thật của game, không để ID test công khai của Google ca-app-pub-3940256099942544~...). Build Guard không kiểm tra mục này, hãy tự kiểm tra trước khi phát hành.
• GameAnalytics Keys: Mở Window > GameAnalytics > Select Settings, đăng nhập và chọn game tương ứng. Build Guard không kiểm tra mục này.
• AppMetrica API Key: Điền vào trường CoreConfig.appMetricaApiKey.

B. Dùng chung cho cả hai Provider

• Mã định danh ứng dụng (Package Name / Bundle Identifier): Thiết lập trong Player Settings. Build Guard từ chối build (Bundle id is still the template id) nếu id còn bắt đầu bằng com.tapbrain.template; hãy đặt id thật của game.
• iOS App Store ID: Điền vào CoreConfig.iosAppStoreId (Build Guard kiểm tra). androidPackageName và privacyPolicyUrl không được kiểm tra.
• Danh mục sản phẩm IAP: File Assets/Resources/IAPProductCatalog.json (tạo qua cửa sổ Unity IAP Catalog) và CoreConfig.removeAdsProductId nếu có sản phẩm xóa quảng cáo. Tạo cùng id trên Google Play Console và App Store Connect.
• Khóa giải mã hóa đơn IAP (Tangles): Mở Services > In-App Purchasing > Receipt Validation Obfuscator, dán Google Play license key để sinh các file *Tangle.cs. Lưu ý: SDK chỉ kiểm tra hóa đơn khi game đăng ký một IReceiptValidator (qua SdkModules.RegisterReceiptValidator từ một hàm [RuntimeInitializeOnLoadMethod(AfterAssembliesLoaded)], dùng các tangle làm khóa). Nếu chưa đăng ký, SDK ghi log [IAP] No IReceiptValidator registered... và chấp nhận mọi hóa đơn, không xác thực.
• Liên kết Unity Gaming Services: Liên kết dự án trong Project Settings > Services. Nếu chưa liên kết, IAP vẫn chạy nhưng ghi cảnh báo [IAP] Unity Gaming Services init failed (project not linked?)....

C. Dành riêng cho Provider SayKit

• SayKit App Keys: Điền các hằng số APP_KEY_ANDROID, APP_KEY_IOS, APP_NAME_IOS, APP_BUNDLE_IOS trong file Assets/SayKit/SayKitApp.cs (Build Guard kiểm tra bốn hằng số này; các hằng số còn lại như APP_SECRET_* do SayGames cấp riêng và không được kiểm tra). File này chỉ chứa khóa: không tự gọi SayKit.init, vì SDK đã gọi.
• Remote Config của SayKit: khai báo các key game đọc thành field trong Assets/SayKitExtensions/GameConfig/SayKitGameConfig.cs (tên field = tên key, giá trị = mặc định).

6. Chốt chặn Build Guard & Cách xử lý lỗi

Lớp CoreConfigTools triển khai interface IPreprocessBuildWithReport để tự động rà soát toàn bộ dự án trước khi xuất bản bản build.

Bảng tra cứu lỗi Build Guard

7. Kiểm tra tính hợp lệ của cấu hình trong Editor

Bạn không cần phải đợi tới lúc bấm Build mới phát hiện ra lỗi. Hãy sử dụng menu:

TapBrain > Validate Core Config

Nếu mọi thông số đã chuẩn xác, Console sẽ in một dòng log thông thường (Debug.Log):

[CoreConfig] OK, no placeholders left

Ngược lại, nếu còn mục chưa điền, hệ thống in một cảnh báo (Warning) liệt kê từng mục (kiểm tra theo nền tảng đang chọn trong Build Settings; danh sách dưới đây chỉ là ví dụ):

[CoreConfig] Placeholders left:
- Assets/google-services.json (Firebase Android config)
- MAX SDK key (Android)
- Banner ad unit (Android)
- iOS App Store id

8. Checklist kiểm tra nhanh