广告风控外部业务对接指南

1. core、bill、risk 最新依赖

以下版本来自当前仓库的发布配置。Risk 不向宿主传递 Bill，外部业务应显式声明三项依赖，避免依赖解析结果不一致。

模块依赖

// app/build.gradle.kts
dependencies {
    implementation("com.github.toukaremax:core:1.0.15")
    implementation("com.github.toukaremax:bill:support_risk_1.0.9")
    implementation("com.github.toukaremax:ad-risk:1.0.8")
}

2. Ad_Risk_Config 在线参数（SDK 内部获取）

远程配置逻辑 Key 固定为 Ad_Risk_Config。设备环境处置字段与行为风控字段放在同一份扁平 JSON 中。SDK 启动时先使用缓存、Assets 或硬编码默认值，再异步拉取远程配置；合法的远程配置会即时生效并写入缓存。

完整配置示例

{
  "behavior_mode": 2,
  "mistake_click_time": 20,
  "mistake_click_count": 2,
  "restrict_interval": 1800,
  "close_click_count": 3,
  "close_activity_class_names": [],
  "limits": {
    "app_open":     { "request_limit": 0, "show_limit": 0, "click_limit": 0, "fill_fail_limit": 0 },
    "interstitial": { "request_limit": 0, "show_limit": 0, "click_limit": 0, "fill_fail_limit": 0 },
    "native":       { "request_limit": 0, "show_limit": 0, "click_limit": 0, "fill_fail_limit": 0 },
    "banner":       { "request_limit": 0, "show_limit": 0, "click_limit": 0, "fill_fail_limit": 0 },
    "rewarded":     { "request_limit": 0, "show_limit": 0, "click_limit": 0, "fill_fail_limit": 0 }
  },
  "vpn_ad_config": -1,
  "dns_ad_config": -1,
  "ip_ad_config": -1,
  "simulator_ad_config": -1,
  "adb_ad_config": -1,
  "sim_ad_config": -1,
  "no_gp_ad_config": -1,
  "sys_9_low_ad_config": -1,
  "play_ad_config": -1
}

行为风控字段

误触风控的生效场景

各广告类型的 limits

<type> 支持 app_open、interstitial、native、banner、rewarded。当前行为风控只处理 AdMob；同类型 position 共用阈值，但分别计数和冷却。

设备环境处置字段

3. 获取 signalConfig，并配合外部检测禁用平台（按项目可选）

读取当前值或持续监听

import com.android.common.risk.AdRisk
import kotlinx.coroutines.flow.collectLatest

// 同步读取当前完整快照
val current = AdRisk.signalConfig.value
val vpnPolicy = current.vpnAdConfig

// 推荐：监听缓存、Assets 和在线配置的后续变化
applicationScope.launch {
    AdRisk.signalConfig.collectLatest { config ->
        val latestVpnPolicy = config.vpnAdConfig
        // 保存最新值，或通知业务重新执行检测处置
    }
}

处置示例：检测到 VPN

外部检测确认设备正在使用 VPN 后，只需读取 vpnAdConfig 并按值处理：

import com.android.common.bill.ads.config.AdPlatform
import com.android.common.risk.AdRestrictionScope
import com.android.common.risk.AdRisk
import com.android.common.risk.AdRiskSignalConfig

if (vpnDetected) {
    when (AdRisk.signalConfig.value.vpnAdConfig) {
        AdRiskSignalConfig.BLOCK_ADMOB -> {
            // 0：只禁用 AdMob
            AdRisk.updatePlatformRestriction(
                AdPlatform.ADMOB,
                AdRestrictionScope.PROCESS,
                true
            )
        }

        AdRiskSignalConfig.BLOCK_ALL_ADS -> {
            // 1：禁用全部广告平台
            AdPlatform.entries.forEach { platform ->
                AdRisk.updatePlatformRestriction(
                    platform,
                    AdRestrictionScope.PROCESS,
                    true
                )
            }
        }

        AdRiskSignalConfig.NOT_CONFIGURED -> Unit // -1：不处理
    }
}

DNS、异常 IP、模拟器等检测的处理方式完全相同，只需把 vpnAdConfig 换成对应的配置字段。检测状态恢复正常后，用相同平台和 Scope 调用 restricted=false 解除本业务设置的限制；存在多项风险时，应在所有相关风险都解除后再清除。

限制生命周期

• PROCESS 与 TODAY 独立；只清除其中一个，另一个仍会继续限制。
• 支持的平台为 ADMOB、GAM、PANGLE、TOPON。
• updatePlatformRestriction 返回 false 表示 Risk 尚未完成自动初始化，本次没有应用；应稍后重试。
• 平台限制与 behavior_mode、行为计数和广告位冷却相互独立。

4. 广告收益与点击回调

广告库通过 BillConfig 暴露两个可选回调，参数类型均为 RevenueAdData。建议在 Application.onCreate() 中完成赋值。

注册回调

import com.android.common.bill.BillConfig

BillConfig.onAdRevenue = { data ->
    // 每次广告展示产生收益时回调（impression 级）
    analytics.logAdRevenue(
        value = data.revenue.value,
        currency = data.revenue.currencyCode,
        platform = data.platform,
        network = data.adRevenueNetwork,
        adUnitId = data.adRevenueUnit,
        adSourceId = data.adSourceId,
        placement = data.adRevenuePlacement,
        format = data.adFormat
    )
}

BillConfig.onAdClick = { data ->
    // 用户点击广告时回调
    analytics.logAdClick(
        platform = data.platform,
        network = data.adRevenueNetwork,
        adUnitId = data.adRevenueUnit,
        adSourceId = data.adSourceId,
        placement = data.adRevenuePlacement,
        format = data.adFormat,
        value = data.revenue.value,
        currency = data.revenue.currencyCode
    )
}

// 不再接收时可清除
// BillConfig.onAdRevenue = null
// BillConfig.onAdClick = null

RevenueAdData 可获取的参数

5. Bill 设置固定广告源 (用于调试工具)

通过 AdSourceController.setCurrentSource(...) 设置 Bill 当前使用的聚合平台。建议在 Application.onCreate() 中、首次广告请求之前完成设置。

固定为指定平台

import com.android.common.bill.ads.bidding.AdSourceController
import com.android.common.bill.ads.bidding.AdSourceController.AdSource

// 固定使用 AdMob；也可改为 GAM、PANGLE 或 TOPON
AdSourceController.setCurrentSource(AdSource.ADMOB)

// 读取当前设置
val currentSource = AdSourceController.getCurrentSource()

恢复为竞价模式

// BIDDING 为默认模式：由 Bill 在所有可用平台中竞价选择
AdSourceController.setCurrentSource(AdSource.BIDDING)