优聚智汇

English

简体中文

English

简体中文

Theme

iOS Banner Ad Integration ​

Overview ​

Banner ads are rectangular ads displayed at the top or bottom of the app interface, with the following characteristics:

  • Small footprint, does not affect user experience
  • Continuous display, increasing ad exposure
  • Fast loading, responsive
  • Suitable for various app scenarios

Banner ads need to be displayed through a container view (container: UIView).

Integration Steps ​

1. Create and Load Banner Ad ​

swift
import UIKit
import UjuAdCore

final class BannerAdHelper {
    private var bannerAd: UjuAdObject?

    func load(vc: UIViewController) {
        // 创建广告配置，指定广告位 ID 与广告尺寸
        let config = UjuAdConfig(
            placementId: "YOUR_BANNER_PLACEMENT_ID",
            adViewSize: AdViewSize.bannerSize320x50  // 320x50
        )
        let banner = UjuAdObject.getBannerObject(vc, config: config)
        banner.setAdObjectListener(BannerListener(helper: self))
        self.bannerAd = banner
        banner.load()
    }

    func show(vc: UIViewController, container: UIView) {
        // 展示前判断 isReady，需传入承载横幅的容器视图
        if bannerAd?.isReady() == true {
            bannerAd?.show(vc, container: container)
        }
    }

    func destroy() {
        bannerAd?.destroy()
        bannerAd = nil
    }
}

2. Implement Banner Listener ​

swift
final class BannerListener: FeedAdObjectListener, @unchecked Sendable {
    private weak var helper: BannerAdHelper?

    init(helper: BannerAdHelper) { self.helper = helper }

    func onLoadSuccess() {
        // 加载成功，可在合适时机调用 show(vc, container:)
    }

    func onLoadError(error: UjuException) {
        print("横幅加载失败: \(error.description)")
    }

    func onAdShow() {
        // 通过 getAdInfo() 获取广告信息，读取 ecpm
        // let ecpm = helper?.bannerAd?.getAdInfo()?.ecpm
    }

    func onAdClicked() {
        // 广告被点击
    }

    func onAdClosed() {
        // 广告关闭
    }

    func onLpClosed() {
        // 落地页关闭
    }

    func onAdError(error: UjuException) {
        print("横幅展示错误: \(error.description)")
    }
}

UjuAdConfig Configuration ​

ParameterTypeRequiredDescription
placementIdStringYesAd placement ID
adViewSizeAdViewSize?NoAd size, only effective for template rendering, default nil
scenarioKeyString?NoAd display scenario identifier, used for analytics
userIdString?NoUser ID
customData[String: String]?NoCustom data, passed through to the ad server
bidFloorDoubleNoBid floor (CNY, CPM), passed by aggregation platform, not needed for normal integrators

Ad Sizes ​

The UjuAd iOS SDK provides the following preset banner sizes (AdViewSize static properties, in pixels):

Preset PropertyWidth × HeightDescription
AdViewSize.bannerSize320x50320 × 50Standard banner (recommended)
AdViewSize.bannerSize320x100320 × 100Large banner
AdViewSize.bannerSize320x75320 × 75Smart banner

To customize the size, construct directly:

swift
let customSize = AdViewSize(width: 300, height: 250)

For the complete AdViewSize presets (including Native sizes), see API Reference.

Best Practices ​

1. Ad Placement ​

  • Bottom placement: The most common position, does not obscure main content
  • Top placement: Suitable for certain specific app scenarios
  • Between content: Interspersed in long articles or lists

2. Optimization Recommendations ​

  • Preload ads: Load in advance before needing to display ads
  • Handle network status: Adjust loading strategy appropriately when network is poor
  • Test different sizes: Choose the appropriate ad size based on your app interface

3. Issues to Avoid ​

  • Do not place multiple banner ads on the same screen
  • Do not obscure core app functionality
  • Do not place ads in areas with frequent user interaction

FAQ ​

Q: Why doesn't the banner ad show? ​

A: Possible causes:

  • Incorrect ad placement ID
  • Network connection issues
  • Insufficient ad inventory (error code 102 noFill)
  • Container view is not visible or has zero size
  • Did not call show(vc, container:) after onLoadSuccess

Q: Can banner ads be used in UITableView/UICollectionView? ​

A: Yes, but note:

  • Manage the ad view lifecycle in cells
  • Properly handle destroy() for ad objects to avoid memory leaks
  • Avoid frequent creation and destruction of ad views