通用广告聚合与展示,按业务选择默认版或专用混淆变体。
LCB / IAA 当前仍为 1.0.54;具体能力差异见下表。
查看接入说明 →添加依赖 → 配置日志与渠道 → 初始化广告源 → 注册回调 → 授权与预加载 → 展示广告。
添加 Core,并按业务选择一个 Bill 版本。同一 App 不要同时依赖多个 Bill 版本。
通用广告聚合与展示,按业务选择默认版或专用混淆变体。
LCB / IAA 当前仍为 1.0.54;具体能力差异见下表。
查看接入说明 →支持 Google 官方预加载、在线缓存容量配置与 AdMob 内容定向。
默认版已补齐失败埋点;Drama 保持 .11,本次未发布。
查看接入说明 →支持 AdMob 多 ID、MAX 聚合,可按需接入风控插件。
Bill 可独立使用;引入 ad-risk 后启用风控能力。
查看接入说明 →com.github.toukaremax:core:1.0.15搭配任一 Bill 版本每列一个已发布版本,每行一项能力。按需求横向选择,点击能力名称查看接入说明。
| 能力 / 当前版本下方按钮复制 Bill 坐标 | 普通主线DEFAULT1.0.58近期更新 ↓ |
普通主线 · 混淆变体LCB1.0.54.lcb近期更新 ↓ |
普通主线 · 混淆变体IAA1.0.54.iaa近期更新 ↓ |
预加载 · 默认PRELOADING1.0.58_preloading.14近期更新 ↓ |
预加载 · 短剧DRAMA1.0.56_preloading.11.drama近期更新 ↓ |
风控分支RISKsupport_risk_1.0.20近期更新 ↓ |
|---|---|---|---|---|---|---|
| AdMob 多 ID五种类型 · Banner 除外 | — | — | — | — | — | ✓ |
| Google 官方预加载在线切换模式与缓存容量 | — | — | — | ✓ | ✓ | — |
| AdMob 内容定向关键词组与内容 URL | — | — | — | ✓ | ✓ | ✓ |
| 全屏广告素材字段标题 / 描述 / 主图 · 尽力提取 | — | — | — | ✓ | ✓ | ✓ |
| AppLovin MAX内置六种广告类型 | — | — | — | — | — | ✓ |
| AdMob 行为风控需额外接入 ad-risk | — | — | — | — | — | ✓可选 · ad-risk |
| 竞价候选准入canSourceShow | ✓ | — | — | ✓ | — | ✓ |
| 调用展示前通知onAdBeforeShow | ✓ | — | — | ✓ | — | ✓ |
| 全局展示失败回调onAdShowFailed | ✓ | — | — | ✓ | — | ✓ |
| 广告开始展示回调onAdOpened | ✓ | — | — | ✓ | ✓ | ✓MAX 除普通原生 / Banner |
| 全局关闭 / 获奖回调onAdClose / onAdRewardEarned | ✓ | — | — | ✓ | ✓ | ✓ |
| 固定源不可用时回退竞价Risk 严格使用固定源 | ✓ | ✓ | ✓ | ✓ | ✓ | — |
| 内部混淆方式不改变公开 API | R8 默认 | LCB 字典 | IAA 字典 | R8 默认 | Drama 字典 | R8 默认 |
| 四个平台基础聚合AdMob / GAM / Pangle / TopOn | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 在线单 ID 配置覆盖宿主注入的广告位 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 主动预加载 APIPreloadController 提前加载 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 全局收益 / 点击回调onAdRevenue / onAdClick | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
按产品线保留最近 4–5 个版本,展开查看逐版变更。范围以各行说明为准,升级时选择该产品线的当前版本。
1.0.58补齐失败埋点并隔离补偿回调| 版本 | 主要修改 | 适用范围 |
|---|---|---|
1.0.58当前版本 | 补齐取消、销毁及遗漏终态的失败埋点;新增补偿只上报,不额外通知宿主。改道复用会话,按请求去重,保留正常加载、竞价、展示和奖励。 | 仅 default |
1.0.57 | 新增竞价准入 canSourceShow、展示前 onAdBeforeShow、失败 onAdShowFailed 三个可选回调;全部候选拒绝时结束展示。 | 仅 default |
1.0.56 | 新增开始展示回调 onAdOpened;隔离参数读取和宿主回调异常,补齐 AdType.fromConfigKey() 混淆保护。 | 仅 default |
1.0.55 | 新增关闭、激励获奖回调;Google 收益按广告实例隔离,统一 TopOn 收益取值。 | 仅 default |
1.0.54 | 默认允许 HTTP 明文流量,随包提供网络安全配置;宿主已有配置时需处理 Manifest 合并。 | default;LCB / IAA 当前基线 |
LCB / IAA 当前仍为 1.0.54.lcb / 1.0.54.iaa,尚未包含 default 1.0.55–1.0.57 的新增回调及 1.0.58 埋点修复。
1.0.58_preloading.14补齐会话终态,避免重复与串报| 版本 | 主要修改 | 适用范围 |
|---|---|---|
1.0.58_preloading.14当前版本 | 补齐取消、销毁及遗漏终态的失败埋点;新增补偿只上报,不额外通知宿主。改道复用会话,按请求去重,保留正常加载、竞价、展示和奖励。 | 仅 default |
1.0.57_preloading.13 | 修复主广告无库存、插屏准入全部拒绝时的错误改道;确认准入判断不消耗 AdMob / GAM 预加载缓存。 | 仅 default |
1.0.57_preloading.12 | 迁移竞价准入、展示前和失败三个回调;保留官方预加载与有效库存筛选,全部拒绝不回退 AdMob。 | 仅 default |
1.0.56_preloading.11 | 新增开始展示回调 onAdOpened,隔离参数读取和宿主异常;保留预加载与素材 / 内容定向。 | default + Drama |
1.0.55_preloading.10 | 新增关闭、激励获奖回调及 Google 广告实例收益隔离;保留预加载模式与 AdMob 内容定向。 | default + Drama |
表中版本号为 default 坐标。标注 Drama 的版本另有 .drama 后缀;Drama 当前为 1.0.56_preloading.11.drama,未发布 .12 / .13 / .14,也不包含本次埋点修复。
support_risk_1.0.20同步埋点修复,保留风控与 MAX| 版本 | 主要修改 | 适用范围 |
|---|---|---|
support_risk_1.0.20当前版本 | 补齐取消、销毁及遗漏终态的失败埋点;新增补偿只上报,不额外通知宿主。改道复用会话,按请求去重,保留正常加载、竞价、展示和奖励。保留多 ID、风控重选和 MAX 原有回调。 | Bill;Core / ad-risk 不变 |
support_risk_1.0.19 | 补齐 REQUEST 风控拦截全部 AdMob ID 时的失败原因,包括固定多 ID 路径;准确返回 ad_risk_blocked。 | Bill;Core / ad-risk 不变 |
support_risk_1.0.18 | 选 ID 前检查 REQUEST / SHOW 门禁,避免重新选中受限 ID;保留重新竞价的失败原因。竞价模式下 AdMob 胜出后平台不可用,可再竞价一次选择 MAX 等可用平台。MAX Banner 挂载失败后清理广告和跟踪。 | Bill;固定源不自动换平台 |
support_risk_1.0.17 | 迁移竞价准入、展示前和失败三个回调,覆盖含 MAX 在内的五个平台;多 ID 回调使用实际候选广告位。 | Bill;保留多 ID 与风控 |
support_risk_1.0.16 | 新增开始展示回调 onAdOpened;MAX 普通原生与 Banner 不以收益事件补发开始展示。 | Bill;保留原有回调 |
当前 .20 包含 .19 / .18 的兼容性修复。Core 保持 1.0.15,可选风控插件 ad-risk 保持 1.0.8。
基础要求:Android minSdk 26、Java / JVM 17;SDK 源码使用 compileSdk 36。先配置 Maven 源与下载凭据,再添加 Core 和一个 Bill 版本,最后检查宿主清单的 HTTP 配置。
以下配置参考 short-drama/settings.gradle.kts(2026-11-17)。合并到项目根目录的 settings.gradle.kts:依赖源放在 dependencyResolutionManagement.repositories,已有的 pluginManagement 保留;不要重复创建配置块。使用 FAIL_ON_PROJECT_REPOS 时,不要再在 app 模块声明仓库。
dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
repositories {
google()
mavenCentral()
// Chartboost 及其 OM SDK 仅从以下官方源解析,避免第三方镜像返回错误产物。
exclusiveContent {
forRepositories(
maven {
name = "ChartboostAds"
url = uri("https://cboost.jfrog.io/artifactory/chartboost-ads/")
},
maven {
name = "ChartboostMediation"
url = uri("https://cboost.jfrog.io/artifactory/chartboost-mediation/")
},
maven {
name = "ChartboostCore"
url = uri("https://cboost.jfrog.io/artifactory/chartboost-core/")
},
)
filter {
includeGroup("com.chartboost")
includeModule("com.iab.omid.library", "chartboost-omsdk-android")
}
}
maven {
setUrl("https://artifact.bytedance.com/repository/pangle")
}
maven {
setUrl("https://dl-maven-android.mintegral.com/repository/mbridge_android_sdk_oversea")
}
maven {
setUrl("https://jfrog.anythinktech.com/artifactory/overseas_sdk")
}
maven {
setUrl("https://android-sdk.is.com/")
}
maven("https://jitpack.io")
maven("https://repo.dgtverse.cn/repository/maven-public")
maven("https://maven.aliyun.com/nexus/content/groups/public/")
maven("https://maven.aliyun.com/nexus/content/repositories/jcenter")
maven("https://maven.aliyun.com/nexus/content/repositories/google")
maven("https://maven.aliyun.com/nexus/content/repositories/gradle-plugin")
maven {
name = "GitHubPackages"
url = uri("https://maven.pkg.github.com/toukaRemax/remax_sdk")
val localProperties = java.util.Properties()
val localPropertiesFile = rootDir.resolve("local.properties")
if (localPropertiesFile.exists()) {
localPropertiesFile.inputStream().use(localProperties::load)
}
val remaxSdkPassword = providers.environmentVariable("REMAX_SDK_TOKEN")
.orElse(providers.provider { localProperties.getProperty("REMAX_SDK_TOKEN") ?: "" })
.get()
credentials {
username = providers.environmentVariable("REMAX_SDK_USER")
.orElse(providers.provider { localProperties.getProperty("REMAX_SDK_USER") ?: "toukaRemax" })
.get()
password = remaxSdkPassword
}
}
}
}
GitHub Packages 是 ReMax 的包源;Pangle、Mintegral、TopOn、ironSource 和 Chartboost 使用各自的广告依赖源。Chartboost 的 exclusiveContent 同时限定 com.chartboost 与 com.iab.omid.library:chartboost-omsdk-android,应保留完整配置。JitPack、DGTVerse 与阿里云条目沿用参考项目的其他依赖 / 镜像源,可按宿主实际依赖保留。
使用具备目标包读取权限的 GitHub 账号和 Personal access token(classic,包含 read:packages)。示例优先读取环境变量,再读取根目录 local.properties;用户名默认沿用参考项目的 toukaRemax,使用个人 Token 时将 REMAX_SDK_USER 改为 Token 所属账号。
# 根目录 local.properties(占位值请替换为自己的凭据)
REMAX_SDK_USER=YOUR_GITHUB_USERNAME
REMAX_SDK_TOKEN=YOUR_READ_PACKAGES_TOKEN
本地配置应加入 Git 忽略;CI 使用 Secret 注入同名环境变量,不提交真实 Token。凭据仅用于 Gradle 下载依赖,广告展示接口无需传入。鉴权失败时检查账号、Token 的 read:packages 权限与包访问权限。参考 GitHub Packages Gradle 鉴权说明。
// app/build.gradle.kts → dependencies
implementation("com.github.toukaremax:core:1.0.15")
// 与 short-drama 当前依赖一致:默认预加载版本;Bill 只选一个
implementation("com.github.toukaremax:bill:1.0.58_preloading.14")
参考项目当前使用默认预加载版本;如需 Drama 版本,改为 1.0.56_preloading.11.drama,其他产品线见依赖版本。
参考 short-drama/app/src/main/AndroidManifest.xml,在宿主的 <application> 显式设置 android:usesCleartextTraffic="true",并用 tools:replace 覆盖依赖清单中的同名属性。根节点需声明 xmlns:tools。
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:tools="http://schemas.android.com/tools">
<uses-permission android:name="android.permission.INTERNET" />
<application
android:usesCleartextTraffic="true"
tools:replace="android:usesCleartextTraffic">
<!-- 保留宿主已有属性、组件和 AdMob meta-data -->
</application>
</manifest>
合并到已有清单,不要替换整个文件。如果已有 tools:replace,在原列表中追加 android:usesCleartextTraffic;例如参考项目保留 android:allowBackup="false",对应列表为 tools:replace="android:allowBackup,android:usesCleartextTraffic"。allowBackup 是宿主自身策略,无需为接入 SDK 额外修改。
Android 7.0+ 存在 android:networkSecurityConfig 时,明文访问以最终 XML 为准,仅覆盖 usesCleartextTraffic 不会覆盖 XML 中的禁止规则。当前 Bill 随包配置默认允许 HTTP;宿主使用自定义 XML 时,应在其中为所需范围设置 cleartextTrafficPermitted="true",并处理 networkSecurityConfig 合并冲突。查看版本范围及自定义 XML 合并示例。
配置完成后,在 Android Studio 的 Merged Manifest 中核对 usesCleartextTraffic 与最终 networkSecurityConfig 引用,并检查对应 XML。该策略作用于整个宿主 App,HTTPS 请求仍走 HTTPS。参考 Android 明文流量属性说明。
所有版本均使用 com.github.toukaremax:bill,产品线只体现在版本后缀中;Core 统一使用 com.github.toukaremax:core:1.0.15。同一 App 只依赖一个 Bill 版本。
同一基础版本的产品线后缀只改变 Bill 内部混淆命名,不改变公开 API 或业务逻辑。1.0.58 与 1.0.58_preloading.14 属于不同业务分支,预加载能力存在差异;当前 Drama 仍为 1.0.56_preloading.11.drama,尚未包含竞价准入、展示前和失败三个回调及本次埋点修复。
Risk 是独立的风控接入分支,需同时声明 Bill 和 ad-risk,Risk 通过 Provider 自动初始化;不是普通版的混淆字典变体。下面的通用接入说明请结合 Risk 业务接入指南 使用。
Risk 不会传递依赖 Bill,需要显式声明以下依赖,并按 Risk 接入指南 配置风控策略。
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")1.0.58、默认预加载版 1.0.58_preloading.14 和 Risk support_risk_1.0.20。普通版与预加载版本次只发布 default;Drama、LCB / IAA、Core 1.0.15 和 ad-risk 1.0.8 保持不变。ad_show_fail,不额外触发 onAdShowFailed。原有真实失败通知、正常加载、竞价、展示与奖励发放保留。ad_format,宿主回调仍使用实际广告类型。广告实例与页面请求分开归因,避免迟到回调串报。ad_position 尽可能对应一次 ad_impression 或 ad_show_fail;埋点与宿主失败回调不保证一一对应。进程退出、上报丢失或仍未结束的请求不保证实时严格相等。1.0.57_preloading.13 与 Risk support_risk_1.0.19;当前版本已包含这些修复。NONE 误当作可改道结果的问题。确认准入判断不会取走或清空 AdMob / GAM 官方预加载队列,后续放行仍可使用原库存。support_risk_1.0.19 另补齐 REQUEST 门禁拦截全部 ID 时的早退原因,包括固定多 ID 路径;这是已发布 support_risk_1.0.18 的补充修复。此时保留 ad_risk_blocked,不误报无平台或宿主拒绝。1.0.57_preloading.12 与 Risk support_risk_1.0.17;均支持 canSourceShow、onAdBeforeShow、onAdShowFailed。三个接口默认 null。1.0.56_preloading.11.drama。普通版 1.0.57、LCB / IAA 1.0.54、Core 1.0.15 和 ad-risk 1.0.8 保持不变。com.github.toukaremax:bill:1.0.57,继续搭配 core:1.0.15。Preloading、Drama、Risk、LCB、IAA 和 ad-risk 的版本保持不变。canSourceShow:六种类型内部竞价按价格从高到低依次询问候选,返回 true 选中,false 继续下一平台;全部拒绝返回 BiddingWinner.NONE,不回退 AdMob。onAdBeforeShow 与 onAdShowFailed,分别对接调用展示前通知和展示会话失败。三个回调均默认 null,未配置时保持原有流程。implementation("com.github.toukaremax:core:1.0.15")
implementation("com.github.toukaremax:bill:1.0.58")1.0.56、默认预加载版 1.0.56_preloading.11、Drama 1.0.56_preloading.11.drama、Risk support_risk_1.0.16。BillConfig.onAdOpened。未配置时不执行新增参数读取;平台 getter 与宿主回调异常均隔离,读取失败仍携带基础广告信息通知。1.0.54.lcb / 1.0.54.iaa,未发布升级。Core 1.0.15 与 ad-risk 1.0.8 均未修改、未发布。support_risk_1.0.15:AdMob 开屏、插页、激励、原生及全屏原生支持单字符串或多 ID 数组;Banner 继续使用单字符串。1.0.15、ad-risk 1.0.8 保持不变;GMA Next-Gen 与反射配置仍为 1.2.1。1.0.55、默认预加载版 1.0.55_preloading.10、Drama 1.0.55_preloading.10.drama、Risk support_risk_1.0.14。BillConfig.onAdClose 和 BillConfig.onAdRewardEarned;修复 Google 预加载 / 交错事件的广告来源与收益串值,统一 TopOn 各事件收益取值。Risk 同步适配 MAX 并保留风控 CLOSE 事件。1.0.54.lcb / 1.0.54.iaa,本次未发布升级,尚不包含新增的两个全局回调。Core 1.0.15、ad-risk 1.0.8 保持不变。1.0.54、LCB 1.0.54.lcb、IAA 1.0.54.iaa、默认预加载版 1.0.54_preloading.9、短剧预加载版 1.0.54_preloading.9.drama、Risk 版 support_risk_1.0.13;Core 保持 1.0.15,ad-risk 保持 1.0.8。android:usesCleartextTraffic="true",并引用 @xml/remax_bill_network_security_config,其中 <base-config cleartextTrafficPermitted="true" /> 默认允许所有域名的 HTTP 明文流量。strictly(1.2.1),仍声明 ads-mobile-sdk:1.2.1 和 TopOn adapter-tpn-gma-next-gen:1.2.1.1.0,允许 Gradle 按依赖解析规则选择其他版本。现有内部取价与素材反射配置只适配 GMA 1.2.1;取消锁定不代表其他版本已验证兼容。support_risk_1.0.13 同步以上明文流量配置,继续使用普通 GMA 1.2.1 依赖声明,无严格版本锁定;保留 MAX、普通加载和风控桥接,不引入官方 Preloader 开关。Android 7.0 及以上设置了 networkSecurityConfig 后,以最终选中的 XML 为准。若宿主已有不同的网络配置引用或显式关闭明文流量,可能出现 Manifest 合并冲突;不同 XML 的内容不会自动拼接。宿主需要明确选择最终策略,并在自己的 XML 中配置允许明文的范围。
若要保留宿主自己的 @xml/app_network_security_config,并允许明文流量,可在宿主的 Manifest 中显式覆盖下面两项属性。将已有的 tools:replace 列表合并保留;XML 文件名请替换成项目实际名称。
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:tools="http://schemas.android.com/tools">
<application
android:networkSecurityConfig="@xml/app_network_security_config"
android:usesCleartextTraffic="true"
tools:replace="android:networkSecurityConfig,android:usesCleartextTraffic">
<!-- 保留宿主已有组件 -->
</application>
</manifest>
在宿主已有的 XML 中,将 base-config 的 cleartextTrafficPermitted 设为 true,或仅为所需域名设置允许明文的 domain-config;保留已有证书、信任锚及域名规则。显式的域名规则仍可覆盖全局默认值。若宿主要继续禁止明文,请同时保留对应的 Manifest 与 XML 禁止策略。
最终在 Android Studio 的 Merged Manifest 中确认属性指向,并检查实际选中的 XML。参考 Android 网络安全配置。
1.0.53、默认预加载版 1.0.52_preloading.8、短剧版 1.0.52_preloading.8.drama;Core 保持 1.0.15。ad_bid_excluded,reason=external_ad_blocked,同次竞价每个平台只上报一次;全部候选被封时通过 ad_show_fail 记录原因。1.0.52_preloading.7、短剧版 1.0.52_preloading.7.drama、Risk 版 support_risk_1.0.12;Core 仍为 1.0.15,ad-risk 仍为 1.0.8。implementation("com.github.toukaremax:core:1.0.15")
implementation("com.github.toukaremax:bill:1.0.58_preloading.14")LCB:
implementation("com.github.toukaremax:core:1.0.15")
implementation("com.github.toukaremax:bill:1.0.54.lcb")
IAA:
implementation("com.github.toukaremax:core:1.0.15")
implementation("com.github.toukaremax:bill:1.0.54.iaa")// 同样放在 dependencyResolutionManagement.repositories 中
google()
mavenCentral()
maven { url = uri("https://jitpack.io") }
maven { url = uri("https://artifact.bytedance.com/repository/pangle/") }
maven { url = uri("https://dl-maven-android.mintegral.com/repository/mbridge_android_sdk_oversea") }
maven { url = uri("https://android-sdk.is.com/") }
maven { url = uri("https://jfrog.anythinktech.com/artifactory/overseas_sdk") }
maven { url = uri("https://cboost.jfrog.io/artifactory/chartboost-ads/") }
maven { url = uri("https://cboost.jfrog.io/artifactory/chartboost-mediation") }
maven { url = uri("https://cboost.jfrog.io/artifactory/chartboost-core") }使用在线广告配置时,宿主需配置自己的 Firebase 项目(google-services.json 和 Google Services Gradle 插件,或自行初始化 FirebaseApp)。
在 Application.attachBaseContext 的 super 调用后设置,早于广告初始化。
import com.android.common.bill.ads.log.AdLogger
import net.corekit.core.log.CoreLogger
import net.corekit.core.controller.ChannelUserController
CoreLogger.setLogEnabled(BuildConfig.DEBUG)
AdLogger.setLogEnabled(BuildConfig.DEBUG)
ChannelUserController.setDefaultChannel("natural") // natural / paid
// 得到用户归因结果后再调用;不要每次启动强制覆盖。
ChannelUserController.setChannel(ChannelUserController.UserChannelType.PAID)
val channel = ChannelUserController.getCurrentChannel()setDefaultChannel 设置未归因时的默认值;setChannel 受首次设置状态约束。渠道决定使用自然 / 买量广告策略。
在主进程协程中调用一次,等待返回后再预加载或展示。下面按已有接入方式列出四个平台;用实际 ID / Key 替换占位符,仅填写接入的平台与广告类型。
import com.android.common.bill.BillConfig
import com.android.common.bill.ads.bidding.AppOpenBiddingInitializer
// suspend 代码;context 为宿主 Context,图标使用宿主资源。
AppOpenBiddingInitializer.initialize(context, R.mipmap.ic_launcher) {
externallyInitialized = false // 让库初始化平台 SDK
skipRuntimeAdIdConfig = false // 保留在线 ID 覆盖;仅用本地 ID 时设 true
googleMobileAds = BillConfig.GoogleMobileAdsConfig(
applicationId = "<GOOGLE_APP_ID>", // AdMob / GAM 共用
)
admob = BillConfig.AdmobConfig(
splashId = "<ID>", bannerId = "<ID>", interstitialId = "<ID>",
nativeId = "<ID>", fullNativeId = "<ID>", rewardedId = "<ID>",
)
gam = BillConfig.GamConfig(
splashId = "<ID>", bannerId = "<ID>", interstitialId = "<ID>",
nativeId = "<ID>", fullNativeId = "<ID>", rewardedId = "<ID>",
)
pangle = BillConfig.PangleConfig(
applicationId = "<PANGLE_APP_ID>",
splashId = "<ID>", bannerId = "<ID>", interstitialId = "<ID>",
nativeId = "<ID>", fullNativeId = "<ID>", rewardedId = "<ID>",
)
topon = BillConfig.ToponConfig(
applicationId = "<TOPON_APP_ID>", appKey = "<TOPON_APP_KEY>",
splashId = "<ID>", bannerId = "<ID>", interstitialId = "<ID>",
nativeId = "<ID>", fullNativeId = "<ID>", rewardedId = "<ID>",
)
// 在这里一并注册下面的全局回调与所需 Renderer。
}Google 初始化:本版本使用 GMA Next Gen,App ID 通过上面的 googleMobileAds 注入;不要为这条链路额外添加 Legacy 的 com.google.android.gms.ads.APPLICATION_ID Manifest 元数据或 Legacy Google Ads 依赖。
若宿主已自行初始化所有接入平台,设 externallyInitialized=true,仍需填写广告位和渲染配置。初始化返回表示流程结束,单个平台失败会记录日志,不代表所有平台都有可展示广告。
使用原生广告前,实现并注入对应平台 Renderer 和布局。下列 My… 类、R.layout… 均由宿主提供,不是库内现成类。
// 放在 initialize 的配置块中;按实际平台注入。
admobNativeRenderer = MyAdmobNativeAdRenderer()
gamNativeRenderer = MyGamNativeAdRenderer()
pangleNativeRenderer = MyPangleNativeAdRenderer()
toponNativeRenderer = MyToponNativeAdRenderer()
admobFullScreenNativeRenderer = MyAdmobFullScreenNativeAdRenderer()
gamFullScreenNativeRenderer = MyGamFullScreenNativeAdRenderer()
pangleFullScreenNativeRenderer = MyPangleFullScreenNativeAdRenderer()
toponFullScreenNativeRenderer = MyToponFullScreenNativeAdRenderer()
// 以 AdMob 为例,其余使用对应平台的样式类型。
admob.nativeStyleStandard = com.android.common.bill.ui.NativeAdStyle(
R.layout.my_native_ad, "normal"
)
adLoadingDialogRenderer = MyAdLoadingDialogRenderer()接口在 com.android.common.bill.ads.renderer 包。原生展示缺少对应 Renderer 会失败;Loading Renderer 未配置时跳过加载弹框。
将所需回调合并到第 3 步的同一个初始化配置块中;无需再次初始化。每个属性只有一个回调,重复赋值会覆盖,设置为 null 可取消监听。
收益和点击回调适用于本页所有版本;关闭和获奖回调从 1.0.55、1.0.55_preloading.10(含 Drama)及 support_risk_1.0.14 提供。开始展示回调从 1.0.56、1.0.56_preloading.11(含 Drama)及 support_risk_1.0.16 提供。使用当前 LCB / IAA 1.0.54 时,仅保留示例中的收益和点击回调。下面示例列齐八个回调;默认版 1.0.58、默认预加载版 1.0.58_preloading.14 和 Risk support_risk_1.0.20 均包含新增的 竞价准入、展示前通知和展示失败;当前 Drama 1.0.56_preloading.11.drama 和 LCB / IAA 尚不包含这三个接口,接入时须移除对应配置。
import com.android.common.bill.ads.bidding.AppOpenBiddingInitializer
import net.corekit.core.ads.RevenueAdData
import org.json.JSONObject
import java.math.BigDecimal
// 合并到第 3 步的初始化调用中,保留广告源配置。
AppOpenBiddingInitializer.initialize(application, R.mipmap.ic_launcher) {
// 以下三个回调适用于当前默认版 1.0.58、默认预加载版 1.0.58_preloading.14、Risk support_risk_1.0.20。
canSourceShow = { data ->
val args = data.toCallbackJson()
// 将 args 交给宿主的本地准入判断,返回 Boolean;此处收益是竞价值。
true // 示例默认放行;替换为宿主判断结果,false 则继续询问下一候选。
}
onAdBeforeShow = { data ->
val args = data.toCallbackJson()
// 即将调用平台展示操作;不保证后续展示成功。
}
onAdShowFailed = { data, reason ->
val args = data.toCallbackJson()
.put("reason", reason)
// 将 args 交给宿主的展示失败处理逻辑;仅表示本次广告会话失败。
}
onAdOpened = { data ->
val args = data.toCallbackJson()
// 广告开始展示;不等同于视频首帧、播放完成或获得奖励。
}
onAdRevenue = { data ->
val args = data.toCallbackJson()
// 将 args 交给宿主的收益处理逻辑。
}
onAdClick = { data ->
val args = data.toCallbackJson()
// 将 args 交给宿主的点击处理逻辑。
}
onAdClose = { data ->
val args = data.toCallbackJson()
// 关闭通知;不代表获得奖励。
}
onAdRewardEarned = { data, rewardType, rewardAmount ->
val args = data.toCallbackJson()
.put("rewardType", rewardType)
.put("rewardAmount", rewardAmount)
// 平台确认获奖;与单次展示回调二选一处理业务发奖。
}
}
// 定义在文件顶层或宿主类中。
private fun RevenueAdData.toCallbackJson(): JSONObject =
JSONObject().apply {
put("revenue", BigDecimal.valueOf(revenue.value))
put("currency", revenue.currencyCode)
put("adType", adFormat)
put("platform", platform)
put("adUnitId", adRevenueUnit)
put("adSource", adRevenueNetwork)
put("adSourceId", adSourceId)
put("extra_info", JSONObject().apply {
put("ad_network", NoviCache.userAdNetwork)
put("campaign", NoviCache.userCampaign)
put("ad_group", NoviCache.userAdgroup)
put("creative", NoviCache.userCreative)
}.toString())
}toCallbackJson() 是宿主侧扩展函数,八个回调的广告数据共用上述 7 个广告字段和 extra_info;extra_info 是包含 ad_network、campaign、ad_group、creative 的 JSON 字符串。NoviCache 为宿主的归因缓存类,请按项目实际包名导入,并在归因结果更新后写入上述属性。展示失败回调额外拼接 reason: String;获奖回调另提供 rewardType: String 和 rewardAmount: Int。onAdRevenue 中的 revenue 为单次收益的主货币单位,不要再次除以 1000;竞价准入中的值仅用于比较,展示前与展示失败回调中的收益为 0,不用于真实收益上报。
| 广告数据字段(八个回调共用) | 含义 |
|---|---|
revenue.value / currencyCode | 单次收益 / 币种;按实际币种处理,SDK 不做汇率换算。 |
platform / adFormat | 聚合平台 / 广告类型。 |
adRevenueUnit | 聚合广告位 ID。 |
adRevenueNetwork / adSourceId | 广告源名称 / 底层源 ID;源 ID 无法获取时回退到聚合广告位 ID。 |
adRevenuePlacement | 平台的广告位置 / placement 信息,保留各平台语义。 |
回调在平台原线程同步执行,耗时操作自行切线程。点击回调不表示新增收益;广告位置参数 position 会进入事件链路的 ad_position,不要假定它总与平台 placement 相同。
奖励名称与数量来自聚合 SDK:AdMob / GAM 的 RewardItem.type / amount、Pangle 的 rewardName / rewardAmount、TopOn 的 scenarioRewardName / scenarioRewardNumber、MAX 的 MaxReward.label / amount。不是新增回调要求业务额外传入的参数。
onRewardEarned 都会执行,业务发奖只选择一处;提前关闭、播放结束或失败不补发奖励。宿主全局回调异常会被隔离。publisherRevenue,仅为 null 时用 ecpm / 1000,明确的 0 保留。币种跟随 SDK,缺失时兜底 USD,不进行汇率换算。这些取值修复也作用于内部上报。BillConfig.onAdOpened: ((RevenueAdData) -> Unit)? 默认 null;设置监听才读取新增参数并通知,设置 null 可取消。同步运行于触发线程,参数读取和宿主回调异常均被隔离,保持既有曝光、收益、点击、关闭、奖励及风控流程。
| 广告类型 | AdMob / GAM | TopOn | Pangle | MAX(仅 Risk) |
|---|---|---|---|---|
| 激励 · Rewarded | onAdShowedFullScreenContent | onRewardedVideoAdPlayStart | onAdShowed | onAdDisplayed |
| 插页 · Interstitial | onAdShowedFullScreenContent | onInterstitialAdShow | onAdShowed | onAdDisplayed |
| 开屏 · Splash | onAdShowedFullScreenContent | onAdShow | onAdShowed | onAdDisplayed |
| 普通原生 · Native | onAdImpression | onAdImpressed | onAdShowed | 不触发;不使用收益兜底 |
| Banner | onAdImpression | onBannerShow | onAdShowed | 不触发;不使用收益兜底 |
| 全屏原生 · FullNative | onAdImpression | onAdImpressed | onAdShowed | 自定义视图成功绑定后的展示通知 |
data.adFormat 是字符串:Rewarded / Interstitial / Splash / Native / Banner / FullNative。可使用 AdType.fromConfigKey(data.adFormat) 转为枚举;未知值为 null。本次版本保留 AdType 和 AdType.Companion 的发布及宿主混淆规则。platform + adFormat + adRevenueUnit 判断来自哪个平台、类型和广告位;RevenueAdData 没有单次展示唯一 ID,不能据此严格区分同广告位的连续或并发展示。import com.android.common.bill.BillConfig
import com.android.common.bill.ads.config.AdType
BillConfig.onAdOpened = { data ->
val type: AdType? = AdType.fromConfigKey(data.adFormat)
if (type == AdType.REWARDED) {
// 激励广告已开始展示;不在这里发放奖励。
}
}
默认版 1.0.57 / 默认预加载版 1.0.57_preloading.12 / Risk support_risk_1.0.17 起 BillConfig.canSourceShow: ((RevenueAdData) -> Boolean)?。内部仍负责获取价格、生成候选并排序;外部只决定当前候选是否允许展示。适用于 AdMob、GAM、TopOn、Pangle 的开屏、插页、激励、原生、全屏原生及 Banner 竞价;Risk 另覆盖 MAX。
import com.android.common.bill.BillConfig
// mmmobCanSourceShow 为宿主业务函数,接收 RevenueAdData 并返回 Boolean。
BillConfig.canSourceShow = { data ->
mmmobCanSourceShow(data)
}
// 取消筛选,恢复原有内部竞价。
// BillConfig.canSourceShow = null
假设内部价格为 A > B > C:先问 A,true 就用 A 并停止;false 才问 B,再依次问 C。配置了回调且候选全部拒绝:本轮无胜出者,没有 AdMob 兜底。未配置回调:保持各分支原有选择规则和可用性检查。
BiddingWinner.NONE,Risk 内部返回 BiddingOutcome.Unavailable(SOURCE_SHOW_DENIED)。不上报 ad_bid_win,统一展示入口上报 external_source_show_denied 并返回原有无可用平台失败码(开屏 -201、插页 -202、激励 -203、全屏原生 -204、Banner -205);普通原生返回 false。普通版 / 默认预加载版直接调用竞价管理器的宿主必须处理新增的 BiddingWinner.NONE,包括 Kotlin 穷举 when;Risk 竞价管理器为内部实现。biddingResult 及直接调用平台 Controller 不经过价格比较,不触发准入回调。实际 show 前不单独重复询问;开屏 / 激励与插页竞争时,各类型独立筛选。Risk 因缓存失效或风控变化重新竞价时,会在新一轮中重新询问候选。ad_bid_excluded 记录 external_source_show_check_error;正常拒绝记录 external_source_show_denied。协程取消继续向上传播。兼容性修复版本:默认预加载版 1.0.58_preloading.14 不会改道到准入已拒绝的插屏。Risk support_risk_1.0.20 在选胜出 ID 前重新读取 REQUEST / SHOW 门禁(不增加请求计数);缓存失效或风控变化后重新竞价会使用新的有效候选,并保留 ad_risk_blocked / external_source_show_denied 的准确失败原因。全屏原生沿用既有行为风控豁免。
沿用其他回调的类型,无需增加入参。以下为候选 AdMob 插页的字段示意,不代表自动 JSON 序列化结果;通过公开属性读取。
{
"revenue": { "value": 0.03, "currencyCode": "USD" },
"platform": "Admob",
"adRevenueNetwork": "Admob",
"adRevenueUnit": "ca-app-pub-xxx/xxx",
"adSourceId": "ca-app-pub-xxx/xxx",
"adRevenuePlacement": "",
"adFormat": "Interstitial"
}
| 字段 | 准入回调中的含义 |
|---|---|
revenue.value / currencyCode | 现有内部竞价比较值 / USD;没有取到价格时为 0,不新增换算。不是已经产生的真实收益,不用于收益上报。 |
platform | 候选聚合平台:Admob、GAM、Pangle、TopOn;Risk 另有 MAX。 |
adRevenueUnit / adSourceId | 均使用当前平台的聚合广告位 ID;Risk AdMob 多 ID 使用平台内本轮胜出候选的实际 ID。每轮每个平台最多询问一次,拒绝 AdMob 后继续下一平台。 |
adRevenueNetwork | 使用平台名;此处不额外读取底层广告网络。 |
adRevenuePlacement | 空字符串;业务 position 仍保留在埋点中。 |
adFormat | Splash / Interstitial / Rewarded / Native / FullNative / Banner。 |
默认版 1.0.57 / 默认预加载版 1.0.57_preloading.12 / Risk support_risk_1.0.17 起 BillConfig.onAdBeforeShow: ((RevenueAdData) -> Unit)?。覆盖 AdMob / GAM / Pangle / TopOn 六种类型,Risk 另覆盖 MAX 六种类型;通知发生在对应平台实际展示、渲染或挂载之前。
BillConfig.onAdBeforeShow = { data ->
// 在这里对接宿主的 mmmobCallAdShow。
// 此时即将调用平台展示操作,不保证后续展示成功。
}
onAdOpened 相互独立。默认版 1.0.57 / 默认预加载版 1.0.57_preloading.12 / Risk support_risk_1.0.17 起 BillConfig.onAdShowFailed: ((RevenueAdData, String) -> Unit)?。广告数据类型保持一致,额外提供失败 reason(沿用原有回调处理规则,最多 64 字符);当前三个默认分支的埋点原因独立归类,可能与回调 reason 不同。
BillConfig.onAdShowFailed = { data, reason ->
// 在这里对接宿主的 mmmobOnAdShowFail。
// 使用 data.adFormat 和 reason 判断本次会话失败原因。
}
上述三个新版本新增的取消、销毁、失败返回或异常兜底只补齐埋点,不额外触发宿主失败回调。已有真实失败及生命周期失败通知仍走原路径;补偿层不会因 SDK 已提交后的单纯取消等待新增失败,各平台原有取消处理保留。请勿把 ad_show_fail 事件数量当作业务失败回调数量,或据此补发奖励。
| 业务接口 | SDK 接入点 |
|---|---|
mmmobOnImpression(收益) | onAdRevenue(data),只使用真实收益通知。 |
mmmobAdClick | onAdClick(data) |
mmmobCallAdShow | onAdBeforeShow(data),表示即将尝试展示。 |
mmmobOnAdShowFail | onAdShowFailed(data, reason),按宿主签名适配。 |
mmmobOnAdClose | onAdClose(data) |
mmmobCanSourceShow | canSourceShow(data): Boolean,仅竞价价格比较阶段。 |
在首次请求广告前,注册宿主的事件与收益上报器。
import net.corekit.core.ads.RevenueAdManager
import net.corekit.core.report.ReportDataManager
// My… 为宿主实现的上报器。
RevenueAdManager.setReporter(MyRevenueReporter()) // 实现 RevenueAdReporter
ReportDataManager.setReporters(listOf(MyEventReporter())) // 实现 ReporterData库负责产出数据,上报平台由宿主接入。收益 Reporter 与 onAdRevenue 独立触发,同一目的地只上报一次。若接 ThinkingData,对应 ReporterData.getName() 返回 "ThinkingData",供 SDK 定向事件使用。
下面在 FragmentActivity 的协程中执行;gatherConsent 挂起版本返回是否放行广告请求。它会判断地区,在非 GDPR 地区跳过弹窗。
import androidx.lifecycle.lifecycleScope
import kotlinx.coroutines.launch
import com.android.common.bill.ads.util.GoogleMobileAdsConsentManager
import com.android.common.bill.ads.PreloadController
lifecycleScope.launch {
val consent = GoogleMobileAdsConsentManager.getInstance(applicationContext)
val allowed = consent.gatherConsent(this@MainActivity)
if (!allowed) return@launch
// 确保第 3 步初始化已结束,再按需要预加载。
PreloadController.preloadAll(applicationContext) // 插页 + 普通原生
// 可选,按实际使用的类型开启:
// PreloadController.preloadAllAppOpen(applicationContext)
// PreloadController.preloadAllRewarded(applicationContext)
// PreloadController.preloadAllFullScreenNative(applicationContext)
}预加载异步执行,调用返回不表示缓存已就绪;展示入口可在无缓存时尝试加载。只需要插页时,可改用 preloadAdmobInterstitial、preloadGamInterstitial、preloadPangleInterstitial、preloadTopOnInterstitial。
此授权辅助方法包含失败降级,返回值不等于用户必然点击了“同意”。隐私设置入口可结合 isPrivacyOptionsRequired 和 showPrivacyOptionsForm(activity) { error -> … } 使用。
需要先根据业务判断禁止展示时,使用 ExternalAdBlockController · 屏蔽广告 API(main / preloading)。
在已初始化、已处理授权的有效 Activity 中调用。以下为独立片段,按需选择一个放入 lifecycleScope.launch { … },不要连续弹出。activity 为 FragmentActivity,container 为已挂入页面的 ViewGroup。
import com.android.common.bill.ads.ext.AdShowExt
import com.android.common.bill.ui.NativeAdStyleType
// 1. 开屏
AdShowExt.showAppOpenAd(
activity = activity,
onLoaded = { loaded -> /* 可更新加载进度 */ },
countdown = null,
showLoading = false,
competeWithInterstitial = false,
position = "APP_OPEN",
)
// 2. 插页
AdShowExt.showInterstitialAd(
activity = activity,
ignoreFullNative = true, // 本次不改道全屏原生
position = "INTERSTITIAL",
)
// 3. 激励
AdShowExt.showRewardedAd(
activity = activity,
onRewardEarned = { /* 在这里处理奖励,并自行保证幂等 */ },
competeWithInterstitial = false, // 本次只展示激励
position = "REWARDED",
)
// 4. 普通原生:需先注册对应 Renderer
val filled = AdShowExt.showNativeAdInContainer(
context = activity,
container = container,
styleType = NativeAdStyleType.STANDARD,
position = "NATIVE",
)
// 5. 全屏原生:需先注册对应全屏 Renderer
AdShowExt.showFullScreenNativeAdInContainer(
activity = activity,
showInterstitial = false, // 本次不衔接插页
position = "FULL_NATIVE",
)
// 6. Banner
AdShowExt.showBannerAd(
activity = activity,
container = container,
position = "BANNER",
)position 是宿主自定义的位置标识,不是平台广告位 ID。普通原生返回 Boolean,其他入口返回 AdResult;激励是否获得奖励以 onRewardEarned 为准。
import com.android.common.bill.ads.AdResult
val result = AdShowExt.showInterstitialAd(
activity, ignoreFullNative = true, position = "INTERSTITIAL"
)
when (result) {
is AdResult.Success -> { /* 展示流程成功结束 */ }
is AdResult.Failure -> {
val code = result.error.code
val message = result.error.message
// 记录失败并继续宿主流程;无需无间隔重试。
}
}开屏 / 激励省略 competeWithInterstitial 时会跟随 SDK 配置,可能与插页竞价;以上示例显式关闭。插页默认允许按策略改道全屏原生,以上示例用 ignoreFullNative=true 固定为插页。
以下 Key 是 Firebase Remote Config 的逻辑参数名,值类型均为字符串,内容粘贴对应 JSON。大小写须保持一致。Core 支持加密 Key / 值;已配置加密参数时优先读取加密项,具体映射以宿主包名为准。
adRuntimeIdConfigJson平台 ID / Key · MAX 仅 Risk 版主线 / Preloading / Risk全部分支adConfigNaturalJson自然量 · 竞价与频控 · MAX 仅 Risk 版主线 / Preloading / Risk全部分支adConfigPaidJson付费量 · 竞价与频控 · MAX 仅 Risk 版主线 / Preloading / RiskPreloading 分支Admob_Preloading_ConfigGoogle 加载模式 · 默认 / Drama 产品线主线 / Risk 分支暂不支持Preloading / Risk 分支admob_content_targeting_configAdMob 内容定向 · 关键词组与 URLPreloading(默认 / Drama)/ RiskRisk 分支Ad_Risk_Config行为风控 / 环境处置需引入 ad-risk 风控库全部分支ad_slot_switch广告位开关 · 宿主主动查询通过共用 Core 提供,各分支均可使用版本范围:通用广告配置适用于本页各 Bill 版本;MAX 字段仅 support_risk_1.0.20 支持。Admob_Preloading_Config 由 1.0.58_preloading.14 和 1.0.56_preloading.11.drama 支持,当前普通版 / LCB / IAA / Risk 版未接入这一在线模式开关。Risk 参数需额外引入 ad-risk;不引入时不影响 Bill 本身的广告能力。
adRuntimeIdConfigJson平台 ID / Key · 各版本通用,MAX 仅 Risk 版
覆盖初始化注入的广告源配置;非空字段生效,省略或空字符串保留已有配置。先应用缓存再读取在线值;BillConfig.skipRuntimeAdIdConfig=true 时跳过动态 ID。在线没有 max 节点时保留当前 MAX 配置(宿主注入值,或此前已应用的非空缓存值);max.sdkKey 是 AppLovin SDK Key,其他字段是对应广告位 ID。下面占位符须替换为实际配置,未接入的平台请省略。
数组配置仅适用于 Risk support_risk_1.0.15 及其后续兼容版本。本页其他产品线和旧 Risk 版本继续使用字符串。支持数组的字段为 splashId、interstitialId、rewardedId、nativeId、fullNativeId;bannerId 始终为单字符串。
{
"admob": {
"splashId": ["OPEN_A", "OPEN_B"],
"interstitialId": ["INTERSTITIAL_A", "INTERSTITIAL_B"],
"rewardedId": ["REWARDED_A", "REWARDED_B"],
"nativeId": ["NATIVE_A", "NATIVE_B"],
"fullNativeId": ["FULL_NATIVE_A", "FULL_NATIVE_B"],
"bannerId": "BANNER_SINGLE"
}
}
在线配置:把以上 JSON 作为字符串填入 adRuntimeIdConfigJson。代码配置:调用下面的公开接口;BillConfig.AdmobConfig 原有字段仍为 String,多 ID 通过 JSON 更新。
import com.android.common.bill.ads.config.AdRuntimeIdConfigManager
AdRuntimeIdConfigManager.updateRuntimeIdConfig(
"""{"admob":{"interstitialId":["INTERSTITIAL_A","INTERSTITIAL_B"]}}"""
)
// 切回单 ID,替换该类型的整个列表
AdRuntimeIdConfigManager.updateRuntimeIdConfig(
"""{"admob":{"interstitialId":"INTERSTITIAL_C"}}"""
)
skipRuntimeAdIdConfig=true 只跳过自动缓存 / 远程读取,不阻止手动更新。用 AdLogger.setLogEnabled(true) 开启日志,在 Logcat 筛选 Tag AdModule 和 [AdMobIds];日志包含广告类型和 ID。
config / eligible / request_blocked:配置、可请求列表与拦截。load_start / load_ready / load_failed / cache_hit:每个 ID 的加载和缓存状态。candidate / winner / consumed_refill:候选收益、内部胜出和消费后补充;priceKnown=false 表示未读到收益。本次广告库 348 项单测通过。固定 AdMob 和 BIDDING 完成单 / 多 ID 真机回归,SDK 上报侧按 session 核对 ad_position = ad_impression + ad_show_fail。插页、原生和全屏原生使用两个不同有效测试 ID;开屏、激励使用重复官方测试 ID,去重后验证的是单 ID 兼容链路,不能视为两个不同 ID 的真机验证。
{
"googleMobileAds": {
"applicationId": "<GOOGLEMOBILEADS_APPLICATION_ID>"
},
"admob": {
"splashId": "<ADMOB_SPLASH_ID>",
"bannerId": "<ADMOB_BANNER_ID>",
"interstitialId": "<ADMOB_INTERSTITIAL_ID>",
"nativeId": "<ADMOB_NATIVE_ID>",
"fullNativeId": "<ADMOB_FULL_NATIVE_ID>",
"rewardedId": "<ADMOB_REWARDED_ID>"
},
"gam": {
"splashId": "<GAM_SPLASH_ID>",
"bannerId": "<GAM_BANNER_ID>",
"interstitialId": "<GAM_INTERSTITIAL_ID>",
"nativeId": "<GAM_NATIVE_ID>",
"fullNativeId": "<GAM_FULL_NATIVE_ID>",
"rewardedId": "<GAM_REWARDED_ID>"
},
"pangle": {
"applicationId": "<PANGLE_APPLICATION_ID>",
"splashId": "<PANGLE_SPLASH_ID>",
"bannerId": "<PANGLE_BANNER_ID>",
"interstitialId": "<PANGLE_INTERSTITIAL_ID>",
"nativeId": "<PANGLE_NATIVE_ID>",
"fullNativeId": "<PANGLE_FULL_NATIVE_ID>",
"rewardedId": "<PANGLE_REWARDED_ID>"
},
"topon": {
"applicationId": "<TOPON_APPLICATION_ID>",
"appKey": "<TOPON_APP_KEY>",
"splashId": "<TOPON_SPLASH_ID>",
"bannerId": "<TOPON_BANNER_ID>",
"interstitialId": "<TOPON_INTERSTITIAL_ID>",
"nativeId": "<TOPON_NATIVE_ID>",
"fullNativeId": "<TOPON_FULL_NATIVE_ID>",
"rewardedId": "<TOPON_REWARDED_ID>"
},
"max": {
"sdkKey": "<MAX_SDK_KEY>",
"splashId": "<MAX_SPLASH_ID>",
"bannerId": "<MAX_BANNER_ID>",
"interstitialId": "<MAX_INTERSTITIAL_ID>",
"nativeId": "<MAX_NATIVE_ID>",
"fullNativeId": "<MAX_FULL_NATIVE_ID>",
"rewardedId": "<MAX_REWARDED_ID>"
}
}两份参数结构相同,分别用于 natural / paid 用户,各自存一个完整配置对象,不套 natural / paid 外层。示例包含 MAX,共开启五个平台,禁用 Banner;未接入的平台请显式改成 false。
| 字段 | 配置参考与含义 |
|---|---|
app_open / interstitial / native / rewarded / banner | 开屏 / 插页 / 原生 / 激励 / Banner。全屏原生也读取 native 节点的配置,但按自己的广告类型独立计数。 |
bidding_platforms | admob、gam、pangle、topon、max:布尔值。关闭类型需将该版本支持的所有平台都设 false。省略平台字段会使用代码默认 true。 |
total_frequency_limits | 跨平台的本广告类型每日展示 / 点击总上限;不检查 min_interval。 |
bidding_frequency_limits | 各平台独立的 max_daily_show、max_daily_click、min_interval;min_interval 单位为秒。 |
max_daily_show / max_daily_click | 达到上限即阻断;0 表示没有额度,不表示无限制。代码字段缺省值为 20 / 10。 |
min_interval | 平台两次展示的最小间隔,0 表示不限制间隔;代码缺省为 0。 |
compete_with_interstitial | 只用于 app_open / rewarded;省略默认 true。show 方法显式传 competeWithInterstitial 时以调用参数为准。 |
ad_strategies.fullscreen_native_after_interstitial | 按插页累计次数判断是否改道全屏原生,需已有对应缓存且调用允许;0 关闭。 |
ad_strategies.app_open_after_interstitial | 插页累计展示次数达到正整数 N 的倍数后,尝试衔接开屏;0 关闭。大于 0 时优先此策略,不走改道全屏原生。 |
下面显式把两项 ad_strategies 设为 0,以保持基础展示流程。代码数据类省略字段时的默认值是 3 / 2,不应通过删字段来关闭策略。线上策略更新会替换该渠道配置;不要把局部 JSON 当成补丁合并。
adConfigNaturalJson{
"app_open": {
"compete_with_interstitial": false,
"bidding_platforms": { "admob": true, "gam": true, "pangle": true, "topon": true, "max": true },
"total_frequency_limits": { "max_daily_show": 20, "max_daily_click": 5 },
"bidding_frequency_limits": {
"admob": { "max_daily_show": 10, "max_daily_click": 3, "min_interval": 60 },
"gam": { "max_daily_show": 10, "max_daily_click": 3, "min_interval": 60 },
"pangle": { "max_daily_show": 10, "max_daily_click": 3, "min_interval": 60 },
"topon": { "max_daily_show": 10, "max_daily_click": 3, "min_interval": 60 },
"max": { "max_daily_show": 10, "max_daily_click": 3, "min_interval": 60 }
}
},
"interstitial": {
"bidding_platforms": { "admob": true, "gam": true, "pangle": true, "topon": true, "max": true },
"total_frequency_limits": { "max_daily_show": 20, "max_daily_click": 5 },
"bidding_frequency_limits": {
"admob": { "max_daily_show": 10, "max_daily_click": 3, "min_interval": 60 },
"gam": { "max_daily_show": 10, "max_daily_click": 3, "min_interval": 60 },
"pangle": { "max_daily_show": 10, "max_daily_click": 3, "min_interval": 60 },
"topon": { "max_daily_show": 10, "max_daily_click": 3, "min_interval": 60 },
"max": { "max_daily_show": 10, "max_daily_click": 3, "min_interval": 60 }
}
},
"native": {
"bidding_platforms": { "admob": true, "gam": true, "pangle": true, "topon": true, "max": true },
"total_frequency_limits": { "max_daily_show": 20, "max_daily_click": 5 },
"bidding_frequency_limits": {
"admob": { "max_daily_show": 10, "max_daily_click": 3, "min_interval": 30 },
"gam": { "max_daily_show": 10, "max_daily_click": 3, "min_interval": 30 },
"pangle": { "max_daily_show": 10, "max_daily_click": 3, "min_interval": 30 },
"topon": { "max_daily_show": 10, "max_daily_click": 3, "min_interval": 30 },
"max": { "max_daily_show": 10, "max_daily_click": 3, "min_interval": 30 }
}
},
"rewarded": {
"compete_with_interstitial": false,
"bidding_platforms": { "admob": true, "gam": true, "pangle": true, "topon": true, "max": true },
"total_frequency_limits": { "max_daily_show": 20, "max_daily_click": 5 },
"bidding_frequency_limits": {
"admob": { "max_daily_show": 10, "max_daily_click": 3, "min_interval": 60 },
"gam": { "max_daily_show": 10, "max_daily_click": 3, "min_interval": 60 },
"pangle": { "max_daily_show": 10, "max_daily_click": 3, "min_interval": 60 },
"topon": { "max_daily_show": 10, "max_daily_click": 3, "min_interval": 60 },
"max": { "max_daily_show": 10, "max_daily_click": 3, "min_interval": 60 }
}
},
"banner": {
"bidding_platforms": { "admob": false, "gam": false, "pangle": false, "topon": false, "max": false },
"total_frequency_limits": { "max_daily_show": 0, "max_daily_click": 5 },
"bidding_frequency_limits": {
"admob": { "max_daily_show": 0, "max_daily_click": 3, "min_interval": 0 },
"gam": { "max_daily_show": 0, "max_daily_click": 3, "min_interval": 0 },
"pangle": { "max_daily_show": 0, "max_daily_click": 3, "min_interval": 0 },
"topon": { "max_daily_show": 0, "max_daily_click": 3, "min_interval": 0 },
"max": { "max_daily_show": 0, "max_daily_click": 3, "min_interval": 0 }
}
},
"ad_strategies": {
"fullscreen_native_after_interstitial": 0,
"app_open_after_interstitial": 0
}
}adConfigPaidJson{
"app_open": {
"compete_with_interstitial": false,
"bidding_platforms": { "admob": true, "gam": true, "pangle": true, "topon": true, "max": true },
"total_frequency_limits": { "max_daily_show": 40, "max_daily_click": 10 },
"bidding_frequency_limits": {
"admob": { "max_daily_show": 20, "max_daily_click": 5, "min_interval": 30 },
"gam": { "max_daily_show": 20, "max_daily_click": 5, "min_interval": 30 },
"pangle": { "max_daily_show": 20, "max_daily_click": 5, "min_interval": 30 },
"topon": { "max_daily_show": 20, "max_daily_click": 5, "min_interval": 30 },
"max": { "max_daily_show": 20, "max_daily_click": 5, "min_interval": 30 }
}
},
"interstitial": {
"bidding_platforms": { "admob": true, "gam": true, "pangle": true, "topon": true, "max": true },
"total_frequency_limits": { "max_daily_show": 40, "max_daily_click": 10 },
"bidding_frequency_limits": {
"admob": { "max_daily_show": 20, "max_daily_click": 5, "min_interval": 30 },
"gam": { "max_daily_show": 20, "max_daily_click": 5, "min_interval": 30 },
"pangle": { "max_daily_show": 20, "max_daily_click": 5, "min_interval": 30 },
"topon": { "max_daily_show": 20, "max_daily_click": 5, "min_interval": 30 },
"max": { "max_daily_show": 20, "max_daily_click": 5, "min_interval": 30 }
}
},
"native": {
"bidding_platforms": { "admob": true, "gam": true, "pangle": true, "topon": true, "max": true },
"total_frequency_limits": { "max_daily_show": 40, "max_daily_click": 10 },
"bidding_frequency_limits": {
"admob": { "max_daily_show": 20, "max_daily_click": 5, "min_interval": 30 },
"gam": { "max_daily_show": 20, "max_daily_click": 5, "min_interval": 30 },
"pangle": { "max_daily_show": 20, "max_daily_click": 5, "min_interval": 30 },
"topon": { "max_daily_show": 20, "max_daily_click": 5, "min_interval": 30 },
"max": { "max_daily_show": 20, "max_daily_click": 5, "min_interval": 30 }
}
},
"rewarded": {
"compete_with_interstitial": false,
"bidding_platforms": { "admob": true, "gam": true, "pangle": true, "topon": true, "max": true },
"total_frequency_limits": { "max_daily_show": 40, "max_daily_click": 10 },
"bidding_frequency_limits": {
"admob": { "max_daily_show": 20, "max_daily_click": 5, "min_interval": 30 },
"gam": { "max_daily_show": 20, "max_daily_click": 5, "min_interval": 30 },
"pangle": { "max_daily_show": 20, "max_daily_click": 5, "min_interval": 30 },
"topon": { "max_daily_show": 20, "max_daily_click": 5, "min_interval": 30 },
"max": { "max_daily_show": 20, "max_daily_click": 5, "min_interval": 30 }
}
},
"banner": {
"bidding_platforms": { "admob": false, "gam": false, "pangle": false, "topon": false, "max": false },
"total_frequency_limits": { "max_daily_show": 0, "max_daily_click": 10 },
"bidding_frequency_limits": {
"admob": { "max_daily_show": 0, "max_daily_click": 5, "min_interval": 0 },
"gam": { "max_daily_show": 0, "max_daily_click": 5, "min_interval": 0 },
"pangle": { "max_daily_show": 0, "max_daily_click": 5, "min_interval": 0 },
"topon": { "max_daily_show": 0, "max_daily_click": 5, "min_interval": 0 },
"max": { "max_daily_show": 0, "max_daily_click": 5, "min_interval": 0 }
}
},
"ad_strategies": {
"fullscreen_native_after_interstitial": 0,
"app_open_after_interstitial": 0
}
}admob_content_targeting_config适用于本页的 Preloading .7 默认版、drama 版及 Risk support_risk_1.0.20。按实际 AdMob 广告位 ID 匹配配置,开屏、插页、激励、原生、全屏原生和 Banner 共用此结构;GAM 不使用该参数。示例中的广告位 ID 和 URL 需替换为实际值。
keyword_groups 定义组 ID 与关键词数组;ad_units 引用组 ID。普通加载每次请求按顺序使用一组;官方 Preloader 新建队列时选一组,队列内补量不换组,重复启动已有队列也不换组。
SDK 通过原有 ConfigRemoteManager.getString 读取,兼容明文 / 密文 Key 和 Value,并先应用上次有效缓存。配置缺失且无有效缓存、未匹配广告位或所有参数均未生效时,不给展示、点击事件附加定向字段;只有部分字段为空时,只要有参数生效,仍上报四个字段,空字段使用空字符串或空数组。空 URL 不调用对应设置接口。日志受 CoreLogger 开关控制。
{
"keyword_groups": [
{
"keyword_group_id": "music_001",
"keywords": [
"music",
"audio player",
"equalizer"
]
},
{
"keyword_group_id": "cleaner_001",
"keywords": [
"storage cleaner",
"phone cleaner",
"file manager"
]
}
],
"ad_units": {
"ca-app-pub-xxxxxxxxxxxxxxxx/1111111111": {
"keyword_group_ids": [
"music_001"
],
"content_url": "https://example.com/products/home",
"neighboring_content_urls": [
"https://example.com/products/music-player",
"https://example.com/products/equalizer"
]
},
"ca-app-pub-xxxxxxxxxxxxxxxx/2222222222": {
"keyword_group_ids": [
"music_001",
"cleaner_001"
],
"content_url": "https://example.com/products/home",
"neighboring_content_urls": [
"https://example.com/products/music-player",
"https://example.com/products/storage-cleaner"
]
},
"ca-app-pub-xxxxxxxxxxxxxxxx/3333333333": {
"keyword_group_ids": [
"cleaner_001"
],
"content_url": "",
"neighboring_content_urls": [
"https://example.com/products/storage-cleaner",
"https://example.com/products/file-manager"
]
},
"ca-app-pub-xxxxxxxxxxxxxxxx/4444444444": {
"keyword_group_ids": [
"music_001",
"cleaner_001"
],
"content_url": "https://example.com/products/music-player",
"neighboring_content_urls": []
}
}
}| ad_click / ad_impression 属性 | 含义 |
|---|---|
keyword_group_id | 本次实际使用的一组 ID,字符串。 |
keyword_list | 该组实际写入请求的关键词数组。 |
content_url | 实际写入请求的内容 URL,未使用时为空字符串。 |
neighboring_content_urls | 实际写入请求的相关内容 URL 数组,未使用时为空数组。 |
展示与点击使用广告加载时绑定的参数,不在回调时重新读取配置;素材字段与内容定向可以同时上报。素材字段说明。
启动读取配置后上报 ad_targeting_config_fetch:result 为 success、not_modified 或 failed,error_code 成功时为空字符串。not_modified 表示读取值与上次有效配置去除首尾空白后相同。
Preloading .7 默认 / Drama · Risk 1.0.12 · AdMob
ad_impression 与 ad_click 按字段独立附加下列非空值;宿主无需增加配置。原生与全屏原生使用 Google 公开 API;插页、激励和开屏从当前广告对象取得 HTML,再解析已识别的素材模板。
| 字段 | 类型 | 含义 |
|---|---|---|
ad_creative_title | String | 素材模板提供的广告标题。 |
ad_creative_description | String | 素材模板提供的广告正文或描述。 |
ad_creative_image_url | String | 已识别的素材主图 URL;不会用 Logo、追踪图片或宿主图标填充。 |
以下为 Google Next-Gen 1.2.1 使用 Google 官方测试广告位在短剧真机中的样本结果,不能视为所有广告模板的保证。15 次补充展示中,7 次取得三项,8 次取得部分字段;普通加载与官方预加载沿用相同提取逻辑。Risk 已迁移同一实现,但这批真机样本来自短剧预加载分支。
| 广告 / 模板 | 标题 | 描述 | 主图 URL |
|---|---|---|---|
| 原生 / 全屏原生 | 沿用公开 API;各字段有值才上报。 | ||
| 插页 · 横版 / 竖版纯图片(5 次) | 未取得 | 未取得 | 取得 |
| 激励 · HTML 动画模板(5 次) | 取得 | 取得 | 取得 |
| 开屏 · 大图 + 文案(2 次) | 取得 | 取得 | 取得 |
| 开屏 · Logo + 文案(2 次) | 取得 | 取得 | 未取得;Logo 不作为主图 |
| 开屏 · 纯文案(1 次) | 取得 | 取得 | 未取得 |
HTML 动画可能返回模板预置或尾帧素材,不能保证对应曝光瞬间的画面。真实视频、互动试玩、第三方聚合素材及其他未知模板尚未验证;图片中的文字不会通过 OCR 提取。GAM 等其他平台不在本次新增范围。
反射路径随 SDK 版本配置;未匹配版本、路径失效、没有已知模板或解析失败时,不附加相应字段,不填占位值。每次展示最多解析一次,解析在后台执行,HTML 超过 512 Ki 字符时跳过;不会执行素材脚本或额外请求图片。素材获取失败不改变已有内容定向和埋点逻辑。
Admob_Preloading_ConfigPreloading .7 默认 / Drama · AdMob / GAM
只控制 AdMob / GAM 的三种格式:IV 插页、RV 激励、SP 开屏。*_Preloading_Enable 为 1 时开启 GMA Preloading,0 走普通 Loading。*_Buffer_Size 是该格式的目标缓存数量,使用正整数;源码对非正数回退为 1,实际容量还受底层 SDK 额度约束。
{
"Admob_IV_Preloading_Enable": 1,
"Admob_IV_Buffer_Size": 1,
"Admob_RV_Preloading_Enable": 1,
"Admob_RV_Buffer_Size": 1,
"Admob_SP_Preloading_Enable": 0,
"Admob_SP_Buffer_Size": 1,
"GAM_IV_Preloading_Enable": 0,
"GAM_IV_Buffer_Size": 1,
"GAM_RV_Preloading_Enable": 0,
"GAM_RV_Buffer_Size": 1,
"GAM_SP_Preloading_Enable": 0,
"GAM_SP_Buffer_Size": 1
}随包默认是所有 Enable 为 0、Buffer Size 为 1。该配置在平台初始化前读取,并在本进程内固定;调整后重新启动进程验证。关闭此模式不会禁止 PreloadController 提前加载,只是切换 Google 的具体加载方式。
远程参数为空或解析失败时使用本地 assets;读取返回 null 时保留缓存 / 已有本地配置。这里的模式开关与广告平台开关、展示频控分别生效。
Ad_Risk_Configad-risk:1.0.8 · 搭配 Bill support_risk_1.0.20
下方为随包默认配置:behavior_mode=2 表示观察,记录与上报行为但不执行行为风控拦截;0 关闭,1 执行。冷启动先读缓存 / 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
}| 字段 | 含义与边界 |
|---|---|
mistake_click_time / mistake_click_count | 误触返回时长(秒)与触发次数;默认 20 / 2。count 为 0 不触发限制。 |
restrict_interval / close_click_count | 执行模式冷却秒数 / 同一插页会话的强关点击阈值;默认 1800 / 3。 |
close_activity_class_names | 追加允许强关的 Activity 完整类名;空数组保留内置默认白名单。 |
limits.<type> | 请求、曝光、点击、连续填充失败阈值。Risk 的 0 表示不限制,与 Bill 的频控额度 0 含义不同。同类型共用阈值,按类型 + position 独立计数。行为风控当前仅处理 AdMob 的开屏、插页、原生、Banner 和激励,不处理全屏原生。 |
vpn / dns / ip / simulator / adb / sim / no_gp / sys_9_low / play*_ad_config | -1 未配置;0 屏蔽 AdMob;1 屏蔽全部广告。Risk 仅解析并通过 AdRisk.signalConfig 提供这些值,设备检测与调用平台限制 API 由业务负责。 |
MAX 已接入 Risk 平台限制桥接;行为风控默认观察不等于取消业务主动设置的平台限制。字段触发边界见 Risk 在线参数说明,平台限制调用见 Risk 外部 API。
ad_slot_switch宿主主动调用 AdSlotSwitchController.isEnabled(position) 查询;AdShowExt 不自动检查此开关。自然分组名是 organic;未配置、未声明或解析失败默认关闭。
{
"organic": {
"APP_OPEN": true,
"INTERSTITIAL": true
},
"paid": {
"APP_OPEN": true,
"INTERSTITIAL": true
}
}投放目标事件仍可通过 BillConfig.enableAdTargetEvents 显式开启,默认 false。
四个控制类的示例共用下列类型:
import com.android.common.bill.ads.PreloadController
import com.android.common.bill.ads.frequency.AdFrequencyController
import com.android.common.bill.ads.bidding.AdCacheStatusController
import com.android.common.bill.ads.bidding.AdSourceController
import com.android.common.bill.ads.config.AdType
import com.android.common.bill.ads.config.AdPlatform
// AdType: APP_OPEN / INTERSTITIAL / REWARDED / NATIVE / FULL_SCREEN_NATIVE / BANNER
// AdPlatform: ADMOB / GAM / PANGLE / TOPON
// support_risk_1.0.20 另支持 MAX包名:com.android.common.bill.ads.PreloadController。通用的 24 个函数参数均为 context: Context、返回 Unit,内部异步执行。请在初始化及授权处理后按需调用,返回不代表加载完成。
| 公开函数 | 返回值 / 用途 |
|---|---|
preloadAll(context: Context): Unit | 所有可用平台:普通原生 + 插页。 |
preloadAllFullScreenNative(context: Context): Unit | 所有可用平台:全屏原生。 |
preloadAllAppOpen(context: Context): Unit | 所有可用平台:开屏。 |
preloadAllRewarded(context: Context): Unit | 所有可用平台:激励。 |
| 公开函数 | 返回值 / 用途 |
|---|---|
preloadAdmob(context: Context): Unit | AdMob · 普通原生 + 插页 |
preloadAdmobInterstitial(context: Context): Unit | AdMob · 插页 |
preloadAdmobNative(context: Context): Unit | AdMob · 普通原生 |
preloadAdmobFullScreenNative(context: Context): Unit | AdMob · 全屏原生 |
preloadAdmobRewarded(context: Context): Unit | AdMob · 激励 |
preloadGam(context: Context): Unit | GAM · 普通原生 + 插页 |
preloadGamInterstitial(context: Context): Unit | GAM · 插页 |
preloadGamNative(context: Context): Unit | GAM · 普通原生 |
preloadGamFullScreenNative(context: Context): Unit | GAM · 全屏原生 |
preloadGamRewarded(context: Context): Unit | GAM · 激励 |
preloadPangle(context: Context): Unit | Pangle · 普通原生 + 插页 |
preloadPangleInterstitial(context: Context): Unit | Pangle · 插页 |
preloadPangleNative(context: Context): Unit | Pangle · 普通原生 |
preloadPangleFullScreenNative(context: Context): Unit | Pangle · 全屏原生 |
preloadPangleRewarded(context: Context): Unit | Pangle · 激励 |
preloadTopOn(context: Context): Unit | TopOn · 普通原生 + 插页 |
preloadTopOnInterstitial(context: Context): Unit | TopOn · 插页 |
preloadTopOnNative(context: Context): Unit | TopOn · 普通原生 |
preloadTopOnFullScreenNative(context: Context): Unit | TopOn · 全屏原生 |
preloadTopOnRewarded(context: Context): Unit | TopOn · 激励 |
Risk 版另提供 preloadMax / preloadMaxInterstitial / preloadMaxNative / preloadMaxFullScreenNative / preloadMaxRewarded,参数均为 context: Context,返回 Unit;其中 preloadMax 加载普通原生 + 插页。
这些入口按平台开关、运行时配置和初始化状态决定是否发起请求。该控制类没有单平台公开开屏函数,也没有 Banner 预加载函数;preloadAll 不包含开屏、激励、全屏原生。固定平台选择不会把 preloadAll 缩减为一个平台。
// 只预加载插页(按接入平台选择)
PreloadController.preloadAdmobInterstitial(application)
PreloadController.preloadTopOnInterstitial(application)
// 如使用激励:
PreloadController.preloadAllRewarded(application)包名:com.android.common.bill.ads.frequency.AdFrequencyController。6 个公开函数均同步查询,不增加展示 / 点击计数,不上报竞价排除事件。
| 公开函数 | 返回值 / 用途 |
|---|---|
getPlatformFrequencyStatus(adType: AdType, platform: AdPlatform): AdFrequencyStatus | 查询单平台每日次数、剩余额度和最小间隔;不合并总控。 |
getTotalFrequencyStatus(adType: AdType): AdFrequencyStatus | 查询类型总控:每日展示 / 点击限制,不检查最小间隔。 |
getFrequencyStatus(adType: AdType): AdFrequencySnapshot | 同时返回 totalStatus 与所有平台的 platformStatuses。 |
isPlatformFrequencyAllowed(adType: AdType, platform: AdPlatform): Boolean | 单平台频次是否通过。 |
isTotalFrequencyAllowed(adType: AdType): Boolean | 总频次是否通过。 |
getFrequencyAllowedPlatforms(adType: AdType): List<AdPlatform> | 总控通过后,返回平台频次也通过的列表;总控不通过返回空列表。 |
查询只描述频次,不判断广告源是否启用、初始化是否成功或有无缓存;因此 isAllowed / canShow() 不代表此刻必然能展示。
| 返回对象 | 常用字段 / 方法 |
|---|---|
AdFrequencyStatus | isAllowed / blockReason / blockReasonKey;dailyShowCount / maxDailyShow / remainingShowCount;dailyClickCount / maxDailyClick / remainingClickCount;lastShowIntervalSeconds / minIntervalSeconds / remainingIntervalSeconds。canShow()、canBid() 均返回 isAllowed。 |
AdFrequencySnapshot | totalStatus / platformStatuses / isTotalAllowed / allowedPlatforms。 |
| 阻断原因 | none / config_unavailable / show_limit_exceeded / click_limit_exceeded / interval_not_met。 |
| 时间单位 | 均为秒;lastShowIntervalSeconds 为 -1 表示没有上次展示记录(总控查询也使用 -1)。 |
val snapshot = AdFrequencyController.getFrequencyStatus(AdType.INTERSTITIAL)
val admob = snapshot.platformStatuses[AdPlatform.ADMOB]
val frequencyAllowed = snapshot.isTotalAllowed && admob?.isAllowed == true
val waitSeconds = admob?.remainingIntervalSeconds
val reason = admob?.blockReasonKey包名:com.android.common.bill.ads.bidding.AdCacheStatusController。5 个公开入口(包含重载),查询已有缓存,不消费广告或触发加载。
| 公开函数 | 返回值 / 用途 |
|---|---|
hasAvailableCache(adType: AdType): Boolean | 按当前聚合源检查:固定源只查该平台,BIDDING 查所有候选平台。 |
hasAvailableCache(adType: AdType, platform: AdPlatform, adUnitId: String? = null): Boolean | 直接检查指定平台;adUnitId 省略时使用 BillConfig 对应类型的 ID。Risk 1.0.15 的 AdMob 多 ID 模式下,省略时检查当前配置列表的任意有效缓存。 |
getAvailableCachePlatforms(adType: AdType): List<AdPlatform> | 当前聚合源下,具有可用缓存的平台列表。 |
getPlatformCacheStatuses(adType: AdType): List<PlatformCacheStatus> | 当前聚合源下各候选平台的状态列表。 |
getPlatformCacheStatus(adType: AdType, platform: AdPlatform, adUnitId: String? = null): PlatformCacheStatus | 指定平台的完整缓存状态,显式传入的 ID 用于缓存查找。 |
PlatformCacheStatus 包含 adType / platform / platformAvailable / hasCache / blockReason;计算属性 hasAvailableCache = platformAvailable && hasCache。platformAvailable 检查平台配置、初始化和平台频控;缓存命中仍不等于通过总控或所有展示前置条件。
blockReason 可能为 platform_unavailable、no_cache,或带详情的频控原因。查询为即时快照,实际展示仍会再次判断。频控达到硬上限时,内部检查可能停止 Google 预加载。
val status = AdCacheStatusController.getPlatformCacheStatus(
AdType.INTERSTITIAL, AdPlatform.ADMOB
)
val ready = AdFrequencyController.isTotalFrequencyAllowed(AdType.INTERSTITIAL) &&
status.hasAvailableCache
val reason = status.blockReason包名:com.android.common.bill.ads.bidding.AdSourceController。选择会持久化,默认 AdSource.BIDDING;枚举还有 ADMOB / GAM / PANGLE / TOPON;Risk 版另有 MAX。
| 公开函数 | 返回值 / 用途 |
|---|---|
getCurrentSource(): AdSource | 读取当前选择,缺失或非法值回退 BIDDING。 |
setCurrentSource(source: AdSource): Unit | 保存选择;传 BIDDING 恢复竞价。 |
getSourceDisplayName(source: AdSource): String | 取得用于显示的名称。 |
getAllSources(): List<AdSource> | 普通 / 预加载版返回 5 个选项,Risk 版增加 MAX 共 6 个;并非当前已初始化 / 可用的平台列表。 |
showAdSourceSelection(context: Context, onSourceChanged: () -> Unit = {}): Unit | 显示选择弹层;用户选择后自动保存并回调。context 使用可承载弹层的 Activity。 |
checkFixedSource(adType: AdType): FixedSourceCheckResult | 检查固定源的平台启用、初始化与平台频控;返回 UseFixedSource(winner) 或 UseBidding。 |
普通 / 预加载版固定源不可用时允许回退竞价。support_risk_1.0.20 严格使用固定源,不可用则结束本次请求,不转给其他平台;该版本的 checkFixedSource 已是 SDK 内部接口,业务使用上面的公开选择 / 查询方法。此检查不判断缓存;仅查询频次时使用 AdFrequencyController。
AdSourceController.setCurrentSource(AdSourceController.AdSource.TOPON)
val selected = AdSourceController.getCurrentSource()
AdSourceController.showAdSourceSelection(activity) {
val label = AdSourceController.getSourceDisplayName(
AdSourceController.getCurrentSource()
)
}
// 调试结束恢复竞价:
AdSourceController.setCurrentSource(AdSourceController.AdSource.BIDDING)清单依据当前发布版本中实际启用的依赖:普通版 1.0.58、LCB / IAA 1.0.54 系列、默认预加载版 1.0.58_preloading.14、短剧 1.0.56_preloading.11.drama、Risk support_risk_1.0.20。宿主通常无需重复声明这些适配器;广告平台后台的应用、广告位与聚合关系仍需配置。
前三组为上述版本共用;MAX 仅 Risk 版内置。某个网络 SDK 被其他聚合引入,并不等于当前聚合已经包含该网络的适配器。
共用 Google Next-Gen ads-mobile-sdk:1.2.1。
| 广告网络 | 已内置的适配器坐标 |
|---|---|
| Meta / Facebook | com.google.ads.mediation:facebook:6.21.0.2 |
聚合 SDK:com.pangle.global:pag-sdk-m:8.1.6.8。
| 广告网络 | 已内置的适配器坐标 |
|---|---|
| Mintegral | com.pangle.global:mintegral-adapter:16.9.91.1 |
Pangle 的 AdMob / Google Ad Manager 适配器目前未启用。
聚合 SDK:com.thinkup.sdk:core-tpn:6.6.40,已内置以下 13 个网络适配器。
| 广告网络 | 已内置的适配器坐标 |
|---|---|
| TuADX / SDM | com.thinkup.sdk:adapter-tpn-sdm:6.5.79.1.0 |
| Liftoff / Vungle | com.thinkup.sdk:adapter-tpn-vungle:7.7.3.1.1 |
| Bigo | com.thinkup.sdk:adapter-tpn-bigo:5.9.0.1.1 |
| Pangle | com.thinkup.sdk:adapter-tpn-pangle:8.1.0.3.1.0 |
| Meta / Facebook | com.thinkup.sdk:adapter-tpn-facebook:6.21.0.1.1 |
| Google Next-Gen | com.thinkup.sdk:adapter-tpn-gma-next-gen:1.2.1.1.0 |
| Mintegral | com.thinkup.sdk:adapter-tpn-mintegral:17.1.61.1.1 |
| ironSource | com.thinkup.sdk:adapter-tpn-ironsource:9.2.0.1.2 |
| Kwai | com.thinkup.sdk:adapter-tpn-kwai:1.2.21.1.2 |
| DT Exchange / Fyber | com.thinkup.sdk:adapter-tpn-fyber:8.4.2.1.2 |
| Moloco | com.thinkup.sdk:adapter-tpn-moloco:4.10.1.1.0 |
| Unity Ads | com.thinkup.sdk:adapter-tpn-unityads:4.18.0.1.0 |
| Chartboost | com.thinkup.sdk:adapter-tpn-chartboost:9.12.0.1.1 |
另带 Tramini 辅助插件 6.5.73。Chartboost 同时引入 chartboost-sdk 9.12.0、chartboost-mediation-sdk 5.3.0、chartboost-core-sdk 1.1.0 及 chartboost-mediation-adapter-chartboost 5.9.11.0.0。
仅 support_risk_1.0.20 聚合 SDK:com.applovin:applovin-sdk:13.6.4。
| 广告网络 | 已内置的适配器坐标 |
|---|---|
| Mintegral | com.applovin.mediation:mintegral-adapter:17.1.61.0 |
| DT Exchange / Fyber | com.applovin.mediation:fyber-adapter:8.4.2.0 |
| Moloco | com.applovin.mediation:moloco-adapter:4.10.1.0 |
MAX 的 Google / Pangle 等其他网络适配器目前未内置。这里列的是 Bill 随包依赖,不包含短剧等宿主项目单独添加的适配器。
宿主可根据自己的风控或业务判断,全局屏蔽广告或只屏蔽指定平台。无需先初始化广告,也不依赖 Risk 插件;默认不屏蔽。
main · DEFAULT / LCB / IAA · Preloading 默认 / Drama
当前对应版本:1.0.58、1.0.54.lcb、1.0.54.iaa、1.0.58_preloading.14、1.0.56_preloading.11.drama。Risk 版使用另一套 AdRisk.updatePlatformRestriction 屏蔽接口,作用范围及解除规则见该页。
import com.android.common.bill.ads.interceptor.ExternalAdBlockController
// 发起风控检查前设置;拒绝时保持屏蔽
ExternalAdBlockController.setBlocked(true)
// 查询全局开关
val globallyBlocked = ExternalAdBlockController.isBlocked()
// 风控通过后解除,再按业务流程初始化和展示
ExternalAdBlockController.setBlocked(false)
import com.android.common.bill.ads.config.AdPlatform
import com.android.common.bill.ads.interceptor.ExternalAdBlockController
// 仅屏蔽 AdMob,其他未屏蔽平台仍可参与
ExternalAdBlockController.setPlatformBlocked(AdPlatform.ADMOB, true)
// 查询平台实际屏蔽状态(包含全局屏蔽)
val admobBlocked = ExternalAdBlockController.isPlatformBlocked(AdPlatform.ADMOB)
// 解除 AdMob 的单平台屏蔽
ExternalAdBlockController.setPlatformBlocked(AdPlatform.ADMOB, false)
| 公开方法 | 含义 |
|---|---|
setBlocked(blocked: Boolean): Unit | 设置全局开关;false 不会清除已经设置的单平台开关。 |
isBlocked(): Boolean | 只返回全局开关;false 不代表所有平台都已放开。 |
setPlatformBlocked(platform: AdPlatform, blocked: Boolean): Unit | 设置指定平台的独立开关;可用平台为 ADMOB、GAM、PANGLE、TOPON。 |
isPlatformBlocked(platform: AdPlatform): Boolean | 返回全局开关与该平台开关合并后的实际屏蔽状态。 |
开关仅在当前进程内有效,线程可见,重启后需要宿主重新设置。全局与单平台开关独立:若此前同时设置了二者,完全放开时需要分别解除。解除后仍受广告总开关、授权流程和频控等原有规则约束。
AdShowExt 六种展示入口:showAppOpenAd、showInterstitialAd、showRewardedAd、showNativeAdInContainer、showFullScreenNativeAdInContainer、showBannerAd。AppOpenBiddingInitializer 会跳过被屏蔽的平台;解除后,下次展示会补尝试此前跳过的初始化,也可以主动重新调用统一初始化入口。ADMOB 与 GAM,或使用全局屏蔽。因外部封控而直接失败时,除普通原生返回 false 外,其余展示入口返回 AdResult.Failure,错误码 -102、消息 外部主动封控;不触发加载完成或奖励回调。
| 情形 | 事件与字段 |
|---|---|
| 全局或全部候选平台被屏蔽 | 先上报 ad_position,再上报 ad_show_fail;二者使用相同 session_id / position,失败原因为 external_ad_blocked。不会产生该次请求的 ad_bid_fail。 |
| 实际进入竞价时排除部分平台 | 每个已配置启用且被屏蔽的平台上报一次 ad_bid_excluded,包含 ad_platform、ad_format、exclusion_type = external_ad_block、reason = external_ad_blocked,以及与后续竞价事件相同的 bid_id;传入的非空 position 也会携带。 |
埋点需要事先注册 ReportDataManager 上报器。缓存查询、初始化、预加载不会产生 ad_bid_excluded;未参与配置的平台、直接命中可用固定源或完全封控而未进入竞价的请求,也不会新增该事件。