集成

CloudX Android SDK 完整集成指南

​

使用 Claude Code 自动集成

借助 AI 驱动的代理，15 分钟内完成 CloudX SDK 集成：

需要 Claude Code。

# 安装 CloudX 代理
bash <(curl -fsSL https://raw.githubusercontent.com/cloudx-io/cloudx-sdk-agents/main/scripts/install.sh)

# 在您的 Android 项目中：
claude "Use @agent-cloudx-android-integrator to integrate CloudX SDK with app key: YOUR_KEY"

• CloudX 优先加载，自动回退到现有广告设置
• 隐私合规验证（GDPR、CCPA）
• 构建验证及早发现错误
• 保留现有广告设置作为备份

完整设置指南

​

手动安装

需要 Android API 23+ 和 Java 8+。

将 CloudX SDK 添加到您应用的 build.gradle：

Kotlin DSL

dependencies {
    implementation("io.cloudx:sdk:4.1.1")

    // 广告网络适配器
    implementation("io.cloudx:adapter-digitalturbine:8.4.5.0")     // Digital Turbine Marketplace SDK 8.4.5
    implementation("io.cloudx:adapter-googlewaterfall:25.1.0.0")   // Google Mobile Ads SDK 25.1.0
    implementation("io.cloudx:adapter-inmobi:11.2.0.0")            // InMobi SDK 11.2.0
    implementation("io.cloudx:adapter-magnite:1.0.0.0")            // Magnite Ads SDK 1.0.0
    implementation("io.cloudx:adapter-meta:6.21.0.1")              // Meta Audience Network 6.21.0
    implementation("io.cloudx:adapter-mintegral:17.1.51.0")        // Mintegral SDK 17.1.51
    implementation("io.cloudx:adapter-moloco:4.8.0.0")             // Moloco SDK 4.8.0
    implementation("io.cloudx:adapter-unityads:4.17.0.0")          // Unity Ads SDK 4.17.0
    implementation("io.cloudx:adapter-verve:3.8.1.0")              // Verve HyBid SDK 3.8.1
    implementation("io.cloudx:adapter-vungle:7.7.3.0")             // Vungle SDK 7.7.3
}

​

初始化

Kotlin

// 使用应用密钥初始化
CloudX.initialize(
    configuration = CloudXInitializationConfiguration.builder("your-app-key-here")
        .build(),
    listener = object : CloudXInitializationListener {
        override fun onInitialized(configuration: CloudXSdkConfiguration) {
            Log.d("CloudX", "CloudX SDK 初始化成功")
        }

        override fun onInitializationFailed(cloudXError: CloudXError) {
            Log.e("CloudX", "CloudX SDK 初始化失败: ${cloudXError.message}")
        }
    }
)

​

广告格式

CloudX 支持横幅、MREC、插屏、激励视频和原生广告集成。请使用对应广告格式指南查看实现细节：

横幅和 MREC 广告

创建固定尺寸展示广告位，并可选择控制刷新。

插屏广告

加载和展示全屏插屏广告位。

原生广告

渲染原生创意和 Reels 风格原生视频体验。

激励视频广告

在用户完成激励广告观看后发放奖励。

​

广告信息 (CloudXAd)

CloudXAd 对象在监听器回调中传递，包含已加载/已展示广告的信息：

属性	类型	描述
adFormat	CloudXAdFormat	广告格式 (BANNER、MREC、INTERSTITIAL、REWARDED、NATIVE)
adUnitId	String	广告单元 ID
networkName	String	获胜广告网络的名称
networkPlacement	String?	网络特定的广告位 ID
placement	String?	通过 setPlacement() 设置的自定义广告位
revenue	Double	竞价时收入估算（以美元计价）
adValues	Map<String, String>	SDK 提供的广告元数据，可用于 Trusted Arbiter 等功能

override fun onAdLoaded(cloudXAd: CloudXAd) {
    Log.d("CloudX", "广告格式: ${cloudXAd.adFormat}")
    Log.d("CloudX", "网络: ${cloudXAd.networkName}")
    Log.d("CloudX", "竞价时收入: ${cloudXAd.revenue}")
}

​

错误处理

所有 SDK 错误都以 CloudXError 对象的形式在监听器回调中返回：

属性	类型	描述
code	CloudXErrorCode	错误类别
message	String	人类可读的描述
cause	Throwable?	可选的底层异常
formattedMessage	String	预格式化的消息，包含代码和描述

​

错误代码类别

范围	类别	常见代码
0	一般	INTERNAL_ERROR
100-199	网络	NETWORK_ERROR、NETWORK_TIMEOUT、NETWORK_SERVER_ERROR、NETWORK_NO_CONNECTION
200-299	初始化	NOT_INITIALIZED、SDK_DISABLED、NO_ADAPTERS_FOUND、INVALID_APP_KEY
300-399	广告加载	NO_FILL、INVALID_AD_UNIT、ADS_DISABLED
400-499	展示	AD_NOT_READY、AD_ALREADY_SHOWING
600-699	适配器	ADAPTER_NO_FILL、ADAPTER_TIMEOUT、ADAPTER_LOAD_TIMEOUT、ADAPTER_INITIALIZATION_ERROR

​

高级功能

​

调试日志

Kotlin

CloudX.setMinLogLevel(CloudXLogLevel.DEBUG)  // 启用调试日志
CloudX.setMinLogLevel(CloudXLogLevel.NONE)   // 禁用所有日志

日志级别： VERBOSE < DEBUG < INFO < WARN < ERROR < NONE

使用标签 CloudX 过滤 logcat 以查看 SDK 日志。

​

展示级收入追踪

在任何广告格式上设置 revenueListener 以接收收入回调。CloudXAd.revenue 包含以美元计价的竞价时收入估算。

Kotlin

bannerAd.revenueListener = object : CloudXAdRevenueListener {
    override fun onAdRevenuePaid(cloudXAd: CloudXAd) {
        Log.d("CloudX", "竞价时收入: ${cloudXAd.revenue}，来自 ${cloudXAd.networkName}")
    }
}

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

​

测试模式

测试模式由服务器控制，通过设备白名单实现。这提供了更好的安全性，并能控制哪些设备接收测试广告。

启用测试模式：

1. 初始化 SDK 并检查 logcat 中的设备广告 ID：

   [CloudX][AdvertisingIdProvider] Device IFA for test whitelisting: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX (LAT: false)
   

2. 复制广告 ID 并将其添加到 CloudX 服务器控制台的设备白名单中

3. SDK 将自动为测试模式配置适配器，并在竞价请求中包含测试标志

注意： 测试模式由服务器决定，因此您无需在开发和生产构建之间更改任何代码。

​

隐私合规

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

​

工作原理

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

1. 欧盟用户 (GDPR)：根据 IAB 全球供应商列表 检查 TCF v2 目的 1 和 2 的同意和供应商同意（CloudX 供应商 ID：1510）
2. 美国用户 (CCPA)：检查销售/共享退出信号
3. 其他地区：不应用限制

当同意被拒绝或用户选择退出时，SDK 会从广告请求中删除个人身份信息：

• 广告 ID (GAID) 被清除
• 地理坐标（经纬度）被删除
• 用户键值对不发送
• 哈希用户 ID 被排除

​

支持的隐私密钥

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

注意：当 GPP（现代标准）和传统 TCF/US Privacy 字符串同时存在时，SDK 优先使用 GPP。

​

手动隐私 API

如果您自行管理用户同意（不使用 CMP），可以直接设置 GDPR 和 CCPA 隐私状态。这些方法必须在 SDK 初始化之前调用。

Kotlin

// GDPR 同意：true、false 或 null（回退到 CMP）
CloudX.setHasUserConsent(true)

// CCPA do-not-sell：true、false 或 null（回退到 CMP）
CloudX.setDoNotSell(true)

当手动设置值和 CMP 信号同时存在时，CMP 信号（GPP/TCF/US Privacy）优先。手动设置值在未集成 CMP 时作为回退使用。

​

用户定向

Kotlin

// 设置哈希用户 ID 用于定向
CloudX.setHashedUserId("hashed-user-id")

// 设置自定义用户键值对
CloudX.setUserKeyValue("age", "25")
CloudX.setUserKeyValue("gender", "male")
CloudX.setUserKeyValue("location", "US")

// 设置自定义应用键值对
CloudX.setAppKeyValue("app_version", "1.0.0")
CloudX.setAppKeyValue("user_level", "premium")

// 清除所有自定义键值对
CloudX.clearAllKeyValues()

​

技术支持

如需支持，请联系 [e-mail]