Admob Plugin

Là 1 Plugin có các Base Class cho các loại Ad như AppOpen, và một số tracking tự động

Download GSM_Admob_Plugin v0.0.0.4.unitypackage

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

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

Tài liệu sử dụng Admob Plugin

1. Tổng quan

Admob Plugin (CSCMobi) hỗ trợ tích hợp Google Mobile Ads (AdMob) vào game, tập trung vào:

• Tự động lấy cấu hình App ID từ GoogleMobileAdsSettings hoặc AppLovin Settings.

• Quản lý App Open Ads (AOA) - quảng cáo mở app.

• Tracking impression và revenue (doanh thu) từ AdMob Mediation gửi về GSM, Firebase và Adjust.

2. Cấu trúc thư mục

AdmobPlugin/
├── Editor/              
│   └── AdmobPluginPreBuildProcessor.cs  # Script editor (tự tạo googleMobileAds.json khi build)
├── Resources/           
│   └── googleMobileAds.json             # File config Runtime (tự sinh, không nên sửa tay)
├── Scripts/
│   ├── GSMAdmobInfo.cs                  # Khởi tạo thông tin AdMob
│   ├── BaseAdmobAppOpenController.cs    # Base class quản lý AOA
│   └── GSMAdmobAppOpenCounterLog.cs     # Counter log cho AOA (First load/show)

3. Cấu hình & Khởi tạo (GSMAdmobInfo)

GSMAdmobInfo là component tĩnh, tự động chạy sau khi Scene load (RuntimeInitializeOnLoadMethod).

Chức năng chính:

1. Lấy App ID:

   • Trong Editor: Lấy từ GoogleMobileAdsSettings hoặc AppLovinSettings.

   • Khi chạy thật (Runtime): Lấy từ file Resources/googleMobileAds.json.

2. Validation: So sánh App ID trong config AdMob và config AppLovin (MAX). Nếu khác nhau sẽ báo lỗi log.

3. Khởi tạo: Gọi GSMCore.Instance.SetAdmobInfo để truyền App ID và Unit ID vào hệ thống core.

Lưu ý quan trọng:

• Khi build, AdmobPluginPreBuildProcessor sẽ tự động đọc setting từ Editor và tạo ra file Resources/googleMobileAds.json. File này chứa App ID và phiên bản SDK.

• Không xóa hoặc sửa thủ công file googleMobileAds.json vì nó sẽ bị ghi đè mỗi khi build.

4. App Open Ads (BaseAdmobAppOpenController)

Để sử dụng quảng cáo mở app (AOA), bạn cần tạo một script kế thừa từ BaseAdmobAppOpenController.

Các hàm abstract cần cài đặt:

• GetAdmobAdUnitId(): Trả về ID của Ad Unit (string).

• GetCanShow(): Logic kiểm tra game có đang cho phép hiện AOA không (ví dụ: không hiện khi đang tutorial).

• GetTargetLevel(), GetGroup(), GetSubGroup(), GetUserType(): Các hàm trả về info để tracking user.

Tính năng có sẵn:

• PreLoad: Tự động tải trước quảng cáo nếu CanPreLoad() trả về true. Trạng thái này được lưu trong PlayerPrefs (CanPreLoadAOA).

• ShowAd: Hiển thị quảng cáo. Nếu quảng cáo chưa sẵn sàng, nó sẽ cố tải lại.

• Counter Log: Tự động log các mốc quan trọng vào GSMAnalytics để theo dõi tỷ lệ hiển thị thành công của lần đầu tiên (Funnel tracking):

  • 01.First_Load

  • 02.First_Load_Success

  • 03.First_Show

  • 04.First_Show_Success

5. Impression Tracking (AdmobMediationTracking)

Class AdmobMediationTracking (nằm trong thư mục LogImpression) chịu trách nhiệm tracking doanh thu quảng cáo.

Hỗ trợ các định dạng:

• App Open Ad

• Banner / Collapsible Banner

• Interstitial

• Rewarded / Rewarded Interstitial

Luồng dữ liệu:

Khi một quảng cáo được hiển thị và trả về AdValue, hệ thống sẽ:

1. Tính Revenue = value / 1,000,000.

2. Gửi dữ liệu doanh thu tới 3 nơi:

   • Firebase Analytics: LogFirebaseImpression

   • Adjust: LogAdjustImpression (thông qua AdjustAdRevenue)

   • GSM Analytics: LogGSMImpression

6. Checklist triển khai

Trước khi build, hãy kiểm tra:

1. GoogleMobileAdsSettings: Đã điền đúng App ID cho Android và iOS chưa? (Assets > Google Mobile Ads > Settings)

2. AppLovin Settings: Nếu dùng MAX Mediation, check xem App ID khai báo trong MAX có khớp với AdMob không. Plugin sẽ báo lỗi nếu lệch.

3. App Open Ad Script: Đã có script kế thừa BaseAdmobAppOpenController gắn vào game launch chưa?

7. Sample Code

• Ở GSM Settings

Code mẫu:

using GoogleMobileAds.Api;
using GSM;
using GSM.Core;
using System;
using System.Collections.Generic;
using UnityEngine;

public class AdmobAppOpenController : BaseAdmobAppOpenController
{
    private static AdmobAppOpenController _instance;
    public static AdmobAppOpenController Instance => _instance;
    [SerializeField] private GameObject overlayBackground;
    // Id Test
    private string _adUnitId = "";

    private void Awake()
    {
        if (_instance == null)
        {
            _instance = this;
            DontDestroyOnLoad(this.gameObject);
        }
        else
        {
            Destroy(gameObject);
        }
        GetAdSettingGSM();
    }
    private void GetAdSettingGSM()
    {
        GSMSettings settings = GSMInitialization.GsmSettings;
        if (settings != null)
        {
            var appOpenAdUnit = settings.GetAdmobAdUnit("AppOpen");
            if (appOpenAdUnit != null)
            {
                _adUnitId = appOpenAdUnit.adUnitId;
            }

        }
        else
        {
            Debug.LogError("GSMSettings not found");
        }
    }
    public override string GetAdmobAdUnitId()
    {
        return _adUnitId;
    }
    protected override bool ExecuteShowAd()
    {
        if (MaxAdsController.Instance == null) return false;
        overlayBackground?.SetActive(true);
        //Kiểm tra nếu vừa mới click AdReward, Inter của Max 
        //và FireBase RemoteConfig không cho hiện AppOpen 
        //khi Click Ad ra ngoài thì không hiện AppOpen
        if (MaxAdsController.Instance.IsRewardOrInterClicked && !FirebaseServiceController.Instance.GetConfigActiveAOAWhenClickAds())
        {
            MaxAdsController.Instance.ReleaseMarkAdClick();
            return false;
        }
        MaxAdsController.Instance.ReleaseMarkAdClick();
        Debug.Log("AppOpen: Showing app open ad.");

        return base.ExecuteShowAd();

    }
    public override bool GetCanShow()
    {
        //Xử lý Logic cho phép hiển thị quảng cáo AppOpen
        OpenAdsData appOpenAdsData = new OpenAdsData();
        if (FirebaseServiceController.Instance != null)
            appOpenAdsData = JsonUtility.FromJson<OpenAdsData>(FirebaseServiceController.Instance.GetOpenAdsData());

        if (appOpenAdsData.activeMode == 0) return false;// tắt trên remove
        if (!PlayerPrefs.HasKey("MaxPassedLevel")) return false; // chưa đủ level

        string maxPass = PlayerPrefs.GetString("MaxPassedLevel");
        int chapterPass = int.Parse(maxPass.Split('_')[0]);
        int levelPass = int.Parse(maxPass.Split("_")[1]);

        if (chapterPass < appOpenAdsData.Chapter) return false;
        if (chapterPass == appOpenAdsData.Chapter && levelPass < appOpenAdsData.Level) return false;

        var playerClass = PlayerPrefs.GetInt("typeUser", 0) + 1;
        for (int i = 0; i < appOpenAdsData.typeUser.Count; i++)
        {
            if (playerClass == appOpenAdsData.typeUser[i])
                return true;
        }
        return false;
    }

    protected override string GetGroup()
    {
        return string.Empty;
    }

    protected override string GetSubGroup()
    {
        return string.Empty;
    }

    protected override string GetTargetLevel()
    {
        return PlayerPrefs.GetString("level_played", "0_0_0");
    }

    protected override string GetUserType()
    {
        return string.Empty;
    }
    protected override void OnAdFullScreenContentFailed(AdError error)
    {
        Debug.Log("AppOpen: OnAdFullScreenContentFailed");
        overlayBackground?.SetActive(false);
        base.OnAdFullScreenContentFailed(error);
        Time.timeScale = 1;


    }
    protected override void OnAdFullScreenContentClosed()
    {
        Debug.Log("AppOpen: OnAdFullScreenContentClosed");
        overlayBackground?.SetActive(false);
        base.OnAdFullScreenContentClosed();
        Time.timeScale = 1;

    }
}
[Serializable]
public class OpenAdsData
{
    public int activeMode;
    public List<int> typeUser;
    public int Chapter;
    public int Level;
    public int Stage;

    public OpenAdsData()
    {
        activeMode = 1;
        typeUser = new List<int>() { };
        Chapter = 1;
        Level = 7;
        Stage = 1;
    }
}

Khi ở màn hình Loading khoảng 3-4s sau khi vào game, thì gọi ShowFirst

if (Application.internetReachability != NetworkReachability.NotReachable && sceneName == "Login")
{
    AdmobAppOpenController.Instance.ShowFirst();
    yield return new WaitForSecondsRealtime(0.2f);
    while (!AdmobAppOpenController.Instance.IsClosed)
    {
        yield return null;
    }
}