> ## Documentation Index > Fetch the complete documentation index at: https://docs.cloudx.io/llms.txt > Use this file to discover all available pages before exploring further. # Overview > Overview of CloudX Unity SDK setup and core features 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. 1. Download `CloudXSdk-4.4.0.unitypackage` from the [CloudX Unity SDK 4.4.0 release](https://github.com/cloudx-io/cloudx-unity/releases/tag/v4.4.0) 2. In Unity, go to **Assets > Import Package > Custom Package** 3. Select the downloaded `.unitypackage` file 4. 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](/en/unity/adapters/meta) 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. ```csharp theme={null} 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: Display ads at a fixed screen position with optional refresh control. Load and show full-screen interstitial placements. Reward users after completed rewarded ad views. 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. ```csharp theme={null} // 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`. ```csharp theme={null} // 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: ```csharp theme={null} 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. ```csharp theme={null} 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. ```csharp theme={null} 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. ```csharp theme={null} 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. ```csharp theme={null} 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, )); } ```