跳转到主要内容

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

    // 广告网络适配器
    implementation("io.cloudx:adapter-cloudx:2.0.0")
    implementation("io.cloudx:adapter-meta:2.0.0")       // Meta Audience Network 6.21.0
    implementation("io.cloudx:adapter-vungle:2.0.0")     // Vungle SDK 7.6.1
    implementation("io.cloudx:adapter-inmobi:2.0.0")     // InMobi SDK 11.1.0
}

初始化

// 使用应用密钥初始化
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}")
        }
    }
)

广告集成

横幅广告 (320x50)

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

    private fun createBannerAd() {
        bannerAd = CloudX.createBanner("your-banner-ad-unit-id")
        bannerAd.listener = this
        bannerAd.revenueListener = 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.networkName}")
    }

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

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

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

    override fun onAdCollapsed(cloudXAd: CloudXAd) {
        Log.d("CloudX", "横幅广告已折叠")
    }

    // CloudXAdRevenueListener 回调
    override fun onAdRevenuePaid(cloudXAd: CloudXAd) {
        Log.d("CloudX", "横幅收入: ${cloudXAd.revenue},来自 ${cloudXAd.networkName}")
    }
}
横幅广告默认自动刷新。手动控制刷新:
bannerAd.stopAutoRefresh()  // 停止自动刷新
bannerAd.load()             // 手动加载新广告
bannerAd.startAutoRefresh() // 重新启用自动刷新
可选的广告位和自定义数据用于跟踪:
bannerAd.setPlacement("home_screen")
bannerAd.setCustomData("level:5,coins:100")

MREC 广告 (300x250)

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

    private fun createMrecAd() {
        mrecAd = CloudX.createMREC("your-mrec-ad-unit-id")
        mrecAd.listener = this
        mrecAd.revenueListener = 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.networkName}")
    }

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

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

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

    override fun onAdCollapsed(cloudXAd: CloudXAd) {
        Log.d("CloudX", "MREC 广告已折叠")
    }

    // CloudXAdRevenueListener 回调
    override fun onAdRevenuePaid(cloudXAd: CloudXAd) {
        Log.d("CloudX", "MREC 收入: ${cloudXAd.revenue},来自 ${cloudXAd.networkName}")
    }
}
MREC 广告也默认自动刷新。使用与横幅广告相同的刷新控制方法。

插屏广告

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

    private fun createInterstitialAd() {
        interstitialAd = CloudX.createInterstitial("your-interstitial-ad-unit-id")
        interstitialAd.listener = this
        interstitialAd.revenueListener = this
        interstitialAd.load()
    }

    private fun showInterstitialAd() {
        if (interstitialAd.isAdReady) {
            // 基本展示
            interstitialAd.show(this)

            // 或带有可选的广告位和自定义数据用于跟踪
            // interstitialAd.show(this, "level_complete", "level:5,score:1000")
        } else {
            Log.w("CloudX", "插屏广告尚未准备好")
        }
    }

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

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

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

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

    override fun onAdDisplayFailed(cloudXAd: CloudXAd, 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", "插屏广告被点击")
    }

    // CloudXAdRevenueListener 回调
    override fun onAdRevenuePaid(cloudXAd: CloudXAd) {
        Log.d("CloudX", "插屏收入: ${cloudXAd.revenue},来自 ${cloudXAd.networkName}")
    }
}

激励视频广告

class MainActivity : AppCompatActivity(), CloudXRewardedListener, CloudXAdRevenueListener {
    private lateinit var rewardedAd: CloudXRewardedAd

    private fun createRewardedAd() {
        rewardedAd = CloudX.createRewarded("your-rewarded-ad-unit-id")
        rewardedAd.listener = this
        rewardedAd.revenueListener = this
        rewardedAd.load()
    }

    private fun showRewardedAd() {
        if (rewardedAd.isAdReady) {
            // 基本展示
            rewardedAd.show(this)

            // 或带有可选的广告位和自定义数据用于跟踪
            // rewardedAd.show(this, "bonus_coins", "level:5,coins:100")
        } else {
            Log.w("CloudX", "激励视频广告尚未准备好")
        }
    }

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

    // CloudXRewardedListener 回调
    override fun onAdLoaded(cloudXAd: CloudXAd) {
        Log.d("CloudX", "激励视频广告已加载,来自 ${cloudXAd.networkName}")
    }

    override fun onAdLoadFailed(adUnitId: String, cloudXError: CloudXError) {
        Log.e("CloudX", "激励视频广告加载失败: ${cloudXError.message}")
    }

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

    override fun onAdDisplayFailed(cloudXAd: CloudXAd, cloudXError: CloudXError) {
        Log.e("CloudX", "激励视频广告展示失败: ${cloudXError.message}")
    }

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

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

    override fun onUserRewarded(cloudXAd: CloudXAd, reward: CloudXReward) {
        Log.d("CloudX", "用户获得奖励: ${reward.amount} ${reward.label}")
        // 为用户发放奖励
    }

    // CloudXAdRevenueListener 回调
    override fun onAdRevenuePaid(cloudXAd: CloudXAd) {
        Log.d("CloudX", "激励视频收入: ${cloudXAd.revenue},来自 ${cloudXAd.networkName}")
    }
}

广告信息 (CloudXAd)

CloudXAd 对象在监听器回调中传递,包含已加载/已展示广告的信息:
属性类型描述
adFormatCloudXAdFormat广告格式 (BANNER、MREC、INTERSTITIAL、REWARDED)
adUnitIdString广告单元 ID
networkNameString获胜广告网络的名称
networkPlacementString?网络特定的广告位 ID
placementString?通过 setPlacement() 设置的自定义广告位
revenueDouble展示级收入(以美元计价)
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_ERRORNETWORK_TIMEOUTNETWORK_SERVER_ERRORNETWORK_NO_CONNECTION
200-299初始化NOT_INITIALIZEDSDK_DISABLEDNO_ADAPTERS_FOUNDINVALID_APP_KEY
300-399广告加载NO_FILLINVALID_AD_UNITADS_DISABLED
400-499展示AD_NOT_READYAD_ALREADY_SHOWING
600-699适配器ADAPTER_NO_FILLADAPTER_TIMEOUTADAPTER_LOAD_TIMEOUTADAPTER_INITIALIZATION_ERROR

高级功能

调试日志

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

展示级收入追踪

在任何广告格式上设置 revenueListener 以接收展示级收入 (ILR) 回调。CloudXAd 对象包含以美元计价的收入值和获胜网络名称。
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):检查 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()

技术支持

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