不限制
未配置、待确认或未获得检测结果时放行。
REMAX SDK · EXTERNAL INTEGRATION
面向宿主业务和外部检测 SDK:配置 Ad_Risk_Config、读取设备风险处置策略、限制广告平台,并接收广告收益与点击数据。
以下版本来自当前仓库的发布配置。Risk 不向宿主传递 Bill,外部业务应显式声明三项依赖,避免依赖解析结果不一致。
首次接入请先配置 SDK 与广告依赖 Maven 源、GitHub Packages 下载凭据,并核对 宿主 Manifest 的明文 HTTP 覆盖;这些配置与普通版共用。
// app/build.gradle.kts
dependencies {
implementation("com.github.toukaremax:core:1.0.15")
implementation("com.github.toukaremax:bill:support_risk_1.0.20")
implementation("com.github.toukaremax:ad-risk:1.0.8")
}
support_risk_1.0.20 补齐取消、销毁和遗漏终态的失败埋点;新增补偿不额外触发 onAdShowFailed,原有真实失败通知保留。改道复用入口会话与位置,曝光 / 失败去重,避免迟到回调串到其他请求。
正常加载、竞价、展示、奖励,以及 AdMob 多 ID、REQUEST / SHOW 风控门禁、重新竞价和 MAX 原有回调保持不变。回调 reason 沿用原规则,埋点 reason 独立归类;两者数量与文本不保证一一对应。详见失败回调边界。
474 项 Bill 单元测试与 Release 构建通过;本次未新增真机验证。Core 1.0.15 与 ad-risk 1.0.8 不变。
support_risk_1.0.19 在加载后、选胜出 ID 前重新读取 REQUEST / SHOW 门禁,不增加请求计数。展示风控变化后可重新选择其他有效 ID;竞价模式下 AdMob 平台受限后可回退 MAX 等平台。
重新竞价结果保留 ad_risk_blocked / external_source_show_denied 原因,并由展示入口统一发送一次失败通知。MAX Banner 挂载失败时先清理广告跟踪,再通知宿主,迟到回调不再处理该广告。
support_risk_1.0.19 补齐 REQUEST 门禁拦截全部 ID 时的早退原因(含固定多 ID),保留 ad_risk_blocked;为 support_risk_1.0.18 的补充修复。
保留固定源、单 ID 加载兜底、多 ID 精确消费及全屏原生不接入行为风控的边界。425 项 Bill 单元测试及 Release 构建通过,Maven 产物与公开接口已核验;本次未新增真机验证,Core 与 ad-risk 版本不变。完整八个回调与 extra_info 示例。
support_risk_1.0.17 新增 canSourceShow、onAdBeforeShow、onAdShowFailed,均默认 null,覆盖 AdMob / GAM / Pangle / TopOn / MAX 六类广告。
准入在竞价价格比较阶段按降序询问平台候选,全部拒绝时本轮无胜出者,失败原因是 external_source_show_denied。AdMob 多 ID 传入当前候选的实际广告位及价格,保留缓存与精确消费。固定源快捷路径不触发准入判断。
展示前通知不代表已展示,失败通知沿用会话去重;保留现有风控桥接、关闭和奖励流程。393 项单元测试及 release 构建通过,Maven 产物与公开接口已核验;本次未新增真机验证。Core 与 ad-risk 保持不变。完整八个回调与 extra_info 拼接示例。
support_risk_1.0.16 新增可选 BillConfig.onAdOpened,沿用 RevenueAdData;未监听时不读取新增参数,平台参数读取和宿主回调异常均隔离。
AdMob / GAM / TopOn / Pangle 覆盖六种广告类型。MAX 激励、插页、开屏监听 onAdDisplayed,自定义全屏原生在视图成功绑定后通知;MAX 普通原生与 Banner 不触发,且不使用收益兜底。完整触发函数与参数说明。
保持既有 AdMob 多 ID、风控桥接与回调行为。Core 1.0.15 和 ad-risk 1.0.8 均未修改、未发布。
support_risk_1.0.15 支持开屏、插页、激励、原生和全屏原生的单字符串或多 ID 数组;Banner 保持单字符串。多 ID 并发加载、内部竞价并在消费后定向补充,单 ID 沿用原有链路。
在线参数 adRuntimeIdConfigJson 与代码 AdRuntimeIdConfigManager.updateRuntimeIdConfig(json) 均可更新,支持单 / 多 ID 双向覆盖;配置应用后后续请求生效,无需重启,后台更新不是实时推送。完整配置示例、生效规则与调试日志。
Core、ad-risk、GMA Next-Gen 版本及反射路径保持不变。
support_risk_1.0.14 新增 BillConfig.onAdClose 和 BillConfig.onAdRewardEarned,覆盖 AdMob、GAM、Pangle、TopOn 和 MAX,保留原有风控 CLOSE 分发。完整回调参数与接入示例。
MAX 关闭覆盖开屏、插页、激励、全屏原生页面和 Banner 展开后的收起;普通原生无对应关闭事件。奖励参数来自 MaxReward.label / amount,收益来自当前广告的 MaxAd.revenue(USD)。全局与单次获奖回调都会执行,业务发奖只选择一处。
同步 Google 广告实例收益隔离和 TopOn 统一取值修复。Core 与 ad-risk 版本保持不变。
Bill 自 support_risk_1.0.13 起在 Manifest 中声明 android:usesCleartextTraffic="true",并引用 @xml/remax_bill_network_security_config。随包 XML 通过 <base-config cleartextTrafficPermitted="true" /> 默认允许所有域名的 HTTP 明文流量。
GMA 继续使用普通 ads-mobile-sdk:1.2.1 依赖声明,无严格版本锁定;内部取价与素材反射配置仍只适配 GMA 1.2.1。MAX、普通加载和风控桥接保持原有行为,未引入官方 Preloader 开关。Core 保持 1.0.15,ad-risk 保持 1.0.8,这两个模块本次无需升级。
Bill support_risk_1.0.12 为 AdMob 插页、激励、开屏的展示和点击事件补充 ad_creative_title、ad_creative_description、ad_creative_image_url。按实际取得的非空字段上报,取不到时保留原有事件和内容定向;原生与全屏原生继续使用公开 API。
宿主无需增加配置,Core 与 ad-risk 版本不变,MAX 和风控接口不变。全屏素材依赖已识别的 Google HTML 模板,并非每条广告都能取得三项。查看字段说明、已验证样本及动画 / 视频限制。
远程配置逻辑 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
}
| 字段 | 默认值 / 范围 | 含义 |
|---|---|---|
behavior_mode | 2;0、1、2 | 0 关闭:不计数、不限制、不强关;1 执行:计数、上报并真正应用冷却/强关;2 观察:计数和上报,但不限制、不强关。模式变化会清空行为风控状态。 |
mistake_click_time | 20 秒;整数 ≥ 0 | 点击广告后 App 进程进入后台并返回,耗时小于等于该值时判定为误触。值为 0 不是关闭开关。 |
mistake_click_count | 2;整数 ≥ 0 | 同一“广告类型 + position”的误触累计到第 N 次时触发;0 表示不触发限制,但仍可上报误触事件。 |
restrict_interval | 1800 秒;整数 ≥ 0 | 执行模式下命中阈值后的冷却时长;0 表示冷却立即结束。 |
close_click_count | 3;整数 ≥ 0 | 同一插页广告 session 第 N 次点击时触发;执行模式会强关及冷却,观察模式只计数和上报。仅插页生效,0 表示关闭强关。 |
close_activity_class_names | [];非空字符串数组 | 追加允许 SDK 内置关闭的 Activity 完整类名。命中后在主线程调用 finish();本地默认 AdMob Activity 始终保留。 |
behavior_mode 为 1 或 2。用户未点击广告而直接关闭时,不进入误触判断。
leave_time;若停留时长不超过 mistake_click_time,则判定并上报误触。leave_time=0 结算,并判定、上报误触。<type> 支持 app_open、interstitial、native、banner、rewarded。当前行为风控只处理 AdMob;同类型 position 共用阈值,但分别计数和冷却。
| 字段 | 默认值 | 触发规则 |
|---|---|---|
limits.<type>.request_limit | 0 | 最多允许 N 次业务请求,第 N+1 次触发;0 不限制。预加载不计入业务请求。 |
limits.<type>.show_limit | 0 | 最多允许 N 次实际曝光,第 N+1 次触发;0 不限制。 |
limits.<type>.click_limit | 0 | 最多允许 N 次点击,第 N+1 次触发;0 不限制。 |
limits.<type>.fill_fail_limit | 0 | 连续加载失败到第 N 次时触发,加载成功会清零;0 不限制,预加载结果也参与。 |
| JSON 字段 | AdRisk.signalConfig 属性 | 外部检测场景 |
|---|---|---|
vpn_ad_config | vpnAdConfig | 设备正在使用 VPN |
dns_ad_config | dnsAdConfig | 设备命中 DNS 代理风险 |
ip_ad_config | ipAdConfig | 设备命中异常 IP 风险 |
simulator_ad_config | simulatorAdConfig | 模拟器设备 |
adb_ad_config | adbAdConfig | 设备处于 ADB 调试状态 |
sim_ad_config | simAdConfig | 设备没有 SIM 卡 |
no_gp_ad_config | noGpAdConfig | 设备没有 Google Play |
sys_9_low_ad_config | sys9LowAdConfig | Android 9 以下设备 |
play_ad_config | playAdConfig | 外部 XM SDK 服务端核验结果 |
未配置、待确认或未获得检测结果时放行。
外部检测命中后禁用 AdMob,其他广告平台仍可承接。
外部检测命中后禁用 AdMob、GAM、Pangle、TopOn 和 MAX。
-1 / 0 / 1。远程 JSON 非法时不会部分应用,而是继续使用当前有效配置。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
// 保存最新值,或通知业务重新执行检测处置
}
}
signalConfig 是只读 StateFlow<AdRiskSignalConfig>。初始快照全部为 -1,随后应用缓存 / Assets,并可能被远程配置更新;需要跟随在线配置时不要只读取一次。外部检测确认设备正在使用 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 解除本业务设置的限制;存在多项风险时,应在所有相关风险都解除后再清除。
| Scope | 保存方式 | 自动失效 | 主动清除 |
|---|---|---|---|
AdRestrictionScope.PROCESS | 仅内存 | 当前应用进程结束 | 同一平台和 Scope 再传 restricted=false |
AdRestrictionScope.TODAY | 本地持久化 | 设备本地自然日变化 | 同一平台和 Scope 再传 restricted=false |
PROCESS 与 TODAY 独立;只清除其中一个,另一个仍会继续限制。ADMOB、GAM、PANGLE、TOPON、MAX。updatePlatformRestriction 返回 false 表示 Risk 尚未完成自动初始化,本次没有应用;应稍后重试。behavior_mode、行为计数和广告位冷却相互独立。当前 Risk 版通过 BillConfig 提供八个可选全局回调,广告数据均沿用 RevenueAdData;获奖和失败回调另有奖励与原因参数。建议合并到初始化配置块中注册。下方展示收益和点击接入,完整八个回调及 extra_info 拼接示例见接入指南第 4 步。
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
| 字段 | 类型 | 含义 / 可能值 |
|---|---|---|
revenue.value | Double | 单次展示收益金额;点击回调携带当前广告已知的收益值,平台未提供时可能为 0。 |
revenue.currencyCode | String | 货币代码,通常为 USD;SDK 不做汇率换算,使用金额前应同时检查该字段。 |
platform | String | 聚合平台:Admob、GAM、Pangle、TopOn、MAX。 |
adRevenueNetwork | String | 实际广告网络 / 底层广告源名称;拿不到时回退为聚合平台名称。 |
adRevenueUnit | String | 本次请求使用的聚合广告位 ID(Ad Unit / Placement ID)。 |
adSourceId | String | 底层广告源或实例 ID;拿不到时回退为 adRevenueUnit。 |
adRevenuePlacement | String | 平台提供的 placement、scenario 或实例名称;平台未提供时可能为空字符串。 |
adFormat | String | Splash、Interstitial、Native、Banner、FullNative、Rewarded。 |
BillConfig.onAdRevenue 或 BillConfig.onAdClick 赋值会替换之前的回调。通过 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 或 MAX
AdSourceController.setCurrentSource(AdSource.ADMOB)
// 读取当前设置
val currentSource = AdSourceController.getCurrentSource()
// BIDDING 为默认模式:由 Bill 在所有可用平台中竞价选择
AdSourceController.setCurrentSource(AdSource.BIDDING)
| AdSource | 行为 |
|---|---|
ADMOB | 固定使用 AdMob |
GAM | 固定使用 Google Ad Manager |
PANGLE | 固定使用 Pangle |
TOPON | 固定使用 TopOn |
MAX | 固定使用 AppLovin MAX |
BIDDING | 恢复默认竞价模式,由可用平台参与选择 |
AdSource.BIDDING。