Overview - CloudX Documentation

The CloudX Unity SDK enables monetization of your Unity games with banner, MREC, interstitial, rewarded, and app open ads across iOS and Android.

Installation

The CloudX Unity SDK is distributed as a .unitypackage file.

Download CloudXSdk-4.4.0.unitypackage from the CloudX Unity SDK 4.4.0 release
In Unity, go to Assets > Import Package > Custom Package
Select the downloaded .unitypackage file
Import all assets when prompted

The External Dependency Manager will automatically resolve Android and iOS dependencies.

Ad Network Adapters

The CloudX SDK requires ad network adapters to serve ads. Enable them by uncommenting the relevant lines in Assets/CloudXSdk/Editor/CloudXDependencies.xml. See the Adapters section for per-adapter setup instructions, including iOS Info.plist requirements.

At least one adapter is required for the SDK to serve ads.

Initialization

Initialize the SDK before loading any ads. You can optionally configure user and app properties before initialization.

using CloudX;
using UnityEngine;

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

    void InitializeCloudX()
    {
        // Pre-initialization configuration (optional)
        CloudXSdk.SetHashedUserId("hashed-user-id");
        CloudXSdk.SetUserKeyValue("user_level", "premium");
        CloudXSdk.SetAppKeyValue("app_version", "1.0.0");

        // Subscribe to initialization callbacks before initializing
        CloudXInitializationCallbacks.OnSdkInitializedEvent += OnSdkInitialized;
        CloudXInitializationCallbacks.OnSdkInitializationFailedEvent += OnSdkInitializationFailed;

        // Initialize SDK
        var config = CloudXInitializationConfiguration.Create("YOUR_APP_KEY").Build();
        CloudXSdk.Initialize(config);
    }

    private void OnSdkInitialized(CloudXSdkConfiguration config)
    {
        Debug.Log("CloudX SDK initialized successfully");
        // Now you can load ads
    }

    private void OnSdkInitializationFailed(CloudXError error)
    {
        Debug.LogError($"SDK initialization failed: {error}");
    }
}

Subscribe to CloudXInitializationCallbacks events before calling Initialize() to receive initialization results.

Ad Formats

CloudX Unity SDK supports banner, MREC, interstitial, rewarded, and app open ad integrations. Use the format-specific guides for implementation details:

Banner & MREC ads

Display ads at a fixed screen position with optional refresh control.

Interstitial ads

Load and show full-screen interstitial placements.

Rewarded ads

Reward users after completed rewarded ad views.

App Open ads

Show full-screen ads when users open or return to your app.

Advanced Features

Privacy Controls

You can override consent state before initialization when your app is not using a CMP.

// Optional manual privacy overrides before Initialize()
CloudXSdk.SetHasUserConsent(true);
CloudXSdk.SetDoNotSell(false);

// Pass null to clear the manual override and defer back to CMP or IAB signals
CloudXSdk.SetHasUserConsent(null);
CloudXSdk.SetDoNotSell(null);

SetHasUserConsent(bool?) sets the GDPR consent override.
SetDoNotSell(bool?) sets the CCPA do-not-sell override.
IAB consent and privacy signals take precedence over these manual overrides when available.

iOS ATT Usage Description

Starting with Unity SDK 2.2.4, the iOS post-process step adds NSUserTrackingUsageDescription automatically if your app has not already defined it in Info.plist.

Default value: This uses device info for more personalized ads and content
If you already provide NSUserTrackingUsageDescription, CloudX leaves your existing value unchanged.
Set your own copy in Info.plist if you want custom ATT prompt wording.

User Targeting

Configure user and app properties for better ad targeting. Call these methods before Initialize.

// Set hashed user ID
CloudXSdk.SetHashedUserId("hashed-user-id-12345");

// Set user-level key-value pairs
CloudXSdk.SetUserKeyValue("user_level", "premium");
CloudXSdk.SetUserKeyValue("age_group", "25-34");

// Set app-level key-value pairs
CloudXSdk.SetAppKeyValue("app_version", "1.0.0");
CloudXSdk.SetAppKeyValue("build_number", "123");

// Clear all custom key-values
CloudXSdk.ClearAllKeyValues();

Revenue Tracking

All ad formats provide revenue callbacks through the OnAdRevenuePaid event. The CloudXAd object contains revenue information:

CloudXAdsCallbacks.Banner.OnAdRevenuePaid += (ad) =>
{
    Debug.Log($"Revenue: ${ad.Revenue:F4}");
    Debug.Log($"Network: {ad.NetworkName}");
    Debug.Log($"Ad Unit: {ad.AdUnitId}");
    Debug.Log($"Ad Format: {ad.AdFormat}");
    Debug.Log($"Placement: {ad.Placement}");
    Debug.Log($"Network Placement: {ad.NetworkPlacement}");

    // Track revenue in your analytics
    TrackRevenue(ad.Revenue, ad.NetworkName);
};

Publisher-Reported Revenue Data

If your app receives impression-level revenue callbacks or bid metadata from AdMob, InMobi, TopOn, or another mediation platform outside the CloudX ad flow, forward those events to CloudX after initialization:

Field	Required	Description
`Platform`	Yes	`CloudXRevenuePlatform.AdMob`, `CloudXRevenuePlatform.InMobi`, `CloudXRevenuePlatform.TopOn`, or `CloudXRevenuePlatform.Custom("MyProvider")`
`Revenue`	Yes	Revenue for one impression in the supplied currency, not CPM/eCPM
`AdFormat`	Yes	Ad format string such as `banner`, `mrec`, `interstitial`, or `rewarded`
`CurrencyCode`	No	ISO 4217 currency code, if known
`Precision`	No	`CloudXRevenuePrecision.Exact`, `Estimated`, `PublisherDefined`, or `Undefined`
`NetworkName`	No	Winning ad network name, if known
`AdUnitId`	No	Mediation-platform ad unit ID
`ThirdPartyAdPlacementId`	No	Network-side ad unit or placement ID
`CreativeId`	No	Creative ID from the ad network
`NetworkPlacement`	No	Network placement identifier
`CountryCode`	No	User country code, if known
`UserSegment`	No	User segment, if known

CloudXSdk.ReportRevenueData() returns true when the event is accepted into the CloudX revenue pipeline. It returns false when the payload is invalid, the SDK is not initialized, or revenue tracking is unavailable.

AdMob paid events

With the Google Mobile Ads Unity plugin, each ad object exposes OnAdPaid. The callback AdValue.Value is reported in micro-units, so divide it by 1_000_000.0 before passing it to CloudX.

private static CloudXRevenuePrecision ToCloudXRevenuePrecision(AdValue.PrecisionType precision) => precision switch
{
    AdValue.PrecisionType.Precise => CloudXRevenuePrecision.Exact,
    AdValue.PrecisionType.Estimated => CloudXRevenuePrecision.Estimated,
    AdValue.PrecisionType.PublisherProvided => CloudXRevenuePrecision.PublisherDefined,
    _ => CloudXRevenuePrecision.Undefined,
};

private static bool ReportAdMobPaidEvent(AdValue adValue, string adFormat, string adUnitId)
{
    return CloudXSdk.ReportRevenueData(new CloudXRevenueData(
        Platform: CloudXRevenuePlatform.AdMob,
        Revenue: adValue.Value / 1_000_000.0,
        AdFormat: adFormat,
        CurrencyCode: adValue.CurrencyCode,
        Precision: ToCloudXRevenuePrecision(adValue.Precision),
        AdUnitId: adUnitId,
    ));
}

bannerView.OnAdPaid += adValue =>
{
    ReportAdMobPaidEvent(adValue, "banner", ADMOB_BANNER_UNIT_ID);
};

InMobi impression events

For InMobi, save args.AdMetaInfo in OnAdFetchSuccessful. When OnAdImpression fires, send the saved metaInfo.Bid to CloudX, then clear the saved value.

private AdMetaInfo bannerMetaInfo;

private static bool ReportInMobiImpression(AdMetaInfo metaInfo, string adFormat, string placementId)
{
    return CloudXSdk.ReportRevenueData(new CloudXRevenueData(
        Platform: CloudXRevenuePlatform.InMobi,
        Revenue: metaInfo.Bid,
        AdFormat: adFormat,
        Precision: CloudXRevenuePrecision.Estimated,
        ThirdPartyAdPlacementId: placementId,
        CreativeId: metaInfo.CreativeID,
    ));
}

bannerAd.OnAdFetchSuccessful += (_, args) =>
{
    bannerMetaInfo = args.AdMetaInfo;
};

bannerAd.OnAdImpression += (_, _) =>
{
    ReportInMobiImpression(bannerMetaInfo, "banner", INMOBI_BANNER_PLACEMENT_ID);
    bannerMetaInfo = null;
};

TopOn revenue events

With the TopOn Unity plugin v2.1.8 or later, set an IATAdRevenueListener on the ad object. Use adInfo.publisher_revenue for the single-impression revenue; do not use adInfo.adsource_price, because TopOn reports that value as CPM/eCPM.

using AnyThinkAds.Api;
using CloudX;

private static CloudXRevenuePrecision ToTopOnRevenuePrecision(string precision)
{
    return precision switch
    {
        "exact" => CloudXRevenuePrecision.Exact,
        "estimated" => CloudXRevenuePrecision.Estimated,
        "publisher_defined" => CloudXRevenuePrecision.PublisherDefined,
        _ => CloudXRevenuePrecision.Undefined,
    };
}

private sealed class TopOnRevenueListener : IATAdRevenueListener
{
    public void onAdRevenuePaid(string placementId, ATCallbackInfo adInfo)
    {
        ReportTopOnRevenue(adInfo, "banner", placementId);
    }
}

private static bool ReportTopOnRevenue(ATCallbackInfo adInfo, string adFormat, string placementId)
{
    return CloudXSdk.ReportRevenueData(new CloudXRevenueData(
        Platform: CloudXRevenuePlatform.TopOn,
        Revenue: adInfo.publisher_revenue,
        AdFormat: adFormat,
        CurrencyCode: adInfo.currency,
        Precision: ToTopOnRevenuePrecision(adInfo.precision),
        NetworkName: adInfo.network_name,
        AdUnitId: placementId,
        ThirdPartyAdPlacementId: adInfo.network_placement_id,
        NetworkPlacement: adInfo.adsource_id,
        CountryCode: adInfo.country,
    ));
}

ATBannerAd.Instance.setAdRevenueListener(TOPON_BANNER_PLACEMENT_ID, new TopOnRevenueListener());

Custom platform events

Use Custom for providers that do not have a CloudX SDK constant like AdMob, InMobi, and TopOn do. The value is only the provider name, such as CloudXRevenuePlatform.Custom("TradPlus") or CloudXRevenuePlatform.Custom("Nimbus"). Keep the name stable so CloudX can group that provider’s revenue consistently. Do not include the amount or currency in the provider name. For a TradPlus impression worth USD 0.01, send Platform: CloudXRevenuePlatform.Custom("TradPlus"), Revenue: 0.01, and CurrencyCode: "USD". If your source reports CPM/eCPM, divide by 1_000.0 first.

private static bool ReportCustomRevenueEvent(
    string providerName,
    double revenue,
    string adFormat,
    string currencyCode,
    string adUnitId,
    string placementId)
{
    return CloudXSdk.ReportRevenueData(new CloudXRevenueData(
        Platform: CloudXRevenuePlatform.Custom(providerName),
        Revenue: revenue,
        AdFormat: adFormat,
        CurrencyCode: currencyCode,
        Precision: CloudXRevenuePrecision.PublisherDefined,
        AdUnitId: adUnitId,
        ThirdPartyAdPlacementId: placementId,
    ));
}

​Installation

​Ad Network Adapters

​Initialization

​Ad Formats

Banner & MREC ads

Interstitial ads

Rewarded ads

App Open ads

​Advanced Features

​Privacy Controls

​iOS ATT Usage Description

​User Targeting

​Revenue Tracking

​Publisher-Reported Revenue Data

​AdMob paid events

​InMobi impression events

​TopOn revenue events

​Custom platform events

Installation

Ad Network Adapters

Initialization

Ad Formats

Advanced Features

Privacy Controls

iOS ATT Usage Description

User Targeting

Revenue Tracking

Publisher-Reported Revenue Data

AdMob paid events

InMobi impression events

TopOn revenue events

Custom platform events