Integration

Complete iOS SDK integration guide

Requires iOS 13.0+, Xcode 16.0+, and Swift 6.0+.

Installation

CocoaPods

Podfile

platform :ios, '13.0'

target 'YourApp' do
  use_frameworks!

  # Core SDK
  pod 'CloudXCore', '~> 3.4.0'

  # Adapters for ad networks (add as needed)
  pod 'CloudXMetaAdapter', '~> 3.4.0'       # Meta Audience Network >= 6.15.1, < 7.0
  pod 'CloudXVungleAdapter', '~> 3.4.0'     # VungleAds >= 7.4.0, < 8.0
  pod 'CloudXInMobiAdapter', '~> 3.4.0'     # InMobiSDK >= 11.0.0, < 12.0
  pod 'CloudXMintegralAdapter', '~> 3.4.0'  # MintegralAdSDK ~> 8.0
  pod 'CloudXUnityAdsAdapter', '~> 3.4.0'   # UnityAds >= 4.17.0, < 5.0
  pod 'CloudXMagniteAdapter', '~> 3.4.0'    # MagniteSDK ~> 1.0.0
  pod 'CloudXMolocoAdapter', '~> 3.4.0'     # MolocoSDKiOS ~> 4.6.0
  pod 'CloudXVerveAdapter', '~> 3.4.0'      # HyBid = 3.8.0
end

pod install --repo-update

Initialization

Objective-C

#import <CloudXCore/CloudXCore.h>

CLXInitializationConfiguration *config =
    [CLXInitializationConfiguration configurationWithAppKey:@"your-app-key-here"];

[[CloudXCore shared] initializeWithConfiguration:config completion:^(CLXSdkConfiguration *sdkConfig, CLXError * _Nullable error) {
    if (sdkConfig) {
        NSLog(@"CloudX SDK initialized successfully");
    } else {
        NSLog(@"Failed to initialize CloudX SDK: %@", error.localizedDescription);
    }
}];

Ad Formats

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

Banner & MREC ads

Create fixed-size display placements with optional refresh control.

Interstitial ads

Load and show full-screen interstitial placements.

Native ads

Render native creatives and Reels-style native video experiences.

Rewarded ads

Reward users after completed rewarded ad views.

Ad Information (CLXAd)

The CLXAd object is passed to delegate callbacks and contains information about the loaded/displayed ad:

Property	Type	Description
adFormat	CLXAdFormat	Ad format (banner, MREC, interstitial, rewarded, native)
adUnitId	NSString?	The ad unit ID
adUnitName	NSString?	The ad unit name
networkName	NSString?	Name of the winning ad network
networkPlacement	NSString?	Network-specific placement ID
placement	NSString?	Custom placement set via placement property
revenue	NSNumber?	Impression-level revenue in USD
revenuePrecision	NSString?	Revenue precision, when provided by the winning network
creativeIdentifier	NSString?	Creative identifier for creative-level issue reporting
requestLatency	NSTimeInterval	Time in seconds from ad request to ad response
nativeAd	CLXNativeAd?	Native ad asset container for native ads; nil for non-native formats
adValues	NSDictionary<NSString *, NSString *>	SDK-defined metadata for the loaded ad; values may be absent by format or network

Objective-C

- (void)didLoadAd:(CLXAd *)ad {
    NSLog(@"Ad format: %ld", (long)ad.adFormat);
    NSLog(@"Network: %@", ad.networkName);
    NSLog(@"Revenue: %@", ad.revenue);
}

Error Handling

All SDK errors are returned as CLXError objects in delegate callbacks:

Property	Type	Description
code	CLXErrorCode	Error category
localizedDescription	NSString	Human-readable description
underlyingError	NSError?	Optional underlying error

Error Code Categories

Range	Category	Common Codes
0	General	CLXErrorCodeInternalError
100-199	Network	CLXErrorCodeNetworkError, CLXErrorCodeNetworkTimeout, CLXErrorCodeServerError, CLXErrorCodeNoConnection
200-299	Initialization	CLXErrorCodeNotInitialized, CLXErrorCodeSDKDisabled, CLXErrorCodeNoAdaptersFound, CLXErrorCodeInvalidAppKey
300-399	Ad Loading	CLXErrorCodeNoFill, CLXErrorCodeInvalidAdUnit, CLXErrorCodeAdsDisabled
400-499	Display	CLXErrorCodeAdNotReady, CLXErrorCodeAdAlreadyShowing
600-699	Adapter	CLXErrorCodeAdapterNoFill, CLXErrorCodeAdapterTimeout, CLXErrorCodeAdapterLoadTimeout, CLXErrorCodeAdapterInitializationError

Advanced Features

Debug Logging

Objective-C

[CloudXCore setMinLogLevel:CLXLogLevelDebug];  // Enable debug logging
[CloudXCore setMinLogLevel:CLXLogLevelNone];   // Disable all logging

Log Levels: verbose < debug < info < warn < error < none

Impression-Level Revenue Tracking

Set a revenueDelegate on any ad format to receive impression-level revenue (ILR) callbacks. The CLXAd object contains the revenue value in USD and the winning network name.

Objective-C

self.bannerAd.revenueDelegate = self;

- (void)didPayRevenueForAd:(CLXAd *)ad {
    NSLog(@"Revenue: %@ from %@", ad.revenue, ad.networkName);
}

Works with all ad formats (banner, MREC, interstitial, rewarded, native).

Delegate Threading

Publisher delegate callbacks are delivered on the main queue and may fire inline relative to the SDK call that triggered them. Keep delegate handlers re-entrant-safe if they call back into the SDK.

Test Mode

Test mode is server-controlled via device whitelisting. This provides better security and control over which devices receive test ads.

To enable test mode:

1. Initialize the SDK and check the logs for your device IFA:

   [CloudX][INFO] Device IFA for test whitelisting: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
   

2. Copy the IFA and add it to your device whitelist on the CloudX server dashboard

3. The SDK will automatically configure adapters for test mode and include the test flag in bid requests

Test mode is determined by the server, so you don’t need to change any code between development and production builds.

Privacy Compliance

The CloudX SDK supports GDPR and CCPA privacy compliance by reading standard IAB privacy strings from NSUserDefaults. These values are typically set automatically by your Consent Management Platform (CMP) such as Google UMP, OneTrust, or Sourcepoint.

How It Works

The SDK automatically detects user location and reads consent signals:

1. EU Users (GDPR): Checks TCF v2 consent for purposes 1 and 2 per the IAB Global Vendor List and vendor consent (CloudX Vendor ID: 1510)
2. US Users (CCPA): Checks for sale/sharing opt-out signals
3. Other Regions: No restrictions applied

When consent is denied or user opts out, the SDK removes PII from ad requests:

• Advertising ID (IDFA) is cleared
• Geo coordinates (lat/lon) are removed
• User key-values are not sent
• Hashed user ID is excluded

Supported Privacy Keys

Key	Standard	Description
IABGPP_HDR_GppString	GPP	Global Privacy Platform string (modern)
IABGPP_GppSID	GPP	Section IDs (e.g., “2” for EU, “7” for US-National, “8” for US-CA)
IABTCF_TCString	TCF v2	GDPR consent string (legacy)
IABTCF_gdprApplies	TCF v2	Whether GDPR applies (1 = yes, 0 = no)
IABUSPrivacy_String	US Privacy	CCPA privacy string (legacy, e.g., “1YNN”)

The SDK prioritizes GPP (modern standard) over legacy TCF/US Privacy strings when both are available.

App Tracking Transparency (ATT)

On iOS 14.5+, you must request App Tracking Transparency authorization before the SDK can access the IDFA. Request ATT permission before initializing the CloudX SDK:

Objective-C

#import <AppTrackingTransparency/AppTrackingTransparency.h>

if (@available(iOS 14.5, *)) {
    [ATTrackingManager requestTrackingAuthorizationWithCompletionHandler:^(ATTrackingManagerAuthorizationStatus status) {
        // Initialize CloudX SDK after ATT response
        [self initializeCloudX];
    }];
} else {
    [self initializeCloudX];
}

Add the NSUserTrackingUsageDescription key to your Info.plist with a description of why you need tracking permission.

Manual Privacy API

If you manage user consent yourself (without a CMP), you can set GDPR and CCPA privacy status directly. Call these before initializing the SDK — some ad network SDKs require privacy settings at initialization time and will not apply values set after init.

Objective-C

// Set privacy BEFORE initializing the SDK
[CloudXCore setHasUserConsent:@YES];
[CloudXCore setDoNotSell:@NO];

[[CloudXCore shared] initializeWithConfiguration:config completion:completion];

When both manual values and CMP signals are present, CMP signals (GPP/TCF/US Privacy) take priority. Manual values act as a fallback when no CMP is integrated. Pass nil to clear manual values and defer entirely to your CMP.

User Targeting

Objective-C

// Set hashed user ID for targeting
[[CloudXCore shared] setHashedUserID:@"hashed-user-id"];

// Set custom user key-value pairs (cleared by privacy regulations)
[[CloudXCore shared] setUserKeyValue:@"age" value:@"25"];
[[CloudXCore shared] setUserKeyValue:@"gender" value:@"male"];
[[CloudXCore shared] setUserKeyValue:@"location" value:@"US"];

// Set custom app key-value pairs (NOT affected by privacy regulations)
[[CloudXCore shared] setAppKeyValue:@"app_version" value:@"1.0.0"];
[[CloudXCore shared] setAppKeyValue:@"user_level" value:@"premium"];

// Clear all custom key-values
[[CloudXCore shared] clearAllKeyValues];

Support

For support, contact [e-mail]