CloudX Unity SDK

CloudX Unity SDK 使您能够在 iOS 和 Android 上通过横幅、MREC、插屏和激励广告实现 Unity 游戏变现。

安装

CloudX Unity SDK 以 .unitypackage 文件形式分发。

从 GitHub Releases 下载最新的 CloudX-Unity-SDK.unitypackage
在 Unity 中，转到 Assets > Import Package > Custom Package
选择下载的 .unitypackage 文件
提示时导入所有资源

External Dependency Manager 将自动解析 Android 和 iOS 依赖。

广告网络适配器

CloudX SDK 需要广告网络适配器来投放广告。适配器是可选的，可以根据您要支持的广告网络启用。

启用适配器

打开 Assets/CloudXSdk/Editor/CloudXDependencies.xml 并取消注释您需要的适配器：

<?xml version="1.0" encoding="utf-8"?>
<dependencies>
    <androidPackages>
        <!-- CloudX 核心 SDK -->
        <androidPackage spec="io.cloudx:sdk:0.12.0"/>

        <!-- 可选：CloudX 适配器（根据需要取消注释） -->
        <androidPackage spec="io.cloudx:adapter-cloudx:0.12.0"/>
        <androidPackage spec="io.cloudx:adapter-meta:0.12.0"/>
        <androidPackage spec="io.cloudx:adapter-vungle:0.12.0"/>
    </androidPackages>
</dependencies>

修改文件后，转到 Assets > External Dependency Manager > Android Resolver > Force Resolve 下载新依赖。

可用适配器

适配器	包	描述
CloudX Network	`io.cloudx:adapter-cloudx`	CloudX 广告网络
Meta Audience Network	`io.cloudx:adapter-meta`	Facebook/Meta 广告
Vungle	`io.cloudx:adapter-vungle`	Vungle 视频广告

SDK 至少需要一个适配器才能投放广告。

初始化

在加载任何广告之前初始化 SDK。您可以在初始化之前选择性地配置用户和应用属性。

using CloudX;
using UnityEngine;

public class MyGameManager : MonoBehaviour
{
    void Start()
    {
        InitializeCloudX();
    }

    async void InitializeCloudX()
    {
        // 初始化前配置（可选）
        CloudXSdk.SetHashedUserId("hashed-user-id");
        CloudXSdk.SetUserKeyValue("user_level", "premium");
        CloudXSdk.SetAppKeyValue("app_version", "1.0.0");

        // 初始化 SDK
        var error = await CloudXSdk.InitializeAsync("YOUR_APP_KEY", testMode: true);
        if (error != null)
        {
            Debug.LogError($"SDK 初始化失败: {error}");
            return;
        }

        Debug.Log("CloudX SDK 初始化成功");
        // 现在可以加载广告
    }
}

InitializeAsync 成功时返回 null，失败时返回 CloudXError 对象。

广告集成

横幅广告

具有自动刷新功能的标准横幅广告。

using CloudX;
using UnityEngine;

public class BannerExample : MonoBehaviour
{
    private const string BannerPlacement = "banner_main";

    void Start()
    {
        // 订阅回调
        CloudXAdsCallbacks.Banner.OnAdLoadSuccess += OnBannerLoaded;
        CloudXAdsCallbacks.Banner.OnAdLoadFailed += OnBannerLoadFailed;
        CloudXAdsCallbacks.Banner.OnAdClicked += OnBannerClicked;
        CloudXAdsCallbacks.Banner.OnAdRevenuePaid += OnBannerRevenuePaid;

        // 创建并显示横幅
        var config = new CloudXAdViewConfiguration(CloudXAdViewConfiguration.AdViewPosition.BottomCenter);
        CloudXSdk.CreateBanner(BannerPlacement, config);
        CloudXSdk.ShowBanner(BannerPlacement);
    }

    void OnApplicationFocus(bool hasFocus)
    {
        if (hasFocus)
        {
            CloudXSdk.ShowBanner(BannerPlacement);
        }
        else
        {
            CloudXSdk.HideBanner(BannerPlacement);
        }
    }

    private void OnBannerLoaded(CloudXAd ad)
    {
        Debug.Log($"横幅已加载: {ad.PlacementName}");
    }

    private void OnBannerLoadFailed(CloudXError error)
    {
        Debug.LogError($"横幅加载失败: {error}");
    }

    private void OnBannerClicked(CloudXAd ad)
    {
        Debug.Log($"横幅被点击: {ad.PlacementName}");
    }

    private void OnBannerRevenuePaid(CloudXAd ad)
    {
        Debug.Log($"横幅收入: ${ad.Revenue}，来自 {ad.BidderName}");
    }
}

自动刷新控制： 横幅广告默认自动刷新。手动控制刷新：

CloudXSdk.StopBannerAutoRefresh(BannerPlacement);  // 停止自动刷新
CloudXSdk.LoadBanner(BannerPlacement);              // 手动加载
CloudXSdk.StartBannerAutoRefresh(BannerPlacement); // 重新启用自动刷新

MREC 广告 (300x250)

中等矩形广告与横幅的工作方式相同，但尺寸更大。

using CloudX;
using UnityEngine;

public class MrecExample : MonoBehaviour
{
    private const string MrecPlacement = "mrec_main";

    void Start()
    {
        // 订阅回调
        CloudXAdsCallbacks.Mrec.OnAdLoadSuccess += OnMrecLoaded;
        CloudXAdsCallbacks.Mrec.OnAdLoadFailed += OnMrecLoadFailed;
        CloudXAdsCallbacks.Mrec.OnAdClicked += OnMrecClicked;
        CloudXAdsCallbacks.Mrec.OnAdRevenuePaid += OnMrecRevenuePaid;

        // 创建并显示 MREC
        var config = new CloudXAdViewConfiguration(CloudXAdViewConfiguration.AdViewPosition.Centered);
        CloudXSdk.CreateMrec(MrecPlacement, config);
        CloudXSdk.ShowMrec(MrecPlacement);
    }

    void OnApplicationFocus(bool hasFocus)
    {
        if (hasFocus)
        {
            CloudXSdk.ShowMrec(MrecPlacement);
        }
        else
        {
            CloudXSdk.HideMrec(MrecPlacement);
        }
    }

    private void OnMrecLoaded(CloudXAd ad)
    {
        Debug.Log($"MREC 已加载: {ad.PlacementName}");
    }

    private void OnMrecLoadFailed(CloudXError error)
    {
        Debug.LogError($"MREC 加载失败: {error}");
    }

    private void OnMrecClicked(CloudXAd ad)
    {
        Debug.Log($"MREC 被点击: {ad.PlacementName}");
    }

    private void OnMrecRevenuePaid(CloudXAd ad)
    {
        Debug.Log($"MREC 收入: ${ad.Revenue}，来自 {ad.BidderName}");
    }
}

插屏广告

在内容过渡之间显示的全屏广告。

using CloudX;
using UnityEngine;

public class InterstitialExample : MonoBehaviour
{
    private const string InterstitialPlacement = "interstitial_main";

    void Start()
    {
        // 订阅回调
        CloudXAdsCallbacks.Interstitial.OnAdLoadSuccess += OnInterstitialLoaded;
        CloudXAdsCallbacks.Interstitial.OnAdLoadFailed += OnInterstitialLoadFailed;
        CloudXAdsCallbacks.Interstitial.OnAdShowSuccess += OnInterstitialShown;
        CloudXAdsCallbacks.Interstitial.OnAdShowFailed += OnInterstitialShowFailed;
        CloudXAdsCallbacks.Interstitial.OnAdHidden += OnInterstitialHidden;
        CloudXAdsCallbacks.Interstitial.OnAdClicked += OnInterstitialClicked;
        CloudXAdsCallbacks.Interstitial.OnAdRevenuePaid += OnInterstitialRevenuePaid;

        // 加载插屏
        CloudXSdk.LoadInterstitial(InterstitialPlacement);
    }

    public void ShowInterstitial()
    {
        if (CloudXSdk.IsInterstitialReady(InterstitialPlacement))
        {
            CloudXSdk.ShowInterstitial(InterstitialPlacement);
        }
        else
        {
            Debug.LogWarning("插屏尚未准备好");
        }
    }

    private void OnInterstitialLoaded(CloudXAd ad)
    {
        Debug.Log($"插屏已加载: {ad.PlacementName}");
    }

    private void OnInterstitialLoadFailed(CloudXError error)
    {
        Debug.LogError($"插屏加载失败: {error}");
    }

    private void OnInterstitialShown(CloudXAd ad)
    {
        Debug.Log($"插屏已展示: {ad.PlacementName}");
    }

    private void OnInterstitialShowFailed(CloudXError error)
    {
        Debug.LogError($"插屏展示失败: {error}");
    }

    private void OnInterstitialHidden(CloudXAd ad)
    {
        Debug.Log($"插屏已隐藏: {ad.PlacementName}");
        // 为下次重新加载
        CloudXSdk.LoadInterstitial(InterstitialPlacement);
    }

    private void OnInterstitialClicked(CloudXAd ad)
    {
        Debug.Log($"插屏被点击: {ad.PlacementName}");
    }

    private void OnInterstitialRevenuePaid(CloudXAd ad)
    {
        Debug.Log($"插屏收入: ${ad.Revenue}，来自 {ad.BidderName}");
    }
}

激励广告

奖励用户观看视频广告。

using CloudX;
using UnityEngine;

public class RewardedExample : MonoBehaviour
{
    private const string RewardedPlacement = "rewarded_main";

    void Start()
    {
        // 订阅回调
        CloudXAdsCallbacks.Rewarded.OnAdLoadSuccess += OnRewardedLoaded;
        CloudXAdsCallbacks.Rewarded.OnAdLoadFailed += OnRewardedLoadFailed;
        CloudXAdsCallbacks.Rewarded.OnAdShowSuccess += OnRewardedShown;
        CloudXAdsCallbacks.Rewarded.OnAdShowFailed += OnRewardedShowFailed;
        CloudXAdsCallbacks.Rewarded.OnAdHidden += OnRewardedHidden;
        CloudXAdsCallbacks.Rewarded.OnAdClicked += OnRewardedClicked;
        CloudXAdsCallbacks.Rewarded.OnAdRewarded += OnUserRewarded;
        CloudXAdsCallbacks.Rewarded.OnAdRevenuePaid += OnRewardedRevenuePaid;

        // 加载激励广告
        CloudXSdk.LoadRewarded(RewardedPlacement);
    }

    public void ShowRewardedAd()
    {
        if (CloudXSdk.IsRewardedReady(RewardedPlacement))
        {
            CloudXSdk.ShowRewarded(RewardedPlacement);
        }
        else
        {
            Debug.LogWarning("激励广告尚未准备好");
        }
    }

    private void OnRewardedLoaded(CloudXAd ad)
    {
        Debug.Log($"激励广告已加载: {ad.PlacementName}");
    }

    private void OnRewardedLoadFailed(CloudXError error)
    {
        Debug.LogError($"激励广告加载失败: {error}");
    }

    private void OnRewardedShown(CloudXAd ad)
    {
        Debug.Log($"激励广告已展示: {ad.PlacementName}");
    }

    private void OnRewardedShowFailed(CloudXError error)
    {
        Debug.LogError($"激励广告展示失败: {error}");
    }

    private void OnRewardedHidden(CloudXAd ad)
    {
        Debug.Log($"激励广告已隐藏: {ad.PlacementName}");
        // 为下次重新加载
        CloudXSdk.LoadRewarded(RewardedPlacement);
    }

    private void OnRewardedClicked(CloudXAd ad)
    {
        Debug.Log($"激励广告被点击: {ad.PlacementName}");
    }

    private void OnUserRewarded(CloudXAd ad)
    {
        Debug.Log($"用户从 {ad.PlacementName} 获得奖励");
        // 在此处给用户奖励
        GrantRewardToUser();
    }

    private void OnRewardedRevenuePaid(CloudXAd ad)
    {
        Debug.Log($"激励广告收入: ${ad.Revenue}，来自 {ad.BidderName}");
    }

    private void GrantRewardToUser()
    {
        // 您的奖励逻辑在此
        Debug.Log("正在给用户奖励！");
    }
}

高级功能

用户定向

配置用户和应用属性以获得更好的广告定向。在 InitializeAsync 之前调用这些方法。

// 设置哈希用户 ID
CloudXSdk.SetHashedUserId("hashed-user-id-12345");

// 设置用户级键值对
CloudXSdk.SetUserKeyValue("user_level", "premium");
CloudXSdk.SetUserKeyValue("age_group", "25-34");

// 设置应用级键值对
CloudXSdk.SetAppKeyValue("app_version", "1.0.0");
CloudXSdk.SetAppKeyValue("build_number", "123");

// 清除所有自定义键值对
CloudXSdk.ClearAllKeyValues();

收入追踪

所有广告格式都通过 OnAdRevenuePaid 事件提供收入回调。CloudXAd 对象包含收入信息：

CloudXAdsCallbacks.Banner.OnAdRevenuePaid += (ad) =>
{
    Debug.Log($"收入: ${ad.Revenue:F4}");
    Debug.Log($"竞价方: {ad.BidderName}");
    Debug.Log($"广告位: {ad.PlacementName}");

    // 在您的分析中追踪收入
    TrackRevenue(ad.Revenue, ad.BidderName);
};

Unity SDK

​CloudX Unity SDK

​安装

​广告网络适配器

​启用适配器

​可用适配器

​初始化

​广告集成

​横幅广告

​MREC 广告 (300x250)

​插屏广告

​激励广告

​高级功能

​用户定向

​收入追踪

CloudX Unity SDK

安装

广告网络适配器

启用适配器

可用适配器

初始化

广告集成

横幅广告

MREC 广告 (300x250)

插屏广告

激励广告

高级功能

用户定向

收入追踪