CloudX iOS SDK

需要 iOS 14.0+ 和 Xcode 12.0+。

安装

CocoaPods

Podfile

platform :ios, '14.0'

target 'YourApp' do
  use_frameworks!

  # 核心 SDK
  pod 'CloudXCore'

  # 广告网络适配器（根据需要添加）
  pod 'CloudXMetaAdapter'       # Meta Audience Network 6.21.0
  pod 'CloudXVungleAdapter'     # Vungle SDK 7.6.0
  pod 'CloudXInMobiAdapter'     # InMobi SDK 11.1.0
end

pod install --repo-update

初始化

#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 初始化成功");
    } else {
        NSLog(@"CloudX SDK 初始化失败: %@", error.localizedDescription);
    }
}];

广告集成

横幅广告 (320x50)

@interface YourViewController () <CLXBannerDelegate, CLXAdRevenueDelegate>
@property (nonatomic, strong) CLXBannerAdView *bannerAd;
@end

@implementation YourViewController

- (void)createBannerAd {
    self.bannerAd = [[CloudXCore shared] createBannerWithAdUnitId:@"your-banner-ad-unit-id"
                                                   viewController:self];
    self.bannerAd.delegate = self;
    self.bannerAd.revenueDelegate = self;

    if (self.bannerAd) {
        self.bannerAd.translatesAutoresizingMaskIntoConstraints = NO;
        [self.view addSubview:self.bannerAd];

        [NSLayoutConstraint activateConstraints:@[
            [self.bannerAd.bottomAnchor constraintEqualToAnchor:self.view.safeAreaLayoutGuide.bottomAnchor],
            [self.bannerAd.centerXAnchor constraintEqualToAnchor:self.view.centerXAnchor],
            [self.bannerAd.widthAnchor constraintEqualToConstant:320],
            [self.bannerAd.heightAnchor constraintEqualToConstant:50]
        ]];

        [self.bannerAd load];
    }
}

- (void)dealloc {
    [self.bannerAd destroy];
}

#pragma mark - CLXBannerDelegate

- (void)didLoadAd:(CLXAd *)ad {
    NSLog(@"横幅广告从 %@ 加载成功", ad.networkName);
}

- (void)didFailToLoadAd:(NSString *)adUnitId error:(CLXError *)error {
    NSLog(@"横幅广告加载失败: %@", error.localizedDescription);
}

- (void)didClickAd:(CLXAd *)ad {
    NSLog(@"横幅广告被点击");
}

// 可选：当横幅展开时调用（如 MRAID）
- (void)didExpandAd:(CLXAd *)ad {
    NSLog(@"横幅广告已展开");
}

// 可选：当横幅收起时调用
- (void)didCollapseAd:(CLXAd *)ad {
    NSLog(@"横幅广告已收起");
}

#pragma mark - CLXAdRevenueDelegate

- (void)didPayRevenueForAd:(CLXAd *)ad {
    NSLog(@"横幅广告收入: %@ 来自 %@", ad.revenue, ad.networkName);
}

@end

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

[self.bannerAd stopAutoRefresh];    // 停止自动刷新
[self.bannerAd load];               // 手动加载新广告
[self.bannerAd startAutoRefresh];   // 重新启用自动刷新

可选的展示位置和自定义数据用于追踪：

self.bannerAd.placement = @"home_screen";
self.bannerAd.customData = @"level:5,coins:100";

MREC 广告 (300x250)

@interface YourViewController () <CLXBannerDelegate, CLXAdRevenueDelegate>
@property (nonatomic, strong) CLXBannerAdView *mrecAd;
@end

@implementation YourViewController

- (void)createMRECAd {
    self.mrecAd = [[CloudXCore shared] createMRECWithAdUnitId:@"your-mrec-ad-unit-id"
                                               viewController:self];
    self.mrecAd.delegate = self;
    self.mrecAd.revenueDelegate = self;

    if (self.mrecAd) {
        self.mrecAd.translatesAutoresizingMaskIntoConstraints = NO;
        [self.view addSubview:self.mrecAd];

        [NSLayoutConstraint activateConstraints:@[
            [self.mrecAd.centerXAnchor constraintEqualToAnchor:self.view.centerXAnchor],
            [self.mrecAd.bottomAnchor constraintEqualToAnchor:self.view.safeAreaLayoutGuide.bottomAnchor constant:-20],
            [self.mrecAd.widthAnchor constraintEqualToConstant:300],
            [self.mrecAd.heightAnchor constraintEqualToConstant:250]
        ]];

        [self.mrecAd load];
    }
}

- (void)dealloc {
    [self.mrecAd destroy];
}

#pragma mark - CLXBannerDelegate

- (void)didLoadAd:(CLXAd *)ad {
    NSLog(@"MREC 广告从 %@ 加载成功", ad.networkName);
}

- (void)didFailToLoadAd:(NSString *)adUnitId error:(CLXError *)error {
    NSLog(@"MREC 广告加载失败: %@", error.localizedDescription);
}

- (void)didClickAd:(CLXAd *)ad {
    NSLog(@"MREC 广告被点击");
}

// 可选：当 MREC 展开时调用（如 MRAID）
- (void)didExpandAd:(CLXAd *)ad {
    NSLog(@"MREC 广告已展开");
}

// 可选：当 MREC 收起时调用
- (void)didCollapseAd:(CLXAd *)ad {
    NSLog(@"MREC 广告已收起");
}

#pragma mark - CLXAdRevenueDelegate

- (void)didPayRevenueForAd:(CLXAd *)ad {
    NSLog(@"MREC 广告收入: %@ 来自 %@", ad.revenue, ad.networkName);
}

@end

MREC 广告也默认自动刷新。使用与横幅广告相同的刷新控制方法。

插屏广告

@interface YourViewController () <CLXInterstitialDelegate, CLXAdRevenueDelegate>
@property (nonatomic, strong) CLXInterstitial *interstitialAd;
@end

@implementation YourViewController

- (void)createInterstitialAd {
    self.interstitialAd = [[CloudXCore shared] createInterstitialWithAdUnitId:@"your-interstitial-ad-unit-id"];
    self.interstitialAd.delegate = self;
    self.interstitialAd.revenueDelegate = self;
    [self.interstitialAd load];
}

- (void)showInterstitialAd {
    if (self.interstitialAd.isReady) {
        // 基本展示
        [self.interstitialAd showFromViewController:self];

        // 或使用可选的展示位置和自定义数据进行追踪
        // [self.interstitialAd showFromViewController:self placement:@"level_complete" customData:@"level:5,score:1000"];
    } else {
        NSLog(@"插屏广告尚未准备好");
    }
}

- (void)dealloc {
    [self.interstitialAd destroy];
}

#pragma mark - CLXInterstitialDelegate

- (void)didLoadAd:(CLXAd *)ad {
    NSLog(@"插屏广告从 %@ 加载成功", ad.networkName);
}

- (void)didFailToLoadAd:(NSString *)adUnitId error:(CLXError *)error {
    NSLog(@"插屏广告加载失败: %@", error.localizedDescription);
}

- (void)didDisplayAd:(CLXAd *)ad {
    NSLog(@"插屏广告已展示");
}

- (void)didFailToDisplayAd:(CLXAd *)ad error:(CLXError *)error {
    NSLog(@"插屏广告展示失败: %@", error.localizedDescription);
}

- (void)didHideAd:(CLXAd *)ad {
    NSLog(@"插屏广告已隐藏");
    [self createInterstitialAd]; // 为下次使用重新加载
}

- (void)didClickAd:(CLXAd *)ad {
    NSLog(@"插屏广告被点击");
}

#pragma mark - CLXAdRevenueDelegate

- (void)didPayRevenueForAd:(CLXAd *)ad {
    NSLog(@"插屏广告收入: %@ 来自 %@", ad.revenue, ad.networkName);
}

@end

激励广告

@interface YourViewController () <CLXRewardedDelegate, CLXAdRevenueDelegate>
@property (nonatomic, strong) CLXRewarded *rewardedAd;
@end

@implementation YourViewController

- (void)createRewardedAd {
    self.rewardedAd = [[CloudXCore shared] createRewardedWithAdUnitId:@"your-rewarded-ad-unit-id"];
    self.rewardedAd.delegate = self;
    self.rewardedAd.revenueDelegate = self;
    [self.rewardedAd load];
}

- (void)showRewardedAd {
    if (self.rewardedAd.isReady) {
        // 基本展示
        [self.rewardedAd showFromViewController:self];

        // 或使用可选的展示位置和自定义数据进行追踪
        // [self.rewardedAd showFromViewController:self placement:@"bonus_coins" customData:@"level:5,coins:100"];
    } else {
        NSLog(@"激励广告尚未准备好");
    }
}

- (void)dealloc {
    [self.rewardedAd destroy];
}

#pragma mark - CLXRewardedDelegate

- (void)didLoadAd:(CLXAd *)ad {
    NSLog(@"激励广告从 %@ 加载成功", ad.networkName);
}

- (void)didFailToLoadAd:(NSString *)adUnitId error:(CLXError *)error {
    NSLog(@"激励广告加载失败: %@", error.localizedDescription);
}

- (void)didDisplayAd:(CLXAd *)ad {
    NSLog(@"激励广告已展示");
}

- (void)didFailToDisplayAd:(CLXAd *)ad error:(CLXError *)error {
    NSLog(@"激励广告展示失败: %@", error.localizedDescription);
}

- (void)didHideAd:(CLXAd *)ad {
    NSLog(@"激励广告已隐藏");
    [self createRewardedAd]; // 为下次使用重新加载
}

- (void)didClickAd:(CLXAd *)ad {
    NSLog(@"激励广告被点击");
}

- (void)didRewardUserForAd:(CLXAd *)ad withReward:(CLXReward *)reward {
    NSLog(@"用户获得奖励: %ld %@", (long)reward.amount, reward.label);
    // 向用户发放奖励
}

#pragma mark - CLXAdRevenueDelegate

- (void)didPayRevenueForAd:(CLXAd *)ad {
    NSLog(@"激励广告收入: %@ 来自 %@", ad.revenue, ad.networkName);
}

@end

广告信息 (CLXAd)

CLXAd 对象会传递给代理回调，包含已加载/展示广告的信息：

属性	类型	描述
`adFormat`	`CLXAdFormat`	广告格式（横幅、MREC、插屏、激励）
`adUnitId`	`NSString?`	广告单元 ID
`adUnitName`	`NSString?`	广告单元名称
`networkName`	`NSString?`	获胜广告网络的名称
`networkPlacement`	`NSString?`	网络特定的展示位置 ID
`placement`	`NSString?`	通过 `placement` 属性设置的自定义展示位置
`revenue`	`NSNumber?`	展示级别收入（美元）

- (void)didLoadAd:(CLXAd *)ad {
    NSLog(@"广告格式: %ld", (long)ad.adFormat);
    NSLog(@"网络: %@", ad.networkName);
    NSLog(@"收入: %@", ad.revenue);
}

错误处理

所有 SDK 错误都作为 CLXError 对象在代理回调中返回：

属性	类型	描述
`code`	`CLXErrorCode`	错误类别
`localizedDescription`	`NSString`	人类可读的描述
`underlyingError`	`NSError?`	可选的底层错误

错误代码类别

范围	类别	常见代码
0	通用	`CLXErrorCodeInternalError`
100-199	网络	`CLXErrorCodeNetworkError`、`CLXErrorCodeNetworkTimeout`、`CLXErrorCodeServerError`、`CLXErrorCodeNoConnection`
200-299	初始化	`CLXErrorCodeNotInitialized`、`CLXErrorCodeSDKDisabled`、`CLXErrorCodeNoAdaptersFound`、`CLXErrorCodeInvalidAppKey`
300-399	广告加载	`CLXErrorCodeNoFill`、`CLXErrorCodeInvalidAdUnit`、`CLXErrorCodeAdsDisabled`
400-499	展示	`CLXErrorCodeAdNotReady`、`CLXErrorCodeAdAlreadyShowing`
600-699	适配器	`CLXErrorCodeAdapterNoFill`、`CLXErrorCodeAdapterTimeout`、`CLXErrorCodeAdapterLoadTimeout`、`CLXErrorCodeAdapterInitializationError`

高级功能

调试日志

[CloudXCore setMinLogLevel:CLXLogLevelDebug];  // 启用调试日志
[CloudXCore setMinLogLevel:CLXLogLevelNone];   // 禁用所有日志

日志级别： verbose < debug < info < warn < error < none

展示级别收入追踪

在任何广告格式上设置 revenueDelegate 以接收展示级别收入（ILR）回调。CLXAd 对象包含以美元计价的收入值和获胜网络名称。

self.bannerAd.revenueDelegate = self;

- (void)didPayRevenueForAd:(CLXAd *)ad {
    NSLog(@"收入: %@ 来自 %@", ad.revenue, ad.networkName);
}

适用于所有广告格式（横幅、MREC、插屏、激励）。

测试模式

测试模式通过设备白名单进行服务端控制。这提供了更好的安全性和对哪些设备接收测试广告的控制。 启用测试模式：

初始化 SDK 并检查日志中的设备 IFA：

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

复制 IFA 并将其添加到 CloudX 服务器仪表板的设备白名单中
SDK 将自动为测试模式配置适配器并在竞价请求中包含测试标志

测试模式由服务器确定，因此您不需要在开发和线上版本之间更改任何代码。

隐私合规

CloudX SDK 通过从 NSUserDefaults 读取标准 IAB 隐私字符串来支持 GDPR 和 CCPA 隐私合规。这些值通常由您的同意管理平台（CMP）自动设置，如 Google UMP、OneTrust 或 Sourcepoint。

工作原理

SDK 自动检测用户位置并读取同意信号：

欧盟用户（GDPR）：检查 TCF v2 对目的 1-4 的同意和供应商同意（CloudX 供应商 ID：1510）
美国用户（CCPA）：检查销售/共享选择退出信号
其他地区：无限制

当用户拒绝同意或选择退出时，SDK 会从广告请求中移除 PII：

广告标识符（IDFA）被清除
地理坐标（纬度/经度）被移除
用户键值不会发送
哈希用户 ID 被排除

支持的隐私密钥

密钥	标准	描述
`IABGPP_HDR_GppString`	GPP	全球隐私平台字符串（现代）
`IABGPP_GppSID`	GPP	Section IDs（如 “2” 为欧盟，“7” 为美国国家，“8” 为美国加州）
`IABTCF_TCString`	TCF v2	GDPR 同意字符串（旧版）
`IABTCF_gdprApplies`	TCF v2	GDPR 是否适用（1 = 是，0 = 否）
`IABUSPrivacy_String`	US Privacy	CCPA 隐私字符串（旧版，如 “1YNN”）

当两者都可用时，SDK 优先使用 GPP（现代标准）而非旧版 TCF/US Privacy 字符串。

应用追踪透明度（ATT）

在 iOS 14.5+ 上，您必须在 SDK 可以访问 IDFA 之前请求应用追踪透明度授权。在初始化 CloudX SDK 之前请求 ATT 权限：

#import <AppTrackingTransparency/AppTrackingTransparency.h>

if (@available(iOS 14.5, *)) {
    [ATTrackingManager requestTrackingAuthorizationWithCompletionHandler:^(ATTrackingManagerAuthorizationStatus status) {
        // 在 ATT 响应后初始化 CloudX SDK
        [self initializeCloudX];
    }];
} else {
    [self initializeCloudX];
}

在 Info.plist 中添加 NSUserTrackingUsageDescription 键，并说明您需要追踪权限的原因。

用户定向

// 设置哈希用户 ID 用于定向
[[CloudXCore shared] setHashedUserID:@"hashed-user-id"];

// 设置自定义用户键值对（受隐私法规清除）
[[CloudXCore shared] setUserKeyValue:@"age" value:@"25"];
[[CloudXCore shared] setUserKeyValue:@"gender" value:@"male"];
[[CloudXCore shared] setUserKeyValue:@"location" value:@"US"];

// 设置自定义应用键值对（不受隐私法规影响）
[[CloudXCore shared] setAppKeyValue:@"app_version" value:@"1.0.0"];
[[CloudXCore shared] setAppKeyValue:@"user_level" value:@"premium"];

// 清除所有自定义键值
[[CloudXCore shared] clearAllKeyValues];

技术支持

如需支持，请联系 mobile@cloudx.io

iOS SDK

适配器

​CloudX iOS SDK

​安装

​CocoaPods

​初始化

​广告集成

​横幅广告 (320x50)

​MREC 广告 (300x250)

​插屏广告

​激励广告

​广告信息 (CLXAd)

​错误处理

​错误代码类别

​高级功能

​调试日志

​展示级别收入追踪

​测试模式

​隐私合规

​工作原理

​支持的隐私密钥

​应用追踪透明度（ATT）

​用户定向

​技术支持

CloudX iOS SDK

安装

CocoaPods

初始化

广告集成

横幅广告 (320x50)

MREC 广告 (300x250)

插屏广告

激励广告

广告信息 (CLXAd)

错误处理

错误代码类别

高级功能

调试日志

展示级别收入追踪

测试模式

隐私合规

工作原理

支持的隐私密钥

应用追踪透明度（ATT）

用户定向

技术支持