ReMaxDeveloper Docs
DOCUMENTATION / GET STARTED

广告库接入 SOP

添加依赖 → 配置日志与渠道 → 初始化广告源 → 注册回调 → 授权与预加载 → 展示广告。

LCB / IAA / DRAMA / RISK

依赖版本 · 完整 Maven 坐标

添加 Core,并按业务选择一个 Bill 版本。同一 App 不要同时依赖多个 Bill 版本。

标准版本STANDARD

通用广告聚合与展示,按业务选择默认版或专用混淆变体。

LCB / IAA 当前仍为 1.0.54;具体能力差异见下表。

查看接入说明 →
更新
预加载版本PRELOADING

支持 Google 官方预加载、在线缓存容量配置与 AdMob 内容定向。

默认版已补齐失败埋点;Drama 保持 .11,本次未发布。

查看接入说明 →
更新
风控版本RISK

支持 AdMob 多 ID、MAX 聚合,可按需接入风控插件。

Bill 可独立使用;引入 ad-risk 后启用风控能力。

查看接入说明 →
更新
三类产品线按需选择 · 移入拼合 · 移出解构
CORE / 共用com.github.toukaremax:core:1.0.15搭配任一 Bill 版本
COMPARE / 06 EDITIONS

版本能力,一眼对比

每列一个已发布版本,每行一项能力。按需求横向选择,点击能力名称查看接入说明。

✓ 支持— 当前版本不支持✓ 可选:需要额外依赖13 项差异 · 已收起 4 项共同能力
六种已发布 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 默认
两种预加载能力的区别所有版本都可调用 PreloadController 提前加载。表中的「官方预加载」专指 Google Preloader 的在线模式开关与缓存容量配置。
Risk 的风控是可选能力Bill 本身可独立使用;接入 ad-risk:1.0.8 后才启用风控插件。接入说明 ↗ · 平台屏蔽 API ↗
RELEASE NOTES / RECENT

近期版本,改了什么

按产品线保留最近 4–5 个版本,展开查看逐版变更。范围以各行说明为准,升级时选择该产品线的当前版本。

标准版本STANDARD · 近 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 埋点修复。

预加载版本PRELOADING · 近 5 个版本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,也不包含本次埋点修复。

风控版本RISK · 近 5 个版本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。

STEP 01添加仓库与下载鉴权

基础要求:Android minSdk 26、Java / JVM 17;SDK 源码使用 compileSdk 36。先配置 Maven 源与下载凭据,再添加 Core 和一个 Bill 版本,最后检查宿主清单的 HTTP 配置。

SDK 与广告依赖的 Maven 源

以下配置参考 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 与阿里云条目沿用参考项目的其他依赖 / 镜像源,可按宿主实际依赖保留。

下载凭据:环境变量或 local.properties

使用具备目标包读取权限的 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,其他产品线见依赖版本。

宿主清单:覆盖并允许明文 HTTP

参考 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 + ad-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")

2026-11-12 · 失败埋点补齐与回调兼容

  • 已发布默认版 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;埋点与宿主失败回调不保证一一对应。进程退出、上报丢失或仍未结束的请求不保证实时严格相等。
  • 普通版 164 项、预加载版 420 项、Risk 474 项 Bill 单元测试及 Release 构建通过,远端 AAR 与本地哈希一致;本次未新增真机验证。Risk 保留多 ID、REQUEST / SHOW 门禁、重新竞价及 MAX 原有取消和回调语义。

2026-11-06 · 迁移兼容性复查与修复

  • 已发布默认预加载版 1.0.57_preloading.13 与 Risk support_risk_1.0.19;当前版本已包含这些修复。
  • Preloading:修复主广告无库存、插屏准入全部拒绝时,将 NONE 误当作可改道结果的问题。确认准入判断不会取走或清空 AdMob / GAM 官方预加载队列,后续放行仍可使用原库存。
  • Risk:选胜出 ID 前重新检查 REQUEST / SHOW 门禁,避免展示风控变化后重新竞价仍选回受限 ID;竞价模式下 AdMob 平台被限制后可回退 MAX 等可用平台。保留固定源、单 ID 展示时加载、多 ID 精确消费及全屏原生不接入行为风控的规则。
  • 重新竞价保留风控拦截与宿主拒绝的准确原因,由展示入口统一发送一次失败通知。MAX Banner 挂载失败时先清理广告和跟踪,再通知宿主,避免处理迟到回调。
  • Risk support_risk_1.0.19 另补齐 REQUEST 门禁拦截全部 ID 时的早退原因,包括固定多 ID 路径;这是已发布 support_risk_1.0.18 的补充修复。此时保留 ad_risk_blocked,不误报无平台或宿主拒绝。
  • Preloading 361 项、Risk 425 项 Bill 单元测试及 Release 构建通过,远端 Maven 包与公开回调接口已核验。本次未新增真机验证。Drama、普通版、LCB / IAA、Core 与 ad-risk 版本均未改变。

2026-11-06 · Preloading / Risk 迁移三个全局回调

  • 已发布默认预加载版 1.0.57_preloading.12 与 Risk support_risk_1.0.17;均支持 canSourceShow、onAdBeforeShow、onAdShowFailed。三个接口默认 null。
  • Preloading 保留官方预加载、可用广告对象筛选及素材 / 内容定向。Risk 覆盖 MAX 六类广告,并保留 AdMob 多 ID、固定源规则与风控桥接。
  • Preloading 351 项、Risk 393 项 Bill 单元测试及 release 构建通过;Maven 下载产物与公开回调接口已核验。本次未新增真机验证。
  • 本次预加载仅发布 default 产品线;Drama 保持 1.0.56_preloading.11.drama。普通版 1.0.57、LCB / IAA 1.0.54、Core 1.0.15 和 ad-risk 1.0.8 保持不变。

2026-11-06 · 竞价筛选、展示前与失败回调

  • 已发布默认版 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,未配置时保持原有流程。
  • 106 项 Bill 单元测试、release 构建和发布 AAR 接口检查通过;本次未新增真机验证。
复制当前默认版 1.0.58 依赖
implementation("com.github.toukaremax:core:1.0.15")
implementation("com.github.toukaremax:bill:1.0.58")

2026-11-03 · 全局广告开始展示回调

  • 已发布:默认版 1.0.56、默认预加载版 1.0.56_preloading.11、Drama 1.0.56_preloading.11.drama、Risk support_risk_1.0.16。
  • 新增可选 BillConfig.onAdOpened。未配置时不执行新增参数读取;平台 getter 与宿主回调异常均隔离,读取失败仍携带基础广告信息通知。
  • AdMob / GAM / TopOn / Pangle 覆盖六类广告;Risk MAX 覆盖激励、插页、开屏和自定义全屏原生,普通原生 / Banner 不使用收益兜底。各类型触发函数与参数说明。
  • LCB / IAA 继续使用 1.0.54.lcb / 1.0.54.iaa,未发布升级。Core 1.0.15 与 ad-risk 1.0.8 均未修改、未发布。

2026-11-02 · Risk AdMob 多 ID

  • Risk 更新为 support_risk_1.0.15:AdMob 开屏、插页、激励、原生及全屏原生支持单字符串或多 ID 数组;Banner 继续使用单字符串。
  • 多 ID 并发加载、内部竞价、消费后定向补充;单 ID 保留原有链路。支持在线和代码配置,以及单 / 多 ID 双向覆盖;补齐手动配置接口的发布混淆保留规则。配置示例与生效规则。
  • 其他 Bill 产品线、Core 1.0.15、ad-risk 1.0.8 保持不变;GMA Next-Gen 与反射配置仍为 1.2.1。

2026-10-22 · 全局关闭与获奖回调

  • 本次发布:默认版 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 事件。
  • LCB / IAA 仍为 1.0.54.lcb / 1.0.54.iaa,本次未发布升级,尚不包含新增的两个全局回调。Core 1.0.15、ad-risk 1.0.8 保持不变。

2026-10-22 · 明文流量与版本约束更新

  • 普通默认版 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。
  • 以上六个新版本在 Bill Manifest 中声明 android:usesCleartextTraffic="true",并引用 @xml/remax_bill_network_security_config,其中 <base-config cleartextTrafficPermitted="true" /> 默认允许所有域名的 HTTP 明文流量。
  • 配置合并生效后作用于整个宿主 App;HTTPS 请求仍走 HTTPS。宿主未设置这些属性时通常直接合入,无需重复添加。
  • 预加载版取消 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;取消锁定不代表其他版本已验证兼容。
  • Risk 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 网络安全配置。

2026-10-20 · 外部封控与排除埋点更新

  • 普通版 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 记录原因。
  • 预加载版保留原有加载模式、素材埋点及无填充回退逻辑。LCB、IAA、Risk 的已发布版本保持不变。

2026-10-15 · 全屏广告素材埋点更新

  • 默认预加载版 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。
  • AdMob 插页、激励、开屏的展示与点击事件支持尽力提取标题、描述和主图 URL;原生与全屏原生沿用公开 API。查看字段、已验证模板与限制。
  • 只上报实际取得的非空字段;没有素材信息时,原有事件、内容定向及广告流程继续工作。每次展示解析一次,展示与点击共用结果。
  • 默认版与 Drama 版业务逻辑相同,仅内部混淆命名不同;Risk 保留原有加载、MAX 和风控接入能力。
复制默认预加载版依赖
implementation("com.github.toukaremax:core:1.0.15")
implementation("com.github.toukaremax:bill:1.0.58_preloading.14")
复制 LCB / IAA 依赖示例(按产品线二选一)

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)。

STEP 02设置日志与用户渠道

在 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 受首次设置状态约束。渠道决定使用自然 / 买量广告策略。

STEP 03配置广告源并初始化

在主进程协程中调用一次,等待返回后再预加载或展示。下面按已有接入方式列出四个平台;用实际 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,仍需填写广告位和渲染配置。初始化返回表示流程结束,单个平台失败会记录日志,不代表所有平台都有可展示广告。

原生 / 全屏原生 / Loading 样式

使用原生广告前,实现并注入对应平台 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 未配置时跳过加载弹框。

STEP 04注册全局广告回调与统一上报

将所需回调合并到第 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 都会执行,业务发奖只选择一处;提前关闭、播放结束或失败不补发奖励。宿主全局回调异常会被隔离。
  • 关闭跟随平台关闭事件;Banner / 原生的全屏内容关闭也可能触发,不等于广告 View 已销毁。主动销毁、过期或加载失败不补发关闭。
  • MAX 仅 Risk 版支持:关闭覆盖开屏、插页、激励、全屏原生页面,以及 Banner 展开后收起;普通原生没有对应关闭事件。MAX 收益币种为 USD。
  • Google 回调收益跟随本次广告 / 展示,未收到收益时为 0;TopOn 优先使用 publisherRevenue,仅为 null 时用 ecpm / 1000,明确的 0 保留。币种跟随 SDK,缺失时兜底 USD,不进行汇率换算。这些取值修复也作用于内部上报。

广告开始展示 · onAdOpened

BillConfig.onAdOpened: ((RevenueAdData) -> Unit)? 默认 null;设置监听才读取新增参数并通知,设置 null 可取消。同步运行于触发线程,参数读取和宿主回调异常均被隔离,保持既有曝光、收益、点击、关闭、奖励及风控流程。

广告类型AdMob / GAMTopOnPangleMAX(仅 Risk)
激励 · RewardedonAdShowedFullScreenContentonRewardedVideoAdPlayStartonAdShowedonAdDisplayed
插页 · InterstitialonAdShowedFullScreenContentonInterstitialAdShowonAdShowedonAdDisplayed
开屏 · SplashonAdShowedFullScreenContentonAdShowonAdShowedonAdDisplayed
普通原生 · NativeonAdImpressiononAdImpressedonAdShowed不触发;不使用收益兜底
BanneronAdImpressiononBannerShowonAdShowed不触发;不使用收益兜底
全屏原生 · FullNativeonAdImpressiononAdImpressedonAdShowed自定义视图成功绑定后的展示通知
  • 开始展示不是新增收益,也不等于视频首帧或播放完成;不保证先于收益通知。Google / TopOn / Pangle 跟随对应平台事件,Banner 刷新展示可再次触发。MAX 三类 SDK 全屏广告对同一次展示的重复打开通知去重;全屏原生的自定义视图绑定不代替 SDK 曝光确认。
  • 收益为触发时已知值,未取得时为 0。新增参数读取失败时,保留平台、广告类型和广告位;广告源名回退平台名、广告源 ID 回退广告位 ID,收益为 0、币种及 placement 为空字符串。此异常兜底只针对新打开回调。
  • data.adFormat 是字符串:Rewarded / Interstitial / Splash / Native / Banner / FullNative。可使用 AdType.fromConfigKey(data.adFormat) 转为枚举;未知值为 null。本次版本保留 AdType 和 AdType.Companion 的发布及宿主混淆规则。
  • 多个回调可按 platform + adFormat + adRevenueUnit 判断来自哪个平台、类型和广告位;RevenueAdData 没有单次展示唯一 ID,不能据此严格区分同广告位的连续或并发展示。
  • 直接读取公开属性即可;示例 JSON 的键名由宿主显式指定。本次未修改 Core 数据结构或 private 字段混淆规则,不保证通过反射字段名或直接反射序列化得到同名键。
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) {
        // 激励广告已开始展示;不在这里发放奖励。
    }
}

竞价候选准入 · canSourceShow

默认版 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 竞价管理器为内部实现。
  • 没有平台参与竞价时仍走原有提前失败分支,不调用这个函数。默认预加载版的开屏 / 插页 / 激励仅询问有可用广告对象的平台,无库存仍返回 null winner;Risk 保留单 ID 展示时加载兜底,多 ID 仅使用实际取得的候选。
  • 固定源快捷路径、直接传入的 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 的准确失败原因。全屏原生沿用既有行为风控豁免。

传给业务的 data · RevenueAdData

沿用其他回调的类型,无需增加入参。以下为候选 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 仍保留在埋点中。
adFormatSplash / Interstitial / Rewarded / Native / FullNative / Banner。

调用展示前通知 · onAdBeforeShow

默认版 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。
    // 此时即将调用平台展示操作,不保证后续展示成功。
}
  • 开屏、插页、激励在现有就绪检查通过后、SDK show 前通知;原生 / 全屏原生在取得广告后、绑定前通知;Banner 在 View 准备好后、挂载或绑定前通知。
  • data 携带平台、类型和广告位,收益为 0,币种及 placement 为空;网络名 / 广告源 ID 分别回退为平台名 / 广告位 ID。
  • 这是通知接口,没有准入返回值;不增加曝光或收益事件。纯加载、提前拦截、无可用广告、未通过就绪检查不触发。Banner 平台自行刷新产生的曝光不补发此通知。
  • 每次实际展示操作前同步通知;后续 SDK 抛异常或展示失败不撤回通知。宿主回调异常被隔离,默认 null;与平台确认后的 onAdOpened 相互独立。

展示会话失败 · onAdShowFailed

默认版 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 判断本次会话失败原因。
}
  • 跟随 AdMob / GAM / Pangle / TopOn 及 Risk MAX 的现有展示失败路径,包括平台展示失败、加载失败导致无法展示、频控、封控、无可用平台及生命周期中断。纯预加载失败不触发;无需注册事件上报器。
  • 收益为 0,币种及 placement 为空;平台和广告位未知时为空字符串,网络名 / 广告源 ID 分别回退为平台名 / 广告位 ID。
  • 沿用会话终态去重:非空 sessionId 已记录曝光或失败后不再通知失败(最多缓存 2048 个会话);直接调用控制器但未传 sessionId 时不保证去重。默认 null,宿主回调异常被隔离。
  • 自默认版 1.0.58、默认预加载版 1.0.58_preloading.14、Risk support_risk_1.0.20 起,开屏 / 激励改道插页复用原会话,不因改道本身通知失败。终态埋点的 ad_format 保留入口类型,回调 data.adFormat 保留实际广告类型;整个调用结果以 show 返回值为准。

上述三个新版本新增的取消、销毁、失败返回或异常兜底只补齐埋点,不额外触发宿主失败回调。已有真实失败及生命周期失败通知仍走原路径;补偿层不会因 SDK 已提交后的单纯取消等待新增失败,各平台原有取消处理保留。请勿把 ad_show_fail 事件数量当作业务失败回调数量,或据此补发奖励。

业务回调对接关系

业务接口SDK 接入点
mmmobOnImpression(收益)onAdRevenue(data),只使用真实收益通知。
mmmobAdClickonAdClick(data)
mmmobCallAdShowonAdBeforeShow(data),表示即将尝试展示。
mmmobOnAdShowFailonAdShowFailed(data, reason),按宿主签名适配。
mmmobOnAdCloseonAdClose(data)
mmmobCanSourceShowcanSourceShow(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 定向事件使用。

STEP 06调用广告展示

需要先根据业务判断禁止展示时,使用 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 固定为插页。

REFERENCE 07在线参数配置

以下 Key 是 Firebase Remote Config 的逻辑参数名,值类型均为字符串,内容粘贴对应 JSON。大小写须保持一致。Core 支持加密 Key / 值;已配置加密参数时优先读取加密项,具体映射以宿主包名为准。

版本范围:通用广告配置适用于本页各 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 本身的广告能力。

REMOTE CONFIG · STRINGadRuntimeIdConfigJson

平台 ID / Key · 各版本通用,MAX 仅 Risk 版

覆盖初始化注入的广告源配置;非空字段生效,省略或空字符串保留已有配置。先应用缓存再读取在线值;BillConfig.skipRuntimeAdIdConfig=true 时跳过动态 ID。在线没有 max 节点时保留当前 MAX 配置(宿主注入值,或此前已应用的非空缓存值);max.sdkKey 是 AppLovin SDK Key,其他字段是对应广告位 ID。下面占位符须替换为实际配置,未接入的平台请省略。

AdMob 单 / 多 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"}}"""
)
  • 覆盖与生效:非空有效字段整体替换该类型的 ID 列表;单 ID 与多 ID 可双向覆盖。数组会去空白、去重并忽略非字符串项,无有效 ID 时保留此前配置。字符串、单元素数组和去重后仅一个 ID 均走原有单 ID 流程。
  • 生效时机:远程值成功获取并应用,或手动调用更新后,后续请求立即使用新配置,无需重启。后台修改不是实时推送;更新配置本身不立即触发新 ID 加载,后续预加载或广告请求才触发加载。手动更新同时保存配置缓存;skipRuntimeAdIdConfig=true 只跳过自动缓存 / 远程读取,不阻止手动更新。
  • 缓存切换:涉及多 ID 的列表变化会使该类型旧缓存失效,在后续访问时清理;旧请求晚到的结果丢弃,移除的 ID 不再补充。已在展示中的广告不被中断。
  • 加载与竞价:多 ID 并发加载;已有缓存时比较有效候选并后台补充缺失 ID,全无缓存时沿用原等待窗口。AdMob 内部按收益选出具体广告,再参与平台间竞价,固定 AdMob 模式也执行内部选择;未知价格按 0,平价按配置及缓存顺序选择。
  • 消费与兼容:取出多 ID 广告后只补充被消费的 ID,其他缓存保留;单 ID 保持原有加载取消、缓存查找、展示兜底与补充时机。Banner、其他平台 ID 字段类型及业务埋点语义保持不变。
加载日志与验证范围

用 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>"
  }
}

adConfigNaturalJson / adConfigPaidJson · 渠道广告策略

两份参数结构相同,分别用于 natural / paid 用户,各自存一个完整配置对象,不套 natural / paid 外层。示例包含 MAX,共开启五个平台,禁用 Banner;未接入的平台请显式改成 false。

字段配置参考与含义
app_open / interstitial / native / rewarded / banner开屏 / 插页 / 原生 / 激励 / Banner。全屏原生也读取 native 节点的配置,但按自己的广告类型独立计数。
bidding_platformsadmob、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 当成补丁合并。

REMOTE CONFIG · STRINGadConfigNaturalJson

自然量 · 完整示例(每日总展示 20、单平台 10)
{
  "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
  }
}
付费量 · 完整示例(每日总展示 40、单平台 20)
{
  "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
  }
}

REMOTE CONFIG · STRINGadmob_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 开关控制。

展开内容定向 JSON 示例
{
  "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 表示读取值与上次有效配置去除首尾空白后相同。

AD EVENTS · OPTIONAL FIELDS广告素材标题、描述与主图

Preloading .7 默认 / Drama · Risk 1.0.12 · AdMob

ad_impression 与 ad_click 按字段独立附加下列非空值;宿主无需增加配置。原生与全屏原生使用 Google 公开 API;插页、激励和开屏从当前广告对象取得 HTML,再解析已识别的素材模板。

字段类型含义
ad_creative_titleString素材模板提供的广告标题。
ad_creative_descriptionString素材模板提供的广告正文或描述。
ad_creative_image_urlString已识别的素材主图 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 字符时跳过;不会执行素材脚本或额外请求图片。素材获取失败不改变已有内容定向和埋点逻辑。

REMOTE CONFIG · STRINGAdmob_Preloading_Config

Preloading .7 默认 / Drama · AdMob / GAM

只控制 AdMob / GAM 的三种格式:IV 插页、RV 激励、SP 开屏。*_Preloading_Enable 为 1 时开启 GMA Preloading,0 走普通 Loading。*_Buffer_Size 是该格式的目标缓存数量,使用正整数;源码对非正数回退为 1,实际容量还受底层 SDK 额度约束。

示例:开启 AdMob 插页 / 激励 Preloading,其余保持普通 Loading
{
  "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 时保留缓存 / 已有本地配置。这里的模式开关与广告平台开关、展示频控分别生效。

REMOTE CONFIG · STRINGAd_Risk_Config

ad-risk:1.0.8 · 搭配 Bill support_risk_1.0.20

下方为随包默认配置:behavior_mode=2 表示观察,记录与上报行为但不执行行为风控拦截;0 关闭,1 执行。冷启动先读缓存 / Assets,再获取在线配置;有效远程值在获取后生效,空值或非法值保留当前配置。

展开 Risk 完整默认 JSON(行为风控 + 设备环境处置)
{
  "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。

REMOTE CONFIG · STRINGad_slot_switch

宿主广告位开关 · 完整示例

宿主主动调用 AdSlotSwitchController.isEnabled(position) 查询;AdShowExt 不自动检查此开关。自然分组名是 organic;未配置、未声明或解析失败默认关闭。

{
  "organic": {
    "APP_OPEN": true,
    "INTERSTITIAL": true
  },
  "paid": {
    "APP_OPEN": true,
    "INTERSTITIAL": true
  }
}

投放目标事件仍可通过 BillConfig.enableAdTargetEvents 显式开启,默认 false。

REFERENCE 08PreloadController · 预加载

四个控制类的示例共用下列类型:

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): UnitAdMob · 普通原生 + 插页
preloadAdmobInterstitial(context: Context): UnitAdMob · 插页
preloadAdmobNative(context: Context): UnitAdMob · 普通原生
preloadAdmobFullScreenNative(context: Context): UnitAdMob · 全屏原生
preloadAdmobRewarded(context: Context): UnitAdMob · 激励
preloadGam(context: Context): UnitGAM · 普通原生 + 插页
preloadGamInterstitial(context: Context): UnitGAM · 插页
preloadGamNative(context: Context): UnitGAM · 普通原生
preloadGamFullScreenNative(context: Context): UnitGAM · 全屏原生
preloadGamRewarded(context: Context): UnitGAM · 激励
preloadPangle(context: Context): UnitPangle · 普通原生 + 插页
preloadPangleInterstitial(context: Context): UnitPangle · 插页
preloadPangleNative(context: Context): UnitPangle · 普通原生
preloadPangleFullScreenNative(context: Context): UnitPangle · 全屏原生
preloadPangleRewarded(context: Context): UnitPangle · 激励
preloadTopOn(context: Context): UnitTopOn · 普通原生 + 插页
preloadTopOnInterstitial(context: Context): UnitTopOn · 插页
preloadTopOnNative(context: Context): UnitTopOn · 普通原生
preloadTopOnFullScreenNative(context: Context): UnitTopOn · 全屏原生
preloadTopOnRewarded(context: Context): UnitTopOn · 激励

Risk 版另提供 preloadMax / preloadMaxInterstitial / preloadMaxNative / preloadMaxFullScreenNative / preloadMaxRewarded,参数均为 context: Context,返回 Unit;其中 preloadMax 加载普通原生 + 插页。

这些入口按平台开关、运行时配置和初始化状态决定是否发起请求。该控制类没有单平台公开开屏函数,也没有 Banner 预加载函数;preloadAll 不包含开屏、激励、全屏原生。固定平台选择不会把 preloadAll 缩减为一个平台。

// 只预加载插页(按接入平台选择)
PreloadController.preloadAdmobInterstitial(application)
PreloadController.preloadTopOnInterstitial(application)
// 如使用激励:
PreloadController.preloadAllRewarded(application)

REFERENCE 09AdFrequencyController · 频次查询

包名: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() 不代表此刻必然能展示。

返回对象常用字段 / 方法
AdFrequencyStatusisAllowed / blockReason / blockReasonKey;dailyShowCount / maxDailyShow / remainingShowCount;dailyClickCount / maxDailyClick / remainingClickCount;lastShowIntervalSeconds / minIntervalSeconds / remainingIntervalSeconds。canShow()、canBid() 均返回 isAllowed。
AdFrequencySnapshottotalStatus / 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

REFERENCE 10AdCacheStatusController · 缓存查询

包名: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

REFERENCE 11AdSourceController · 固定平台

包名: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)

REFERENCE 12各聚合内置适配器

清单依据当前发布版本中实际启用的依赖:普通版 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 被其他聚合引入,并不等于当前聚合已经包含该网络的适配器。

01 / AdMob · GAM

共用 Google Next-Gen ads-mobile-sdk:1.2.1。

广告网络已内置的适配器坐标
Meta / Facebookcom.google.ads.mediation:facebook:6.21.0.2

02 / Pangle

聚合 SDK:com.pangle.global:pag-sdk-m:8.1.6.8。

广告网络已内置的适配器坐标
Mintegralcom.pangle.global:mintegral-adapter:16.9.91.1

Pangle 的 AdMob / Google Ad Manager 适配器目前未启用。

03 / TopOn

聚合 SDK:com.thinkup.sdk:core-tpn:6.6.40,已内置以下 13 个网络适配器。

广告网络已内置的适配器坐标
TuADX / SDMcom.thinkup.sdk:adapter-tpn-sdm:6.5.79.1.0
Liftoff / Vunglecom.thinkup.sdk:adapter-tpn-vungle:7.7.3.1.1
Bigocom.thinkup.sdk:adapter-tpn-bigo:5.9.0.1.1
Panglecom.thinkup.sdk:adapter-tpn-pangle:8.1.0.3.1.0
Meta / Facebookcom.thinkup.sdk:adapter-tpn-facebook:6.21.0.1.1
Google Next-Gencom.thinkup.sdk:adapter-tpn-gma-next-gen:1.2.1.1.0
Mintegralcom.thinkup.sdk:adapter-tpn-mintegral:17.1.61.1.1
ironSourcecom.thinkup.sdk:adapter-tpn-ironsource:9.2.0.1.2
Kwaicom.thinkup.sdk:adapter-tpn-kwai:1.2.21.1.2
DT Exchange / Fybercom.thinkup.sdk:adapter-tpn-fyber:8.4.2.1.2
Molococom.thinkup.sdk:adapter-tpn-moloco:4.10.1.1.0
Unity Adscom.thinkup.sdk:adapter-tpn-unityads:4.18.0.1.0
Chartboostcom.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。

04 / AppLovin MAX

仅 support_risk_1.0.20 聚合 SDK:com.applovin:applovin-sdk:13.6.4。

广告网络已内置的适配器坐标
Mintegralcom.applovin.mediation:mintegral-adapter:17.1.61.0
DT Exchange / Fybercom.applovin.mediation:fyber-adapter:8.4.2.0
Molococom.applovin.mediation:moloco-adapter:4.10.1.0

MAX 的 Google / Pangle 等其他网络适配器目前未内置。这里列的是 Bill 随包依赖,不包含短剧等宿主项目单独添加的适配器。

REFERENCE 13ExternalAdBlockController · 屏蔽广告

宿主可根据自己的风控或业务判断,全局屏蔽广告或只屏蔽指定平台。无需先初始化广告,也不依赖 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。
  • 全局屏蔽或当前请求的所有候选平台均被屏蔽时,新的展示请求直接失败;不会进行该次请求的竞价、loading 或其他广告类型兜底。开屏 / 激励启用插页竞价时,候选范围也包含插页。
  • 仅屏蔽部分平台时,会从竞价、固定源选择、缓存命中及统一预加载入口中排除这些平台,其他可用平台继续参与;不会仅因排除某个平台就让整次展示失败。旧插页竞价结果指向被屏蔽平台时会重新竞价。
  • 统一初始化 AppOpenBiddingInitializer 会跳过被屏蔽的平台;解除后,下次展示会补尝试此前跳过的初始化,也可以主动重新调用统一初始化入口。
  • 不会取消已经开始的 SDK 请求,也不会关闭已经展示的广告。直接调用底层平台 Manager / Controller 的请求由宿主控制。
  • 这里的平台是 SDK 的接入通道,不是第三方聚合内部的广告源。AdMob 与 GAM 共用 Google Mobile Ads SDK;若需同时屏蔽这两个通道,须分别设置 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;未参与配置的平台、直接命中可用固定源或完全封控而未进入竞价的请求,也不会新增该事件。