Chương 9: Chọn & Chuyển Provider (MGW ↔ SayKit)

Khám phá mô hình trừu tượng hóa Provider trong MGW SDK: quy tắc độc quyền chính xác một Provider cho mỗi bản build, bảng đối chiếu chuyên sâu giữa ngăn xếp MGW (Firebase + MAX) và SayKit, công cụ chuyển đổi tự động trong Editor, và kỹ thuật viết code gameplay an toàn chạy đa nền tảng.

1. Mục đích & Mô hình kiến trúc Provider

Trong quá trình phát triển game di động, studio có thể tự phát hành tựa game với hệ thống phân tích và quảng cáo riêng (ngăn xếp MGW gồm Firebase và AppLovin MAX), hoặc hợp tác phát hành với đơn vị bên ngoài yêu cầu bộ công cụ chuyên biệt của họ (tiêu biểu là SayKit từ SayGames).

Thay vì yêu cầu đội ngũ lập trình phải viết lại toàn bộ mã nguồn quản lý quảng cáo, mua hàng IAP hay luồng sự kiện phân tích, com.mgw.sdk thiết lập lớp trừu tượng thông qua interface ISdkProvider (kiểu internal của SDK: game không hiện thực hay gọi trực tiếp). Các dịch vụ cấp cao của game luôn gọi qua mặt nạ tĩnh App.Ads, App.Analytics, App.RemoteConfig, App.Iap và App.Review:

2. Bảng đối chiếu chi tiết MGW vs SayKit

Bảng dưới đây tổng hợp toàn diện sự khác biệt giữa hai ngăn xếp công nghệ để giúp bạn nắm rõ hành vi thực tế ở thời gian chạy và các yêu cầu tích hợp:

3. Các Scripting Define Symbols & Quy tắc quản lý

Kiến trúc của SDK chuyển đổi mã nguồn C# thông qua các cờ biên dịch (Scripting Defines). Mỗi nhóm define có nhiệm vụ và phạm vi hoạt động cụ thể:

4. Hướng dẫn chuyển đổi Provider trong Unity Editor

SDK cung cấp công cụ tự động hóa toàn diện cho việc chuyển đổi ngăn xếp SDK nằm trong menu Unity Editor:

A. Các lối vào chuyển đổi trong Unity Editor

• Chuyển sang SayKit: Menu TapBrain > SDK > Switch To SayKit...
• Chuyển về MGW: Menu TapBrain > SDK > Switch To MGW...
• Giao diện điều khiển: Menu TapBrain > SDK Settings... → Bấm nút Switch To <Tên Provider đối ứng>....

B. Cơ chế hoạt động của bộ chuyển đổi ngăn xếp SDK

Khi bạn xác nhận chuyển đổi, công cụ sẽ thực hiện tuần tự các bước nghiêm ngặt sau:

1. Cất giữ ngăn xếp rời đi (Park):
   • Sao chép toàn bộ các thư mục, file cấu hình và file .meta của Provider hiện tại ra một thư mục lưu trữ stash riêng bên ngoài Assets/ (tránh bị Unity import hay gây lỗi biên dịch).
   • Đối với MGW, các mục được cất giữ bao gồm: Assets/MaxSdk, Assets/GeneratedLocalRepo, các file thư viện Android Firebase trong Assets/Plugins/Android/, file Assets/google-services.json, Assets/GoogleService-Info.plist, cấu hình Crashlytics và thư mục GameAnalytics.
   • Đối với SayKit, các mục được cất giữ bao gồm: Assets/SayKit, Assets/SayKitExtensions, và Assets/Resources/SayKit.
   • Các file cấu hình build Android trong Assets/Plugins/Android/ (các file .gradle và AndroidManifest.xml) cũng được cất theo stack đang active.
   • Trích xuất các dependency và scoped registry thuộc sở hữu của provider rời đi ra khỏi Packages/manifest.json và lưu vào file trạng thái stack.json trong thư mục stash.
   • Thực hiện xóa an toàn các thư mục đã được cất khỏi Assets/ qua AssetDatabase.DeleteAssets.
2. Khôi phục ngăn xếp đích (Restore):
   • Nếu Provider đích đã từng được cất trước đó: Khôi phục toàn bộ file, dependency trong manifest, scoped registry, cờ bật tắt module và xóa thư mục stash của Provider đích.
   • Nếu là lần đầu chuyển sang SayKit: xóa Assets/SayKitExtensions/SayKitApp.cs (bản của trình cài đặt SayKit, tự gọi SayKit.init) và tạo Assets/SayKit/SayKitApp.cs từ file mẫu của SDK (không có hàm init).
3. Cập nhật cấu hình & Biên dịch lại:
   • Ghi đè file Packages/manifest.json (giữ nguyên chuẩn kết thúc dòng CRLF).
   • Cập nhật toàn bộ Scripting Defines tương ứng trên Android, iOS và Standalone thông qua SdkSettings.Apply.
   • Đặt CoreConfig.enableAppUpdateCheck = false khi chuyển sang SayKit (vì thư viện native Google Play Core phụ thuộc EDM4U vốn đã được gỡ bỏ cùng MGW); khi chuyển về MGW, giá trị cũ được khôi phục từ trạng thái đã cất.
   • Kích hoạt AssetDatabase.Refresh() và Client.Resolve() để Unity giải quyết package UPM và biên dịch lại code một lần duy nhất.

5. Quy trình thiết lập SayKit lần đầu cho dự án

Khi dự án bắt đầu tích hợp SayKit lần đầu tiên, hãy thực hiện theo đúng các bước sau:

Bước 1: Nhập gói SayKit Version Manager

Nhập file .unitypackage do SayGames cung cấp vào dự án. Gói này chỉ chứa file công cụ quản lý phiên bản SayKitVersionManager.dll.

Bước 2: Cài đặt SayKit qua Version Manager

Mở menu SayKit > Version Manager trên thanh công cụ Unity. Tiến hành cài đặt gói phiên bản SayKit (ví dụ 2026091100).

Bước 3: Thực hiện chuyển đổi Provider trên SDK

Chọn menu:

TapBrain > SDK > Switch To SayKit...

Hộp thoại xác nhận sẽ liệt kê toàn bộ các gói và thư mục MGW sẽ được cất giữ an toàn. Bấm Switch. Bộ chuyển đổi sẽ tự động dọn dẹp file cài đặt thừa và tạo file Assets/SayKit/SayKitApp.cs chuẩn hóa từ SDK.

Bước 4: Điền thông số Key và Remote Config

1. Mở file Assets/SayKit/SayKitApp.cs và thay các giá trị giữ chỗ dạng <...> bằng khóa do SayGames cấp. Chỉ sửa giá trị của các hằng số có sẵn: giữ nguyên tên class SayKitApp (namespace toàn cục) và tên các hằng số vì SayKit cùng SDK đọc chúng theo tên; không thêm hàm [RuntimeInitializeOnLoadMethod] (Build Guard sẽ chặn build).

// Assets/SayKit/SayKitApp.cs: only replace the placeholder values, keep every other generated member as it is.
public class SayKitApp
{
    public const string APP_NAME_IOS = "MyGame";
    public const string APP_BUNDLE_IOS = "com.mycompany.mygame";

    public const string APP_KEY_IOS = "your_saygames_ios_key";
    public const string APP_SECRET_IOS = "your_saygames_ios_secret";

    public const string APP_KEY_ANDROID = "your_saygames_android_key";
    public const string APP_SECRET_ANDROID = "your_saygames_android_secret";

    // ... other generated members (notificationsEnabled, PROMO_KEY_IOS, AD_INTERSTITIAL, AD_REWARDED...)
}

2. Khai báo các khóa Remote Config của game vào file Assets/SayKitExtensions/GameConfig/SayKitGameConfig.cs (thêm field vào class đã được Version Manager sinh ra). Tên field trùng với tên key Remote Config và giá trị khởi tạo là giá trị mặc định. Key không có field tương ứng sẽ chỉ dùng giá trị mặc định cục bộ (CoreConfig hoặc AddDefault). Các key inter_interval_sec/inter_first_delay_sec của AdsPolicy không cần khai báo vì SayKit không áp dụng AdsPolicy:

// Add fields to the existing SayKitGameConfig class; field name = Remote Config key, initial value = default.
public float coin_reward_multiplier = 2f;
public int daily_bonus_coins = 50;
public bool shop_banner_enabled = false;

Đồng bộ SayKitAppSettings.asset

SayKit đọc file Assets/Resources/SayKit/SayKitAppSettings.asset khi chạy; thiếu file này, Play mode trong Editor sẽ lỗi bên trong SayKit.init. Lớp SayKitSettingsSync của SDK tự tạo lại file này (qua importer của SayKit) sau mỗi lần biên dịch khi file đang thiếu; nó không ghi đè file đã tồn tại. Sau khi sửa khóa trong SayKitApp.cs, hãy chủ động đồng bộ qua menu (chỉ có khi stack SayKit đang được biên dịch):

TapBrain > SDK > Sync SayKit App Settings

6. Các quy tắc Build Guard theo từng Provider

Lớp CoreConfigTools (triển khai IPreprocessBuildWithReport) tự động rà soát tính hợp lệ trước khi Unity xuất bản bản build:

7. Bật tắt Module GameAnalytics & AppMetrica (Chỉ MGW)

Trên ngăn xếp MGW, bạn có thể tùy chọn tích hợp thêm GameAnalytics hoặc AppMetrica để theo dõi nâng cao:

1. Cài đặt package vào Packages/manifest.json (GameAnalytics qua OpenUPM: com.gameanalytics.sdk; AppMetrica qua Git URL: io.appmetrica.analytics).
2. Mở TapBrain > SDK Settings..., tích chọn Use GameAnalytics hoặc Use AppMetrica, sau đó nhấn nút Apply (recompiles) để cập nhật define symbols trên Android, iOS và Standalone. Nếu package chưa cài, cửa sổ cảnh báo module sẽ không biên dịch.
3. Mở CoreConfig.asset, đảm bảo các cờ thời gian chạy enableGameAnalytics hoặc enableAppMetrica được đặt thành true (mặc định đã bật). Điền appMetricaApiKey cho AppMetrica; khóa game/secret của GameAnalytics nằm trong cửa sổ GameAnalytics Settings, không nằm trong CoreConfig.
4. Bỏ chọn một module trong SDK Settings chỉ loại code của module khỏi biên dịch; package vẫn nằm trong manifest cho đến khi bạn gỡ thủ công.
5. Khi chuyển sang Provider SayKit, hai module này bị tắt, loại khỏi biên dịch và các package của chúng được cất khỏi manifest.json cùng stack MGW.

8. Cách viết Code Game tương thích an toàn đa Provider

Để đảm bảo dự án game của bạn có thể chuyển đổi qua lại giữa MGW và SayKit chỉ bằng một cú click chuột mà không phát sinh bất kỳ lỗi biên dịch nào, hãy tuân thủ triệt để các nguyên tắc sau:

Các nguyên tắc cốt lõi

• Tuyệt đối không gọi trực tiếp API của bên thứ ba: Không bao giờ gọi trực tiếp MaxSdk.*, Firebase.*, hay SayKit.* trong mã gameplay. Luôn gọi qua App.Ads, App.Iap, App.Analytics, App.RemoteConfig, App.Review.
• Bọc mã dịch vụ đặc thù MGW trong cờ điều kiện: Các dịch vụ chỉ có trên MGW (như FirebaseService, RealtimeDbService, BIService, NotificationService, namespace TapBrain.Sdk.Mgw) phải luôn được bọc trong khối #if !TB_SDK_SAYKIT, kể cả dòng using của namespace đó. Khi chuyển sang SayKit, assembly MGW không còn được biên dịch nên mã không bọc sẽ lỗi biên dịch (không phải lỗi lúc chạy).
• Dùng ServiceLocator.TryGet để truy xuất dịch vụ tùy chọn: Luôn kiểm tra xem dịch vụ có được đăng ký hay không trước khi sử dụng, và kiểm tra cờ sẵn sàng của dịch vụ (ví dụ IsReady).

So sánh Code Đúng vs Code Sai

using UnityEngine;
// WRONG: references a third-party SDK directly
using Firebase.Database;

namespace MyGame
{
    public class RewardManager : MonoBehaviour
    {
        public void ShowAd()
        {
            // WRONG: SayKit builds have no MaxSdk, so this fails to compile
            // as soon as the project is switched to SayKit.
            if (MaxSdk.IsRewardedAdReady("ad_unit_id"))
            {
                MaxSdk.ShowRewardedAd("ad_unit_id");
            }
        }

        public void SaveToCloud(string data)
        {
            // WRONG: not guarded by TB_SDK_SAYKIT and bypasses the SDK services
            var db = FirebaseDatabase.DefaultInstance;
            db.RootReference.Child("users").SetRawJsonValueAsync(data);
        }
    }
}

using UnityEngine;
using TapBrain.Core;
using TapBrain.Core.Services;
#if !TB_SDK_SAYKIT
using TapBrain.Sdk.Mgw; // MGW-only namespace: the using must be guarded too
#endif

namespace MyGame
{
    public class RewardManager : MonoBehaviour
    {
        public void ShowAd()
        {
            // RIGHT: go through the App.Ads facade.
            // It routes to MAX or SayKit depending on the compiled provider.
            if (App.Ads.IsRewardedReady)
            {
                App.Ads.ShowRewarded("double_reward", result =>
                {
                    // Grant only on Rewarded; Skipped / NotReady / Failed give nothing.
                    if (result == RewardedResult.Rewarded) GiveReward();
                });
            }
        }

        public void SaveToCloud(string path, string json)
        {
            // RIGHT: MGW-only service, guarded by #if !TB_SDK_SAYKIT
            // and resolved with ServiceLocator.TryGet.
#if !TB_SDK_SAYKIT
            if (ServiceLocator.TryGet<RealtimeDbService>(out var db) && db.IsReady)
            {
                db.SetJson(path, json, success =>
                {
                    Debug.Log($"[MyGame] Cloud sync: {success}");
                });
            }
#endif
        }

        private void GiveReward() { }
    }
}

Nếu game của bạn dùng asmdef riêng, asmdef đó phải tham chiếu TapBrain.Core (và thêm TapBrain.Sdk.MGW nếu dùng dịch vụ MGW, kèm điều kiện !TB_SDK_SAYKIT). Mã nằm trong Assembly-CSharp (không có asmdef) tự thấy các assembly SDK được biên dịch.

9. Hành vi thời gian chạy & Log Console kiểm chứng

Khi chạy game trong Unity Editor, Console hiển thị luồng khởi tạo tương ứng với Provider đang kích hoạt. Các dòng [Tag] message mức Info (như [Boot] ... done in ...) chỉ in khi CoreConfig.verboseLog bật hoặc khi chạy development build (trong Editor luôn in); cảnh báo và lỗi luôn in. Số liệu thời gian và số sản phẩm dưới đây chỉ là minh họa.

A. Dòng log chuẩn khi dùng Provider MGW

Trường hợp đã có đầy đủ key và cấu hình Firebase (các thông điệp chưa có key được liệt kê ở Chương 11):

[IAP] No IReceiptValidator registered: receipts accepted without local validation   (only if the game registered no validator)
[Boot] ATT done in 0.00s
[Firebase] Ready (Analytics + Crashlytics)
[Boot] Firebase done in 0.12s
[Boot] Auth done in 0.05s
[RemoteConfig] Fetched, activated=True
[Boot] RemoteConfig done in 0.08s
[RTDB] Ready at /my_game/debug
[Boot] RealtimeDb+BI done in 0.01s
[Ads] MAX initialized
[Boot] Ads done in 0.15s
[Boot] AppMetrica done in 0.01s                  (order of the two optional modules is not fixed)
[Boot] GameAnalytics done in 0.02s
[IAP] Ready, 3 products
[Boot] IAP done in 0.20s
[Boot] Notifications done in 0.01s
[Boot] Background done in 0.00s
[Boot] Completed, user=17300000001234 new=False session=12

B. Dòng log chuẩn khi dùng Provider SayKit

[IAP] No IReceiptValidator registered: receipts accepted without local validation   (only if the game registered no validator)
[Boot] SayKit done in 0.18s
[RemoteConfig] SayKit game config ready (3 fields)
[Boot] RemoteConfig done in 0.02s
[IAP] Ready, 3 products
[Boot] IAP done in 0.22s
[Boot] Background done in 0.01s
[Boot] Completed, user=17300000001234 new=False session=12

Lưu ý thứ tự: các dòng do bước tự in (như [Ads] MAX initialized, [IAP] Ready) xuất hiện trước dòng [Boot] <Bước> done của chính bước đó.

10. Checklist kiểm tra khi chuyển đổi Provider