跳转到主要内容

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.

Maven Central

​
使用 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： 
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
}

​
初始化

// 使用应用密钥初始化
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 对象在监听器回调中传递，包含已加载/已展示广告的信息：
属性类型描述
adFormatCloudXAdFormat广告格式 (BANNER、MREC、INTERSTITIAL、REWARDED、NATIVE)
adUnitIdString广告单元 ID
networkNameString获胜广告网络的名称
networkPlacementString?网络特定的广告位 ID
placementString?通过 setPlacement() 设置的自定义广告位
revenueDouble竞价时收入估算（以美元计价）
adValuesMap<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 对象的形式在监听器回调中返回：
属性类型描述
codeCloudXErrorCode错误类别
messageString人类可读的描述
causeThrowable?可选的底层异常
formattedMessageString预格式化的消息，包含代码和描述

​
错误代码类别

范围类别常见代码
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

​
高级功能

​
调试日志

CloudX.setMinLogLevel(CloudXLogLevel.DEBUG)  // 启用调试日志
CloudX.setMinLogLevel(CloudXLogLevel.NONE)   // 禁用所有日志
日志级别： VERBOSE < DEBUG < INFO < WARN < ERROR < NONE 使用标签 CloudX 过滤 logcat 以查看 SDK 日志。

​
展示级收入追踪

在任何广告格式上设置 revenueListener 以接收收入回调。CloudXAd.revenue 包含以美元计价的竞价时收入估算。 
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_GppStringGPP全球隐私平台字符串（现代）
IABGPP_GppSIDGPP部分 ID（例如，“2” 代表欧盟，“7” 代表美国国家，“8” 代表美国加州）
IABTCF_TCStringTCF v2GDPR 同意字符串（传统）
IABTCF_gdprAppliesTCF v2GDPR 是否适用（1 = 是，0 = 否）
IABUSPrivacy_StringUS PrivacyCCPA 隐私字符串（传统，例如 “1YNN”）
注意：当 GPP（现代标准）和传统 TCF/US Privacy 字符串同时存在时，SDK 优先使用 GPP。

​
手动隐私 API

如果您自行管理用户同意（不使用 CMP），可以直接设置 GDPR 和 CCPA 隐私状态。这些方法必须在 SDK 初始化之前调用。 
// 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 时作为回退使用。

​
用户定向

// 设置哈希用户 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