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.1.5_HybridAds.unitypackage

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

• Tích hợp GSM SDK V1.2.4.4 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/
│   ├── MaxAdsHybridController.cs          (Abstract) Controller chính - nhiều AdUnitId
│   ├── BaseMaxAdsController.cs            (Abstract) Controller cơ bản - 1 AdUnitId
│   │
│   ├── GSMMaxInitialization.cs            Khởi tạo MAX SDK
│   ├── GSMMaxInfo.cs                      Thông tin MAX + cấu hình AppLovin
│   ├── MaxAdUnitConfig.cs                 Cấu hình loadFailMax cho từng AdUnit
│   ├── 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

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

Class	Loại	Mô tả
MaxAdsHybridController	Abstract	Controller nâng cao: nhiều AdUnitId, rotation theo eCPM, override từ GSM server
BaseMaxAdsController	Abstract	Controller cơ bản: 1 Interstitial + 1 Rewarded cố định
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
MaxAdUnitConfig	Data	Cấu hình loadFailMax cho từng AdUnit
MaxLoadStatus	Data	Trạng thái: loadFailCount, isLoading, disabled
GSMMaxTracking	Static	Gửi tracking khi load ad
GSMMaxCounterLog	Static	Counter log cho analytics
AndroidToast	Static	Hiển thị toast trên Android

---

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

4. Hỗ trợ build

   • Tự động tạo ApplovinSettingData.json khi build

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. MaxAdsHybridController - Hướng dẫn sử dụng

3.1 Tổng quan

MaxAdsHybridController là abstract class quản lý quảng cáo MAX với các tính năng:

• Nhiều AdUnitId: Hỗ trợ danh sách AdUnitId theo thứ tự eCPM (Cao → Trung → Thấp)

• Tự động rotation: Chuyển sang AdUnitId tiếp theo khi fail

• Override từ GSM Server: Có thể lấy danh sách AdUnitId từ server

• Config riêng từng AdUnit: loadFailMax có thể config qua GSM config

• Auto retry: Retry với delay tăng dần (2^n giây, max 64s)

3.2 Kiến trúc

MaxAdsHybridController (Abstract)
│
├── rewardAdUnitIds: List<string>          // Danh sách Reward AdUnitIds theo format: Reward0, Reward1, RewardDefault
├── interAdUnitIds: List<string>           // Danh sách Interstitial AdUnitIds theo format: Interstitial0, Interstitial1, InterstitialDefault
│
├── _defaultAdRewardUnitId: string         // Từ "RewardDefault"
├── _defaultAdInterUnitId: string          // Từ "InterstitialDefault"
│
├── dictLoadRewardStatus: Dictionary<string, MaxLoadStatus>
├── dictLoadInterStatus: Dictionary<string, MaxLoadStatus>
│
├── Methods:
│   ├── GetDefaultRewardVideoAdUnitId()    [Public]
│   ├── GetDefaultInterstitialAdUnitId()   [Public]
│   ├── GetTargetLevel()                   [Abstract]
│   ├── GetGroup()                         [Abstract]
│   ├── GetSubGroup()                      [Abstract]
│   ├── GetUserType()                      [Abstract]
│   │
│   ├── LoadRewardedVideo()
│   ├── LoadInterstitial()
│   ├── ShowVideoAds(onReward, onClosed)
│   ├── ShowInterstitial(onClosed)
│   ├── IsVideoRewardAdsReady()
│   ├── IsInterstitialAdsReady()
│   └── ReleaseMarkAdClick()
│
└── SerializeFields:
    ├── IsAutoLoadRewardVideo
    └── IsAutoLoadInterstitial

3.3 Các method Abstract cần implement

Format AdUnitId (CỐ ĐỊNH):

Hệ thống quy định chặt chẽ format tên AdUnitId như sau:

Loại	Format	Ví dụ	Ghi chú
Rewarded	Reward + số thứ tự	Reward0, Reward1, Reward2...	Sắp xếp theo eCPM (0 = cao nhất)
Rewarded Default	RewardDefault	RewardDefault	Luôn ở cuối danh sách
Interstitial	Interstitial + số thứ tự	Interstitial0, Interstitial1, Interstitial2...	Sắp xếp theo eCPM (0 = cao nhất)
Interstitial Default	InterstitialDefault	InterstitialDefault	Luôn ở cuối danh sách

public abstract class MaxAdsHybridController : MonoBehaviour, IAdsInterface
{
    // Hệ thống tự động lấy AdUnitId từ GSMSettings theo format CỐ ĐỊNH:
    // - "Reward0", "Reward1", "Reward2"... → rewardAdUnitIds (SORT THEO THỨ TỰ SỐ TĂNG DẦN)
    // - "RewardDefault" → _defaultAdRewardUnitId (luôn ở cuối danh sách)
    // - "Interstitial0", "Interstitial1", "Interstitial2"... → interAdUnitIds (SORT THEO THỨ TỰ SỐ TĂNG DẦN)
    // - "InterstitialDefault" → _defaultAdInterUnitId (luôn ở cuối danh sách)

    // Bạn KHÔNG cần implement các method để lấy AdUnitId!

    // Thông tin tracking
    protected abstract string GetTargetLevel();
    protected abstract string GetGroup();
    protected abstract string GetSubGroup();
    protected abstract string GetUserType();
}

Các method public để truy xuất AdUnitId mặc định:

public string GetDefaultRewardVideoAdUnitId() => _defaultAdRewardUnitId;
public string GetDefaultInterstitialAdUnitId() => _defaultAdInterUnitId;

3.4 Ví dụ triển khai hoàn chỉnh

using System.Collections.Generic;
using UnityEngine;
using GSM.Core;
using GSM.Models.Mediations;

public class MyMaxAdsController : MaxAdsHybridController, IAdsInterface
{
    // Ad Unit IDs được lấy TỰ ĐỘNG từ GSMSettings theo format CỐ ĐỊNH:
    // - "Reward0", "Reward1", "Reward2"... → rewardAdUnitIds (SORT THEO THỨ TỰ SỐ TĂNG DẦN)
    // - "RewardDefault" → GetDefaultRewardVideoAdUnitId()
    // - "Interstitial0", "Interstitial1", "Interstitial2"... → interAdUnitIds (SORT THEO THỨ TỰ SỐ TĂNG DẦN)
    // - "InterstitialDefault" → GetDefaultInterstitialAdUnitId()

    #region Thông tin tracking

    protected override string GetTargetLevel()
    {
        return PlayerData.Instance.GetCurrentLevel().ToString(); // Đây là ví dụ
    }

    protected override string GetGroup()
    {
        return string.Empty; // Nếu có thì trả về
    }

    protected override string GetSubGroup()
    {
        return string.Empty; // Nếu có thì trả về
    }

    protected override string GetUserType()
    {
        return string.Empty; // Nếu có thì trả về
    }

    #endregion
}

Lưu ý quan trọng:

• Base class tự động lấy AdUnitId từ GSMSettings trong Awake()

• Chỉ cần implement các method tracking (GetTargetLevel, GetGroup, GetSubGroup, GetUserType)

3.5 Thiết lập AdUnitId trong GSMSettings

QUAN TRỌNG: Format tên AdUnitId (adName) là CỐ ĐỊNH, bắt buộc phải theo đúng quy tắc bên dưới:

Trong GSMSettings Inspector, bạn cấu hình AdUnitIds với các adName đúng format:

GSMSettings Inspector:
├── Android MAX Unit IDs:
│   ├── [0] adName: "Reward0",         adUnitId: "YOUR_HIGH_ECPM_REWARD_ID"      ← eCPM cao nhất
│   ├── [1] adName: "Reward1",         adUnitId: "YOUR_MEDIUM_ECPM_REWARD_ID"    ← eCPM trung bình
│   ├── [2] adName: "RewardDefault",   adUnitId: "YOUR_DEFAULT_REWARD_ID"         ← Mặc định (luôn ở cuối)
│   ├── [3] adName: "Interstitial0",   adUnitId: "YOUR_HIGH_ECPM_INTER_ID"        ← eCPM cao nhất
│   ├── [4] adName: "Interstitial1",   adUnitId: "YOUR_MEDIUM_ECPM_INTER_ID"      ← eCPM trung bình
│   └── [5] adName: "InterstitialDefault", adUnitId: "YOUR_DEFAULT_INTER_ID"     ← Mặc định (luôn ở cuối)
│
└── iOS MAX Unit IDs:
    ├── [0] adName: "Reward0",         adUnitId: "YOUR_IOS_HIGH_REWARD_ID"
    ├── [1] adName: "Reward1",         adUnitId: "YOUR_IOS_MEDIUM_REWARD_ID"
    ├── [2] adName: "RewardDefault",   adUnitId: "YOUR_IOS_DEFAULT_REWARD_ID"
    ├── [3] adName: "Interstitial0",   adUnitId: "YOUR_IOS_HIGH_INTER_ID"
    ├── [4] adName: "Interstitial1",   adUnitId: "YOUR_IOS_MEDIUM_INTER_ID"
    └── [5] adName: "InterstitialDefault", adUnitId: "YOUR_IOS_DEFAULT_INTER_ID"

Quy tắc đặt tên (CỐ ĐỊNH):

• Reward0, Reward1, Reward2... → Tự động được thêm vào rewardAdUnitIds theo thứ tự số tăng dần

• RewardDefault → Luôn ở cuối danh sách rewardAdUnitIds

• Interstitial0, Interstitial1, Interstitial2... → Tự động được thêm vào interAdUnitIds theo thứ tự số tăng dần

• InterstitialDefault → Luôn ở cuối danh sách interAdUnitIds

Lưu ý: Tên AdUnitId phải tuân thủ đúng format trên. Nếu đặt sai tên (ví dụ: RewardedVideo thay vì Reward0), hệ thống sẽ không nhận diện được.

Ví dụ kết quả:

• Nếu có: Reward5, Reward1, Reward3, RewardDefault

• → rewardAdUnitIds = ["id_of_Reward1", "id_of_Reward3", "id_of_Reward5", "id_of_RewardDefault"]

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(); // Ẩn MREC khi show video
            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
{
    // Lấy instance từ scene
    private AdsController _adsController;

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

    // Hiển thị Interstitial (ví dụ: giữa các level)
    public void ShowInterstitialBetweenLevels()
    {
        _adsController.ShowInterstitial(
            onSuccessShow: () =>
            {
                Debug.Log("Bắt đầu hiển thị Interstitial");
            },
            onClose: () =>
            {
                Debug.Log("Interstitial đã đóng");
                LoadNextLevel(); // Chuyển sang level tiếp theo
            },
            onFailShow: () =>
            {
                Debug.Log("Interstitial không khả dụng, chuyển level luôn");
                LoadNextLevel();
            }
        );
    }

    // Hiển thị Rewarded Video (ví dụ: khi người chơi xin thêm hint)
    public void ShowRewardForHint()
    {
        _adsController.ShowVideoReward(
            onUserEarnedReward: () =>
            {
                // User xem hết ad, nhận thưởng
                PlayerData.Instance.AddHint(1);
                UIManager.Instance.ShowMessage("Bạn nhận được 1 hint!");
            },
            onAdClosed: () =>
            {
                // Ad đã đóng (kể cả khi không xem hết)
                Debug.Log("Reward ad đã đóng");
            }
        );
    }
}

Cấu trúc trong Scene:

Hierarchy:
└── AdsController (GameObject)
    └── MaxAdsController (Component) ← Kéo vào Inspector

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
   ↓
5. MaxAdsController (kế thừa MaxAdsHybridController) hiển thị ad

3.7 Các SerializeField config

Property	Type	Default	Mô tả
IsAutoLoadRewardVideo	bool	true	Tự động load sau khi SDK init
IsAutoLoadInterstitial	bool	true	Tự động load sau khi SDK init

3.8 Event và Callback

protected override void Awake()
{
    base.Awake();
    OnSdkInitializedEvent += OnMaxSDKInitialized;
}

private void OnMaxSDKInitialized(MaxSdkBase.SdkConfiguration config)
{
    Debug.Log("MAX SDK đã sẵn sàng!");
}

// Override callback nếu cần
protected override void OnRewardedAdLoadedEvent(string adUnitId, MaxSdkBase.AdInfo adInfo)
{
    base.OnRewardedAdLoadedEvent(adUnitId, adInfo);
    Debug.Log($"Reward ad loaded: {adUnitId}");
}

protected override void OnInterstitialClickedEvent(string adUnitId, MaxSdkBase.AdInfo adInfo)
{
    base.OnInterstitialClickedEvent(adUnitId, adInfo);
    // User đã click ad
}

3.9 Cơ chế Fail và Retry

Load Fail Flow:
1. Ad load thất bại
   ↓
2. Tăng retryAttempt (0, 1, 2, 4, 8, 16, 32, 64 giây)
   ↓
3. Đánh dấu AdUnit là disabled
   ↓
4. Tăng loadFailCount
   ↓
5. Nếu loadFailCount >= loadFailMax
   → Loại bỏ AdUnit khỏi danh sách (TRỪ default)
   ↓
6. Thử AdUnit tiếp theo trong danh sách

Config loadFailMax qua GSM Config:

{
    "maxConfig": {
        "adUnitConfig": {
            "HIGH_ECPM_AD_UNIT_ID": {
                "loadFailMax": 3
            }
        }
    }
}

• Mặc định: loadFailMax = 1

• AdUnit mặc định: KHÔNG BAO GIỜ bị loại bỏ

3.10 Override từ GSM Server

Hệ thống tự động gọi GSMApp.GetMaxAdUnitIds() để lấy danh sách AdUnitId từ server. Nếu server trả về danh sách, nó sẽ override danh sách từ GSMSettings.

3.11 So sánh với BaseMaxAdsController

Tiêu chí	BaseMaxAdsController	MaxAdsHybridController
Số AdUnit	1 Inter + 1 Reward	Nhiều AdUnit (list)
Rotation	Không	Có (theo eCPM)
Override từ server	Không	Có
loadFailMax config	Không	Có (qua GSM config)
Độ phức tạp	Thấp	Trung bình
Phù hợp	Game đơn giản	Game cần tối ưu revenue

---

Version

Plugin Version: 0.0.0.15

Last Updated: 2026-02-24