跳转到主要内容

CloudX Android SDK

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 21+ 和 Java 8+。 将 CloudX SDK 添加到您应用的 build.gradle:
dependencies {
    implementation("io.cloudx:sdk:0.12.0")

    // 广告网络适配器
    implementation("io.cloudx:adapter-cloudx:0.12.0")
    implementation("io.cloudx:adapter-meta:0.12.0")    // Meta Audience Network 6.17.0
    implementation("io.cloudx:adapter-vungle:0.12.0")  // Vungle SDK 7.6.1
}

初始化

// 使用应用密钥初始化
CloudX.initialize(
    initParams = CloudXInitializationParams(
        appKey = "your-app-key-here",
        testMode = false  // 开发时设置为 true 以获取测试广告
    ),
    listener = object : CloudXInitializationListener {
        override fun onInitialized() {
            Log.d("CloudX", "CloudX SDK 初始化成功")
        }

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

广告集成

横幅广告 (320x50)

class MainActivity : AppCompatActivity(), CloudXAdViewListener {
    private lateinit var bannerAd: CloudXAdView

    private fun createBannerAd() {
        bannerAd = CloudX.createBanner("your-banner-placement-name")
        bannerAd.listener = this

        val layoutParams = LinearLayout.LayoutParams(
            LinearLayout.LayoutParams.WRAP_CONTENT,
            LinearLayout.LayoutParams.WRAP_CONTENT
        )
        layoutParams.gravity = Gravity.CENTER_HORIZONTAL
        findViewById<LinearLayout>(R.id.banner_container).addView(bannerAd, layoutParams)
    }

    override fun onDestroy() {
        super.onDestroy()
        bannerAd.destroy()
    }

    // CloudXAdViewListener 回调
    override fun onAdLoaded(cloudXAd: CloudXAd) {
        Log.d("CloudX", "横幅广告已加载,来自 ${cloudXAd.bidderName}")
    }

    override fun onAdLoadFailed(cloudXError: CloudXError) {
        Log.e("CloudX", "横幅广告加载失败: ${cloudXError.message}")
    }

    override fun onAdDisplayed(cloudXAd: CloudXAd) {
        Log.d("CloudX", "横幅广告已展示")
    }

    override fun onAdClicked(cloudXAd: CloudXAd) {
        Log.d("CloudX", "横幅广告被点击")
    }

    override fun onAdHidden(cloudXAd: CloudXAd) {
        Log.d("CloudX", "横幅广告已隐藏")
    }

    override fun onAdDisplayFailed(cloudXError: CloudXError) {
        Log.e("CloudX", "横幅广告展示失败: ${cloudXError.message}")
    }

    override fun onAdExpanded(cloudXAd: CloudXAd) {
        Log.d("CloudX", "横幅广告已展开")
    }

    override fun onAdCollapsed(cloudXAd: CloudXAd) {
        Log.d("CloudX", "横幅广告已折叠")
    }
}
横幅广告默认自动刷新。手动控制刷新:
bannerAd.stopAutoRefresh()  // 停止自动刷新
bannerAd.load()             // 手动加载新广告
bannerAd.startAutoRefresh() // 重新启用自动刷新

MREC 广告 (300x250)

class MainActivity : AppCompatActivity(), CloudXAdViewListener {
    private lateinit var mrecAd: CloudXAdView

    private fun createMrecAd() {
        mrecAd = CloudX.createMREC("your-mrec-placement-name")
        mrecAd.listener = this

        val layoutParams = LinearLayout.LayoutParams(
            LinearLayout.LayoutParams.WRAP_CONTENT,
            LinearLayout.LayoutParams.WRAP_CONTENT
        )
        layoutParams.gravity = Gravity.CENTER_HORIZONTAL
        findViewById<LinearLayout>(R.id.mrec_container).addView(mrecAd, layoutParams)
    }

    override fun onDestroy() {
        super.onDestroy()
        mrecAd.destroy()
    }

    // CloudXAdViewListener 回调(与横幅广告相同)
    override fun onAdLoaded(cloudXAd: CloudXAd) {
        Log.d("CloudX", "MREC 广告已加载,来自 ${cloudXAd.bidderName}")
    }

    override fun onAdLoadFailed(cloudXError: CloudXError) {
        Log.e("CloudX", "MREC 广告加载失败: ${cloudXError.message}")
    }

    override fun onAdDisplayed(cloudXAd: CloudXAd) {
        Log.d("CloudX", "MREC 广告已展示")
    }

    override fun onAdClicked(cloudXAd: CloudXAd) {
        Log.d("CloudX", "MREC 广告被点击")
    }

    override fun onAdHidden(cloudXAd: CloudXAd) {
        Log.d("CloudX", "MREC 广告已隐藏")
    }

    override fun onAdDisplayFailed(cloudXError: CloudXError) {
        Log.e("CloudX", "MREC 广告展示失败: ${cloudXError.message}")
    }

    override fun onAdExpanded(cloudXAd: CloudXAd) {
        Log.d("CloudX", "MREC 广告已展开")
    }

    override fun onAdCollapsed(cloudXAd: CloudXAd) {
        Log.d("CloudX", "MREC 广告已折叠")
    }
}
MREC 广告也默认自动刷新。使用与横幅广告相同的刷新控制方法。

插屏广告

class MainActivity : AppCompatActivity(), CloudXInterstitialListener {
    private lateinit var interstitialAd: CloudXInterstitialAd

    private fun createInterstitialAd() {
        interstitialAd = CloudX.createInterstitial("your-interstitial-placement-name")
        interstitialAd.listener = this
        interstitialAd.load()
    }

    private fun showInterstitialAd() {
        if (interstitialAd.isAdReady) {
            interstitialAd.show()
        } else {
            Log.w("CloudX", "插屏广告尚未准备好")
        }
    }

    override fun onDestroy() {
        super.onDestroy()
        interstitialAd.destroy()
    }

    // CloudXInterstitialListener 回调
    override fun onAdLoaded(cloudXAd: CloudXAd) {
        Log.d("CloudX", "插屏广告已加载,来自 ${cloudXAd.bidderName}")
    }

    override fun onAdLoadFailed(cloudXError: CloudXError) {
        Log.e("CloudX", "插屏广告加载失败: ${cloudXError.message}")
    }

    override fun onAdDisplayed(cloudXAd: CloudXAd) {
        Log.d("CloudX", "插屏广告已展示")
    }

    override fun onAdDisplayFailed(cloudXError: CloudXError) {
        Log.e("CloudX", "插屏广告展示失败: ${cloudXError.message}")
    }

    override fun onAdHidden(cloudXAd: CloudXAd) {
        Log.d("CloudX", "插屏广告已隐藏")
        // 为下次使用重新加载
        interstitialAd.load()
    }

    override fun onAdClicked(cloudXAd: CloudXAd) {
        Log.d("CloudX", "插屏广告被点击")
    }
}

错误处理

所有 SDK 错误都以 CloudXError 对象的形式在监听器回调中返回,包含 code(错误类别)、message(人类可读的描述)和可选的 cause(底层异常)。

错误代码类别

范围类别常见代码
100-199初始化NOT_INITIALIZEDINVALID_APP_KEYNO_ADAPTERS_FOUND
200-299网络NETWORK_ERRORNETWORK_TIMEOUTSERVER_ERROR
300-399广告加载NO_FILLINVALID_PLACEMENTLOAD_TIMEOUT
400-499广告展示AD_NOT_READYAD_EXPIREDDISPLAY_FAILED
600-699适配器ADAPTER_NO_FILLADAPTER_TIMEOUT

高级功能

调试日志

CloudX.setMinLogLevel(CloudXLogLevel.DEBUG)  // 启用调试日志
CloudX.setMinLogLevel(CloudXLogLevel.NONE)   // 禁用所有日志
使用标签 CloudX 过滤 logcat 以查看 SDK 日志。

测试模式

// 启用 Meta Audience Network 测试模式
import io.cloudx.adapter.meta.enableMetaAudienceNetworkTestMode
enableMetaAudienceNetworkTestMode(true)

收入追踪

在任何广告格式上设置 revenueListener 以在广告展示被追踪时接收收入回调。CloudXAd 对象包含以美元计价的收入值和获胜竞价方名称。
bannerAd.revenueListener = object : CloudXAdRevenueListener {
    override fun onAdRevenuePaid(cloudXAd: CloudXAd) {
        Log.d("CloudX", "收入: ${cloudXAd.revenue},来自 ${cloudXAd.bidderName}")
    }
}
适用于所有广告格式(横幅、MREC、插屏)。

隐私合规

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

工作原理

SDK 自动检测用户位置并读取同意信号:
  1. 欧盟用户 (GDPR):检查 TCF v2 目的 1-4 的同意和供应商同意(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。

用户定向

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

技术支持

如需支持,请联系 [email protected]