REMAX SDK · ADRISK

外部接入 API

读取设备环境处置配置，结合宿主的设备检测结果，按平台设置当前进程或当日广告限制。

配置来源 Ad_Risk_Config
公开入口 AdRisk

职责边界

Risk

提供配置

解析缓存、assets 与远程 JSON，通过只读 StateFlow 提供完整快照。

外部 SDK / 宿主

检测并决策

检测 VPN、模拟器等设备状态，并把检测结果与配置值组合。

Bill

执行平台门禁

统一平台可用性检查会排除被限制的平台；其他平台仍可正常承接。

Ad_Risk_Config→ AdRisk.signalConfig+ 外部设备检测→ updatePlatformRestriction→ Bill 平台门禁

保持独立：平台限制不读写原有 AdMob 点击计数、广告位冷却或 behavior_mode；配置 Flow 本身也不会自动限制广告。

AdRisk.signalConfig

AdRisk.signalConfig 是只读 StateFlow<AdRiskSignalConfig>，每个快照会一次性包含下列九项设备环境处置配置。直接读取适合获取当前值；collect 适合感知缓存、assets 或在线配置更新。

import com.android.common.risk.AdRisk

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

// 持续感知配置更新
applicationScope.launch {
    AdRisk.signalConfig.collectLatest { config ->
        val latestVpnConfig = config.vpnAdConfig
    }
}

StateFlow 创建时的初始值是全部 -1。Risk 初始化后会依次应用当前有效缓存 / assets，随后可能异步应用远程配置。只读取一次可能拿到较早的快照；需要跟随在线配置时应使用 collect。

可以获取到什么

Kotlin 属性	JSON 字段	对应的设备情况	默认值 / 合法范围
`vpnAdConfig`	`vpn_ad_config`	VPN 用户	-1；只能为 -1、0、1
`dnsAdConfig`	`dns_ad_config`	DNS 代理用户	-1；只能为 -1、0、1
`ipAdConfig`	`ip_ad_config`	异常 IP 用户	-1；只能为 -1、0、1
`simulatorAdConfig`	`simulator_ad_config`	模拟器用户	-1；只能为 -1、0、1
`adbAdConfig`	`adb_ad_config`	设备处于 ADB 调试状态	-1；只能为 -1、0、1
`simAdConfig`	`sim_ad_config`	设备没有 SIM 卡	-1；只能为 -1、0、1
`noGpAdConfig`	`no_gp_ad_config`	设备没有 Google Play	-1；只能为 -1、0、1
`sys9LowAdConfig`	`sys_9_low_ad_config`	Android 9 以下设备	-1；只能为 -1、0、1
`playAdConfig`	`play_ad_config`	XM SDK 服务端核验结果	-1；只能为 -1、0、1

NOT_CONFIGURED

-1 · 不限制

待确认、未获取或配置未启用时放行。

BLOCK_ADMOB

0 · 限制 AdMob

外部命中对应设备风险后，仅限制 AdMob。

BLOCK_ALL_ADS

1 · 限制全部平台

外部命中对应设备风险后，逐个平台设置限制。

设置或清除平台限制

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

// 当前进程限制 AdMob
AdRisk.updatePlatformRestriction(
    platform = AdPlatform.ADMOB,
    scope = AdRestrictionScope.PROCESS,
    restricted = true
)

// 清除同一平台、同一范围的限制
AdRisk.updatePlatformRestriction(
    platform = AdPlatform.ADMOB,
    scope = AdRestrictionScope.PROCESS,
    restricted = false
)

// 当日限制全部平台
AdPlatform.entries.forEach { platform ->
    AdRisk.updatePlatformRestriction(platform, AdRestrictionScope.TODAY, true)
}

Scope	存储	失效时间	清除方式
`PROCESS`	仅内存	当前应用进程结束	同平台、同 Scope 传 `restricted=false`
`TODAY`	本地持久化	设备本地自然日变化	同平台、同 Scope 传 `restricted=false`

PROCESS 与 TODAY 独立保存。清除其中一个不会清除另一个。函数返回 false 表示 Risk 尚未完成自动初始化；建议在 Application.onCreate() 或更晚调用，并检查返回值。

日志与展示失败埋点

设置、清除和平台门禁拒绝均输出 [AdRisk][Policy] 日志，包含平台、Scope 和最终状态。
某个平台被限制但其他平台成功承接时，不会上报展示失败。
最终没有任何平台可展示，且至少一个配置启用的平台被门禁限制时，上报 ad_show_fail，reason 为 risk_restricted。
没有平台限制导致的普通无广告，继续使用 no_platform_available_after_exclusion。

不会改变：原有 Ad_Behavior_Restricted、ad_risk_blocked、点击计数和广告位冷却逻辑保持独立。