> ## 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. # 集成 > CloudX Android SDK 完整集成指南 [![Maven Central](https://img.shields.io/maven-central/v/io.cloudx/sdk)](https://central.sonatype.com/artifact/io.cloudx/sdk) ## 使用 Claude Code 自动集成 **借助 AI 驱动的代理，15 分钟内完成 CloudX SDK 集成：** 需要 [Claude Code](https://claude.ai/code)。 ```bash theme={null} # 安装 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） * **构建验证**及早发现错误 * **保留现有广告设置**作为备份 **[完整设置指南](https://github.com/cloudx-io/cloudx-sdk-agents)** ## 手动安装需要 Android API 23+ 和 Java 8+。将 CloudX SDK 添加到您应用的 build.gradle： ```kotlin Kotlin DSL theme={null} dependencies { implementation("io.cloudx:sdk:4.2.0") // 广告网络适配器 implementation("io.cloudx:adapter-digitalturbine:8.4.6.0") // Digital Turbine Marketplace SDK 8.4.6 implementation("io.cloudx:adapter-googlewaterfall:25.2.0.0") // Google Mobile Ads SDK 25.2.0 implementation("io.cloudx:adapter-inmobi:11.4.0.1") // InMobi SDK 11.4.0 implementation("io.cloudx:adapter-magnite:1.0.0.1") // Magnite Ads SDK 1.0.0 implementation("io.cloudx:adapter-meta:6.21.0.3") // Meta Audience Network 6.21.0 implementation("io.cloudx:adapter-mintegral:17.1.61.2") // Mintegral SDK 17.1.61 implementation("io.cloudx:adapter-mobilefuse:1.11.0.1") // MobileFuse SDK 1.11.0 implementation("io.cloudx:adapter-moloco:4.10.1.0") // Moloco SDK 4.10.1 implementation("io.cloudx:adapter-pangle:8.1.0.4.1") // Pangle SDK 8.1.0.4 implementation("io.cloudx:adapter-taurusx:1.18.3.0") // TaurusX SDK 1.18.3 implementation("io.cloudx:adapter-unityads:4.19.0.1") // Unity Ads SDK 4.19.0 implementation("io.cloudx:adapter-verve:3.9.0.1") // Verve HyBid SDK 3.9.0 implementation("io.cloudx:adapter-vungle:7.7.5.0") // Vungle SDK 7.7.5 } ``` ```groovy Groovy theme={null} dependencies { implementation 'io.cloudx:sdk:4.2.0' // 广告网络适配器 implementation 'io.cloudx:adapter-digitalturbine:8.4.6.0' // Digital Turbine Marketplace SDK 8.4.6 implementation 'io.cloudx:adapter-googlewaterfall:25.2.0.0' // Google Mobile Ads SDK 25.2.0 implementation 'io.cloudx:adapter-inmobi:11.4.0.1' // InMobi SDK 11.4.0 implementation 'io.cloudx:adapter-magnite:1.0.0.1' // Magnite Ads SDK 1.0.0 implementation 'io.cloudx:adapter-meta:6.21.0.3' // Meta Audience Network 6.21.0 implementation 'io.cloudx:adapter-mintegral:17.1.61.2' // Mintegral SDK 17.1.61 implementation 'io.cloudx:adapter-mobilefuse:1.11.0.1' // MobileFuse SDK 1.11.0 implementation 'io.cloudx:adapter-moloco:4.10.1.0' // Moloco SDK 4.10.1 implementation 'io.cloudx:adapter-pangle:8.1.0.4.1' // Pangle SDK 8.1.0.4 implementation 'io.cloudx:adapter-taurusx:1.18.3.0' // TaurusX SDK 1.18.3 implementation 'io.cloudx:adapter-unityads:4.19.0.1' // Unity Ads SDK 4.19.0 implementation 'io.cloudx:adapter-verve:3.9.0.1' // Verve HyBid SDK 3.9.0 implementation 'io.cloudx:adapter-vungle:7.7.5.0' // Vungle SDK 7.7.5 } ``` ## 初始化 ```kotlin Kotlin theme={null} // 使用应用密钥初始化 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}") } } ) ``` ```java Java theme={null} // 使用应用密钥初始化 CloudXInitializationConfiguration configuration = CloudXInitializationConfiguration.builder("your-app-key-here") .build(); CloudX.initialize(configuration, new CloudXInitializationListener() { @Override public void onInitialized(@NonNull CloudXSdkConfiguration configuration) { Log.d("CloudX", "CloudX SDK 初始化成功"); } @Override public void onInitializationFailed(@NonNull CloudXError cloudXError) { Log.e("CloudX", "CloudX SDK 初始化失败: " + cloudXError.getMessage()); } }); ``` ## 广告格式 CloudX 支持横幅、MREC、插屏、激励视频、原生和 App Open 广告集成。请使用对应广告格式指南查看实现细节：创建固定尺寸展示广告位，并可选择控制刷新。加载和展示全屏插屏广告位。渲染原生创意和 Reels 风格原生视频体验。在用户完成激励广告观看后发放奖励。在自然的应用打开或回到前台时机展示全屏广告。 ### 广告信息 (CloudXAd) `CloudXAd` 对象在监听器回调中传递，包含已加载/已展示广告的信息： | 属性 | 类型 | 描述 | | ------------------ | --------------------- | --------------------------------------------------------- | | `adFormat` | `CloudXAdFormat` | 广告格式 (BANNER、MREC、INTERSTITIAL、REWARDED、NATIVE、APP\_OPEN) | | `adUnitId` | `String` | 广告单元 ID | | `networkName` | `String` | 获胜广告网络的名称 | | `networkPlacement` | `String?` | 网络特定的广告位 ID | | `placement` | `String?` | 通过 `setPlacement()` 设置的自定义广告位 | | `revenue` | `Double` | 竞价时收入估算（以美元计价） | | `adValues` | `Map` | SDK 提供的广告元数据，可用于 Trusted Arbiter 等功能 | ```kotlin theme={null} 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 Kotlin theme={null} CloudX.setMinLogLevel(CloudXLogLevel.DEBUG) // 启用调试日志 CloudX.setMinLogLevel(CloudXLogLevel.NONE) // 禁用所有日志 ``` ```java Java theme={null} CloudX.setMinLogLevel(CloudXLogLevel.DEBUG); // 启用调试日志 CloudX.setMinLogLevel(CloudXLogLevel.NONE); // 禁用所有日志 ``` **日志级别：** `VERBOSE` \< `DEBUG` \< `INFO` \< `WARN` \< `ERROR` \< `NONE` 使用标签 `CloudX` 过滤 logcat 以查看 SDK 日志。 ### 上报 AdMob 收益数据如果您的应用在 CloudX Google Waterfall 适配器之外接收 AdMob paid event，请在 CloudX 初始化完成后将这些展示级收入事件转发给 CloudX： ```kotlin theme={null} val revenueData = CloudXRevenueData.builder( platform = CloudXRevenuePlatform.ADMOB, revenue = adValue.valueMicros, adFormat = "banner", ) .currencyCode(adValue.currencyCode) .precision(CloudXRevenuePrecision.ESTIMATED) .adUnitId(adUnitId) .networkName(responseInfo.mediationAdapterClassName) .build() val accepted = CloudX.reportRevenueData(revenueData) ``` AdMob 的 `AdValue.valueMicros` 以所提供货币的微单位上报，因此请将原始 micros 值传给 `revenue`。当事件被 CloudX 收益链路接受时，`reportRevenueData()` 返回 `true`。如果 SDK 尚未初始化、服务端未启用收益跟踪，或应用中没有可用的上报平台，则返回 `false`。 ### 展示级收入追踪在任何广告格式上设置 `revenueListener` 以接收收入回调。`CloudXAd.revenue` 包含以美元计价的竞价时收入估算。 ```kotlin Kotlin theme={null} bannerAd.revenueListener = object : CloudXAdRevenueListener { override fun onAdRevenuePaid(cloudXAd: CloudXAd) { Log.d("CloudX", "竞价时收入: ${cloudXAd.revenue}，来自 ${cloudXAd.networkName}") } } ``` ```java Java theme={null} bannerAd.setRevenueListener(new CloudXAdRevenueListener() { @Override public void onAdRevenuePaid(@NonNull CloudXAd cloudXAd) { Log.d("CloudX", "竞价时收入: " + cloudXAd.getRevenue() + "，来自 " + cloudXAd.getNetworkName()); } }); ``` 适用于所有广告格式（横幅、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 全球供应商列表](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework) 检查 TCF v2 目的 1 和 2 的同意和供应商同意（[CloudX 供应商 ID：1510](https://vendor-list.consensu.org/v3/vendor-list.json)） 2. **美国用户 (CCPA)**：检查销售/共享退出信号 3. **其他地区**：不应用限制当同意被拒绝或用户选择退出时，SDK 会从广告请求中删除个人身份信息： * 广告 ID (GAID) 被清除 * 地理坐标（经纬度）被删除 * 用户键值对不发送 * 哈希用户 ID 被排除 #### 支持的隐私密钥 | 密钥 | 标准 | 描述 | | ---------------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------- | | `IABGPP_HDR_GppString` | [GPP](https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform) | 全球隐私平台字符串（现代） | | `IABGPP_GppSID` | GPP | 部分 ID（例如，"2" 代表欧盟，"7" 代表美国国家，"8" 代表美国加州） | | `IABTCF_TCString` | [TCF v2](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework) | GDPR 同意字符串（传统） | | `IABTCF_gdprApplies` | TCF v2 | GDPR 是否适用（1 = 是，0 = 否） | | `IABUSPrivacy_String` | [US Privacy](https://github.com/InteractiveAdvertisingBureau/USPrivacy) | CCPA 隐私字符串（传统，例如 "1YNN"） | > **注意**：当 GPP（现代标准）和传统 TCF/US Privacy 字符串同时存在时，SDK 优先使用 GPP。 #### 手动隐私 API 如果您自行管理用户同意（不使用 CMP），可以直接设置 GDPR 和 CCPA 隐私状态。这些方法必须在 SDK 初始化之前调用。 ```kotlin Kotlin theme={null} // GDPR 同意：true、false 或 null（回退到 CMP） CloudX.setHasUserConsent(true) // CCPA do-not-sell：true、false 或 null（回退到 CMP） CloudX.setDoNotSell(true) ``` ```java Java theme={null} // 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 Kotlin theme={null} // 设置哈希用户 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() ``` ```java Java theme={null} // 设置哈希用户 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(); ``` ## 技术支持如需支持，请联系 [mobile@cloudx.io](mailto:mobile@cloudx.io)