Max Plugin

Đây là 1 Plugin có các Class Base để phục vụ Init, Load và Show Ads của Max và 1 một số tracking tự động với GSM

• Download GSM_Max_Plugin v0.0.2.0HybridAds.unitypackage

1. Điều kiện sử dụng

• Tích hợp GSM SDK V1.2.4.5 trở lên

Max Plugin Documentation

Tài liệu hướng dẫn sử dụng Max Plugin cho Unity - Tích hợp AppLovin MAX Ads với hệ thống GSM.

---

1. Cấu trúc thư mục và các Class

Assets/CSCMobiPlugin/MaxPlugin/
│
├── Scripts/
│   ├── MaxAdsRouter.cs                    (Abstract) Router chính - điều phối ads
│   ├── OneAdUnitIdMaxAdsController.cs     Controller cho 1 AdUnitId
│   ├── MultipleAdUnitIdMaxAdsController.cs Controller cho nhiều AdUnitId
│   ├── IMaxAdsInterface.cs                Interface chung cho controllers
│   │
│   ├── MaxAdsHybridController.cs          (Legacy) Controller cũ - nhiều AdUnitId
│   ├── BaseMaxAdsController.cs            (Legacy) Controller cũ - 1 AdUnitId
│   │
│   ├── GSMMaxInitialization.cs            Khởi tạo MAX SDK
│   ├── GSMMaxInfo.cs                      Thông tin MAX + cấu hình AppLovin
│   ├── MaxAdUnitConfig.cs                 MaxAdUnitConfig + MaxConfig (cấu hình từ GSM)
│   ├── MaxLoadStatus.cs                   Trạng thái load của AdUnit
│   ├── GSMMaxTracking.cs                  Tracking impressions
│   ├── GSMMaxCounterLog.cs                Counter log cho analytics
│   └── AndroidToast.cs                    Toast notification (Android)
│
├── Editor/
│   └── MaxPluginPreBuildProcessor.cs      Xử lý trước khi build
│
├── Resources/
│   └── ApplovinSettingData.json           Cấu hình AppLovin (runtime)
│
└── Documents/
    ├── README.md                          ← Tài liệu chính
    ├── README_MaxAdsHybridController.md   ← Tài liệu cũ (archived)
    └── CHANGE_LOG.md                      ← Lịch sử thay đổi

Mô tả ngắn gọn các Class

Class	Loại	Mô tả
MaxAdsRouter	Abstract	Router chính: đăng ký callbacks, chọn controller phù hợp, quản lý click tracking
OneAdUnitIdMaxAdsController	MonoBehaviour	Xử lý 1 Reward + 1 Interstitial AdUnitId
MultipleAdUnitIdMaxAdsController	MonoBehaviour	Xử lý nhiều AdUnitId: rotation, MaxLoadStatus, disable on fail
IMaxAdsInterface	Interface	Contract chung cho cả 2 controller (kế thừa IAdsInterface)
GSMMaxInitialization	Static	Quản lý khởi tạo MAX SDK, kiểm tra trạng thái init
GSMMaxInfo	Static	Lấy thông tin MAX, SDK key, network adapters, đọc GSMSettings
MaxConfig	Data	Cấu hình MAX từ GSM: retryDelay, delay load, auto load, adUnitConfig
MaxAdUnitConfig	Data	Cấu hình loadFailMax cho từng AdUnit
MaxLoadStatus	Data	Trạng thái: loadFailCount, isLoading, disabled
GSMMaxTracking	Singleton	Tracking ads events (load, show, click, hidden, revenue)
GSMMaxCounterLog	Static	Counter log cho analytics

---

2. GSMMaxInfo - Chức năng và cách sử dụng

2.1 Chức năng

GSMMaxInfo là class static chịu trách nhiệm:

1. Đọc cấu hình MAX từ GSMSettings

   • Ad Unit IDs cho Android và iOS

   • Platform detection (tự động chọn đúng danh sách theo platform)

2. Lấy SDK Key và thông tin network

   • Editor: Đọc từ AppLovinSettings asset

   • Runtime: Đọc từ ApplovinSettingData.json trong Resources

3. Gửi thông tin MAX lên GSM Core

   • SDK Key, MAX Version, danh sách AdUnitIds

   • Network adapter versions (AdMob, Facebook, Vungle, etc.)

   • AdMob App IDs

2.2 Cách hoạt động

Runtime Flow:
1. [RuntimeInitializeOnLoadMethod(AfterSceneLoad)]
   ↓
2. GSMMaxInfo.SetMaxInfo() được gọi
   ↓
3. Đọc GSMSettings → Lấy androidMAXUnitIds hoặc iosMAXUnitIds
   ↓
4. Đọc ApplovinSettingData.json → Lấy SDK Key, networks
   ↓
5. Tạo MAXInfo object
   ↓
6. GSMCore.Instance.SetMAXInfo(info, otherData)

---

3. MaxAdsRouter - Hướng dẫn sử dụng

3.1 Tổng quan

MaxAdsRouter là abstract class thay thế MaxAdsHybridController, với kiến trúc tách biệt:

• Router: Đăng ký callbacks MAX SDK, quản lý click tracking, chọn controller phù hợp

• Controller: Xử lý load/show/retry ads (1 hoặc nhiều AdUnitId)

Tự động chọn controller:

• Có ≥ 2 AdUnitId (Reward hoặc Interstitial) → MultipleAdUnitIdMaxAdsController

• Có 1 AdUnitId → OneAdUnitIdMaxAdsController

3.2 Kiến trúc

MaxAdsRouter (Abstract - kế thừa bởi game)
│
├── Callbacks: Đăng ký tất cả MAX SDK events
├── Click Tracking: isInterstitialClick, isRewardedClick
├── Config: MaxConfig từ GSM server
│
├── Tự động tạo 1 trong 2:
│   ├── OneAdUnitIdMaxAdsController      ← khi chỉ có 1 AdUnitId
│   └── MultipleAdUnitIdMaxAdsController ← khi có ≥ 2 AdUnitId
│
├── Interface:
│   ├── IsVideoRewardAdsReady()
│   ├── IsInterstitialAdsReady()
│   ├── LoadRewardedVideo()
│   ├── LoadInterstitial()
│   ├── ShowVideoAds(onReward, onClosed)
│   ├── ShowInterstitial(onClosed)
│   ├── ReleaseMarkAdClick()
│   ├── GetDefaultRewardVideoAdUnitId()
│   └── GetDefaultInterstitialAdUnitId()
│
├── Abstract (cần implement):
│   ├── GetTargetLevel()
│   ├── GetGroup()
│   ├── GetSubGroup()
│   └── GetUserType()
│
└── SerializeFields:
    ├── _autoLoadRewardVideo (default: true)
    └── _autoLoadInterstitial (default: true)

3.3 Flow khởi tạo

Awake()
  → InitializeRewardedAdCallbacks()      // Đăng ký Reward callbacks
  → InitializeInterstitialAdCallbacks()  // Đăng ký Interstitial callbacks
  → GetAdUnitIdFromGSMSettings()         // Lấy RewardDefault + InterstitialDefault
  → LoadCachedMaxConfig()                // Load config cũ từ PlayerPrefs
  → LoadGSMConfig()                      // Lấy MaxConfig mới từ server
  → InitAdUnitIdFromGSMServer()          // Lấy danh sách AdUnitId từ server (async)

Start()
  → WaitAndLoadAds()                     // Coroutine:
    → Chờ MAX SDK init
    → OnMaxSdkInitializedEventSuccess()
    → Chờ server response + config (timeout 5s)
    → CreateController()                 // Tạo One hoặc Multiple controller
    → SetMaxConfig()                     // Truyền config cho controller
    → SetAdUnitId()                      // Set default AdUnitId
    → SetAdUnitIds()                     // Set danh sách (Multiple dùng, One bỏ qua)
    → LoadRewardedVideo() / LoadInterstitial()

Sơ đồ (Mermaid):

Sơ đồ luồng: OneAdUnitIdMaxAdsController:

Sơ đồ luồng: MultipleAdUnitIdMaxAdsController:

3.4 Các method Abstract cần implement

public class MyMaxAdsController : MaxAdsRouter
{
    // Thông tin tracking - BẮT BUỘC implement
    protected override string GetTargetLevel()
    {
        return PlayerData.Instance.GetCurrentLevel().ToString();
    }

    protected override string GetGroup() => string.Empty;
    protected override string GetSubGroup() => string.Empty;
    protected override string GetUserType() => string.Empty;

    // Optional: override callback nếu cần
    protected override void OnMaxSdkInitializedEventSuccess(MaxSdkBase.SdkConfiguration sdkConfig)
    {
        Debug.Log("MAX SDK đã sẵn sàng!");
    }
}

3.5 Thiết lập AdUnitId trong GSMSettings

Trong GSMSettings Inspector, cấu hình AdUnitIds:

GSMSettings Inspector:
├── Android MAX Unit IDs:
│   ├── [0] adName: "RewardDefault",       adUnitId: "YOUR_REWARD_ID"
│   └── [1] adName: "InterstitialDefault", adUnitId: "YOUR_INTER_ID"

Nếu có nhiều AdUnitId (server sẽ trả về danh sách):

├── Server trả về:
│   ├── Rewarded: ["HIGH_ECPM_REWARD", "MED_REWARD", "DEFAULT_REWARD"]
│   └── Interstitial: ["HIGH_ECPM_INTER", "MED_INTER", "DEFAULT_INTER"]
│
│   → MaxAdsRouter tự động chọn MultipleAdUnitIdMaxAdsController
│   → Lần load đầu: Default. Từ lần 2: ưu tiên theo thứ tự list (eCPM cao → thấp)
│   → Giữ ad unit hiện tại cho đến khi fail, rồi chuyển sang ad tiếp theo

3.6 Cách sử dụng trong game

Kế thừa từ GSMAdManager để quản lý ads tập trung:

using GSM.Ads;
using UnityEngine;

public class AdsController : GSMAdManager
{
    public static AdsController Instance { get; private set; }

    private void Awake()
    {
        Instance = this;
    }

    #region Rewarded Video

    public bool IsRewardVideoAdsReady()
    {
        return base.IsRewardVideoAdsReady();
    }

    public void ShowVideoReward(System.Action onUserEarnedReward, System.Action onAdClosed)
    {
        if (IsRewardVideoAdsReady())
        {
            HideMREC();
            base.ShowVideoAds(onUserEarnedReward, onAdClosed);
        }
        else
        {
            Debug.Log("Reward ad đang tải...");
            onAdClosed?.Invoke();
        }
    }

    #endregion

    #region Interstitial

    public bool IsInterstitialAdsReady()
    {
        return base.IsInterstitialReady();
    }

    public void ShowInterstitial(System.Action onSuccessShow, System.Action onClose, System.Action onFailShow = null)
    {
        if (IsInterstitialAdsReady())
        {
            base.ShowInterstitial(
                onSuccess: () => { onSuccessShow?.Invoke(); },
                onAdClosed: () => { onClose?.Invoke(); }
            );
        }
        else
        {
            Debug.Log("Interstitial chưa sẵn sàng");
            onFailShow?.Invoke();
        }
    }

    #endregion
}

Sử dụng trong game:

public class GameManager : MonoBehaviour
{
    private AdsController _adsController;

    private void Start()
    {
        _adsController = AdsController.Instance;
    }

    public void ShowRewardForHint()
    {
        _adsController.ShowVideoReward(
            onUserEarnedReward: () =>
            {
                PlayerData.Instance.AddHint(1);
            },
            onAdClosed: () =>
            {
                Debug.Log("Reward ad đã đóng");
            }
        );
    }

    public void ShowInterstitialBetweenLevels()
    {
        _adsController.ShowInterstitial(
            onSuccessShow: () => { Debug.Log("Bắt đầu hiển thị Interstitial"); },
            onClose: () => { LoadNextLevel(); },
            onFailShow: () => { LoadNextLevel(); }
        );
    }
}

Cấu trúc trong Scene:

Hierarchy:
└── AdsController (GameObject)
    └── MaxAdsController (Component) ← Kéo vào Inspector (kế thừa MaxAdsRouter)
        └── [Tự động tạo] OneAdUnitIdMaxAdsController hoặc MultipleAdUnitIdMaxAdsController

Flow hoạt động:

1. GameManager gọi ShowVideoReward() hoặc ShowInterstitial()
   ↓
2. AdsController kiểm tra Is...Ready()
   ↓
3. Gọi base.Show...() từ GSMAdManager
   ↓
4. GSMAdManager gọi Show...() trên MaxAdsController (kế thừa MaxAdsRouter)
   ↓
5. MaxAdsRouter delegate cho controller (One hoặc Multiple) → hiển thị ad

3.7 MaxConfig – Cấu hình từ GSM

Cấu hình load/retry và từng AdUnit được đọc từ GSM config qua object maxConfig.

Cấu trúc MaxConfig:

Thuộc tính	Kiểu	Mặc định	Mô tả
adUnitConfig	Dictionary<string, MaxAdUnitConfig>	{}	Cấu hình theo từng AdUnitId
delayLoadAfterHiddenSeconds	int	1	Số giây chờ trước khi gọi load lại sau khi quảng cáo bị đóng
delayTimeoutSecond	float	5f	Thời gian chờ phản hồi tối đa của request load ads trước khi timeout
timeoutLoadRewardSeconds	int	0	Max thời gian load Video rào (Giây), = 0 là tắt
timeoutLoadInterSeconds	int	0	Max thời gian load Interstitial (Giây), = 0 là tắt
retryDelay	int	2	Cơ số retry: delay = retryDelay^attempt (giây), tối đa 6 lần → max 64s
retryMaxReward	int	10	Số lần retry load Reward Ads tối đa (OneAdUnit dùng global retry, MultipleAdUnit dùng loadFailCount trên mỗi AdUnitId).
retryMaxInter	int	10	Số lần retry load Interstitial Ads tối đa (OneAdUnit dùng global retry, MultipleAdUnit dùng loadFailCount trên mỗi AdUnitId).
isAutoLoadRewardVideo	bool?	null	Override auto load Reward (null = giữ giá trị Inspector)
isAutoLoadInterstitial	bool?	null	Override auto load Interstitial (null = giữ giá trị Inspector)

Lưu ý: MaxConfig (bao gồm delayTimeoutSecond sẽ được cache lại sử dụng PlayerPrefs qua khoá Prefs_Max_Config để tối ưu cho những lần mở máy không có mạng hoặc mạng chậm).

Cấu trúc MaxAdUnitConfig:

Thuộc tính	Kiểu	Mặc định	Mô tả
loadFailMax	int	2	Số lần fail tối đa trước khi loại AdUnit khỏi rotation (trừ default)

Ví dụ GSM Config (JSON):

{
    "maxConfig": {
        "retryDelay": 2,
        "retryMaxReward": 10,
        "retryMaxInter": 10,
        "isAutoLoadRewardVideo": true,
        "isAutoLoadInterstitial": true,
        "adUnitConfig": {
            "ca-app-pub-xxx-reward-high": {
                "loadFailMax": 3
            }
        }
    }
}

3.8 Cơ chế Fail và Retry

Load Fail Flow (OneAdUnitId):
1. Ad load thất bại
   ↓
2. Kiểm tra `retryMax`: Nếu đạt giới hạn cấu hình → Ngắt retry.
   ↓
3. Retry với delay = `retryDelay^attempt` (mặc định 2^n: 2s, 4s, 8s, 16s, 32s, 64s)

Load Fail Flow (MultipleAdUnitId):
1. Ad load thất bại trên 1 AdUnitId
   ↓
2. Tăng `loadFailCount` của AdUnitId đó.
   ↓
3. Kiểm tra `retryMax`: Nếu tổng fail vượt mức giới hạn → Ngắt retry.
   ↓
4. Nếu `loadFailCount` >= `loadFailMax` (của riêng AdUnitId, mặc định 2):
   → Loại bỏ thiết lập chờ và ngắt AdUnitId khỏi danh sách chêm vòng (Rotation), TRỪ adUnit mặc định.
   ↓
5. Delay với `retryDelay^attempt` rồi gọi thử load lại (sẽ chọn AdUnitId tiếp theo khả dụng).

Show Fail Protection:
1. ShowVideoAds() hoặc ShowInterstitial() được gọi
   ↓
2. try: OnApplicationPause() → MaxSdk.Show()
   ↓
3. catch (nếu MaxSdk.Show throw):
   → Tracking Exception

3.9 So sánh với MaxAdsHybridController

Tiêu chí	MaxAdsHybridController (cũ)	MaxAdsRouter (mới)
Kiến trúc	Monolithic (~900 dòng)	Router + Controller tách biệt
Callback registration	Trong class	Router đăng ký, delegate cho controller
Controller selection	Không	Tự động: One vs Multiple
Show exception protection	❌ Không	✅ try/catch + resume app
Null check adUnitId	❌ Thiếu	✅ Toàn bộ callbacks
State inconsistency check	Có	✅ Có (Multiple controller)
retryDelay default	4 (lên tới 4096s!)	2 (max 64s)
GSMMaxTracking safety	❌ Không try/catch	✅ try/catch tất cả callbacks

---

Version

Plugin Version: 0.0.2.0

Thay đổi 0.0.2.0:

• MultipleAdUnitIdMaxAdsController: Sửa lỗi conflict luồng tải quảng cáo ngầm khi đang hiển thị. Quảng cáo chỉ tiếp tục tải mới khi load fail hoặc sau khi user đóng lại.

• MultipleAdUnitIdMaxAdsController: Thêm cơ chế rotation theo thứ tự list AdUnitId. Lần load đầu luôn dùng Default. Từ lần thứ 2, ưu tiên AdUnitId đầu tiên khả dụng (High → Medium → Default). Giữ ad unit hiện tại cho đến khi fail thì tự chuyển sang tiếp theo.

Thay đổi 0.0.1.9:

• Loại bỏ hoàn toàn các Config Load Delay và định kỳ (rewardSecondDelayForLoad, interSecondDelayForLoad, periodicReloadRewardSeconds, periodicReloadInterSeconds).

• Loại bỏ hoàn toàn luồng hoạt động PeriodicReload và tính năng Delay Load sau khi tải xong (MultipleAdUnitIdMaxAdsController, OneAdUnitIdMaxAdsController, MaxAdsRouter).

• Loại bỏ các thiết lập Block Time (rewardShowBlockSeconds, rewardDisplayedBlockSeconds, vân vân) do nó không còn được sử dụng ở tiến trình đếm periodic.

• MaxConfig: Thêm delayLoadAfterHiddenSeconds (mặc định 1s) xử lý độ trễ load sau khi đóng Ads.

• MaxConfig: Thêm delayTimeoutSecond (mặc định 5s) và logic huỷ tiến trình nếu quảng cáo bị timeout.

• MaxConfig: Thêm cấu hình số lần retry tối đa retryMaxReward và retryMaxInter (mặc định 10 lần) áp dụng trên cả 2 phiên bản controller. Lưu ý MultipleAdUnitController đánh giá số lần fail trên từng AdUnitId độc lập bằng loadFailCount.

• MaxAdsRouter: Sử dụng chức năng lưu MaxConfig trực tiếp dưới cấu hình json vào PlayerPrefs để thiết lập ưu tiên nếu game mở offline không gọi dữ liệu từ server. Đọc chuỗi JSON qua Prefs_Max_Config.

• Bổ sung tracking Load_Reward_Timeout và Load_Inter_Timeout khi quá hiệu số chờ config.

• Xóa Coroutine Timeout nếu Ads Load Success/Fail xử lý memory leak.

Thay đổi 0.0.1.8:

• MaxAdsRouter: Thay thế MaxAdsHybridController làm controller chính. Tách kiến trúc thành Router + Controller.

• OneAdUnitIdMaxAdsController: Controller cho 1 AdUnitId, sử dụng MaxConfig.

• MultipleAdUnitIdMaxAdsController: Controller cho nhiều AdUnitId với rotation, MaxLoadStatus tracking, disable on fail, state inconsistency check.

• IMaxAdsInterface: Interface chung cho controllers.

• Show exception protection: try/catch bảo vệ ShowVideoAds/ShowInterstitial khỏi bị stuck.

• GSMMaxTracking: Thêm try/catch tất cả callbacks để không chặn callback chain.

• MaxConfig defaults: retryDelay 4→2, rewardSecondDelayForLoad 10→5, interSecondDelayForLoad 10→5.

Thay đổi 0.0.1.7:

• MaxAdsHybridController: Bỏ OnSdkInitializedEvent, thay bằng method OnMaxSdkInitializedEventSuccess.

• MaxAdsHybridController: Chuyển WaitMaxSDKInitSuccess và StartLoadAds từ Awake() xuống Start().

Thay đổi 0.0.1.6:

• MaxConfig: Cấu hình từ GSM gồm adUnitConfig, rewardSecondDelayForLoad, interSecondDelayForLoad, retryDelay, isAutoLoadRewardVideo, isAutoLoadInterstitial.

• Retry delay dùng công thức retryDelay^attempt.

• StartLoadAds: Chờ đủ ba điều kiện mới bắt đầu load ad.

Last Updated: 2026-03-16