Banner 广告

文档版本 v1.0.0

本页对应 SDK 1.0.0，与离线包 docs/ 目录里的同一份文档内容一致。其他版本见文档中心。

与另两种广告位最大的区别是它常驻页面并定时刷新，因此生命周期管理是必做项， 漏掉 destroy() 必然泄漏。

完整示例

ViewGroup container = findViewById(R.id.banner_container);

BannerAd bannerAd = new BannerAd("banner_main");
bannerAd.load(activity, container, new BannerAdListener() {
    @Override public void onAdLoaded(String adnType) { }   // 每次刷新都会回调，adnType 可能变
    @Override public void onAdLoadFailed(AdError error) { }
    @Override public void onAdShow()  { }
    @Override public void onAdClick() { }
    @Override public void onAdClose() { }   // 用户关闭后刷新自动停止
});

// Activity onDestroy 中 —— 不调必然泄漏
bannerAd.destroy();

要点：

• 广告 View 由 SDK 挂进 container，业务侧不需要自己 addView
• onAdLoaded 每次刷新成功都会回调，adnType 可能与上次不同
• onAdClose 表示用户点了广告自带的关闭按钮，此后刷新自动停止

onDestroy 必须调 destroy()

Banner 长期持有 Activity 引用，且定时器一直在转。页面 finish() 后不 destroy() 的后果是 内存持续上涨 + 曝光数虚高（广告还在刷新并上报曝光，而页面已经没了）。

刷新由聚合层驱动

刷新间隔由后台的 refresh_interval_sec 决定，每次刷新重走一整轮完整调度 （竞价、比价、竞胜 / 竞败回传一条不少），业务侧不需要任何干预。

两个适配器都显式关掉了广告平台自带的刷新（穿山甲 setSlideIntervalTime(0)、 优量汇 setRefresh(0)）。不这样做的后果是广告位会永远锁死在最初中标的那一家，聚合失去意义。

广告平台后台的 Banner 自动刷新也要关掉

两边都开会重复计费曝光，也会打乱聚合比价。这一项由平台运营在广告平台后台确认。

新旧广告交替时，SDK 先挂新广告再销毁旧的 —— 反过来会有空白闪烁。

尺寸规格

Banner 广告位有尺寸规格，必须与广告平台后台建广告位时选的规格一致， 否则报 40006 广告位ID不合法，或者拿到一条比例怪异的素材。

向平台运营申请 Banner 广告位时必须同时说清尺寸，运营在后台配置 width_dp / height_dp 与广告平台侧的规格对齐。

缓存

Banner 只有首次 load() 会取缓存，定时刷新一律实时请求、不自动补位。 配置未下发 cache_size 时 Banner 默认为 0（不缓存）—— 缓存只对首屏有价值。

Kotlin 写法

private var bannerAd: BannerAd? = null

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_banner)
    val container: ViewGroup = findViewById(R.id.banner_container)

    bannerAd = BannerAd("banner_main").also { ad ->
        ad.load(this, container, object : BannerAdListener {
            // 每次定时刷新成功都会回调，adnType 可能与上次不同
            override fun onAdLoaded(adnType: String) {}
            override fun onAdLoadFailed(error: AdError) {}
            override fun onAdShow() {}
            override fun onAdClick() {}
            override fun onAdClose() {}    // 用户关闭后刷新自动停止
        })
    }
}

override fun onDestroy() {
    // Banner 常驻页面且定时刷新，不 destroy 的话页面 finish 后定时器还在转：
    // 内存持续上涨 + 曝光数虚高
    bannerAd?.destroy()
    super.onDestroy()
}

验证刷新是否正常

停在 Banner 页看 2~3 个刷新周期，确认无空白、无闪烁、内存不持续上涨。

刷新后「看着没变」通常不是故障

测试广告位的素材池小且风格雷同，肉眼看着像没变，实际已经换了一条。 用刷新计数（onAdLoaded 回调次数）确认，不要靠肉眼。

穿山甲 Banner 在 GroMore 模式下是一段式：适配器拿到非空的 ExpressAdView 才算填充， 拿不到 View 视为无填充并让聚合层继续下探。所以填充判定点是「渲染成功」而不是「加载成功」， 不会出现「竞价赢了却渲染失败、广告位空着」。