文档 · iOS 集成

5. 调用各类广告

每次调用仍需传入在 AKS 门户中配置的 placeholder 字符串——AKS 会在运行时将其解析为广告网络及故障转移列表。

5.1 桥接模式

AKS 的广告回调类型（AdsCallback、BannerCallback、NativeCallback、RewardedAdCallbacks、AppOpenAdCallbacks）都是需要继承并通过 override 重写方法的类，而不是闭包。惯用的实现模式（广泛用于 AppsKitSDKAdsManagerIOS 的调用方）是为每种广告格式创建一个小型私有适配器类，用于：

继承 AKS 回调类型，并调用 super.init()。
将各个生命周期事件转发给自己的 UI 层，按需处理。
对于横幅广告、原生广告和激励广告，由适配器自行串联加载→展示流程——即在重写的 onBannerLoaded()/onNativeLoaded()/onRewardedLoaded() 方法中触发相应的 show... 调用，并复用 self 作为展示阶段的回调对象。

swift

private class BannerCallbackAdapter: BannerCallback {
    private let onLoaded: () -> Void
    private let onFailed: (String) -> Void
    private weak var container: UIView?
    private let placeholder: String

    init(container: UIView, placeholder: String, onLoaded: @escaping () -> Void, onFailed: @escaping (String) -> Void) {
        self.container = container
        self.placeholder = placeholder
        self.onLoaded = onLoaded
        self.onFailed = onFailed
        super.init()
    }

    override func onBannerLoaded() {
        onLoaded()
        guard let vc = UIApplication.topViewController(), let view = container else {
            onFailed("No active view controller found")
            return
        }
        AppsKitSDKAdsManagerIOS.instance.showBanner(from: vc, placeholder: placeholder, container: view, callback: self)
    }
    override func onBannerFailedToLoad() { onFailed("") }
    override func onBannerClicked() {}
    override func onBannerShown() {}
    override func onBannerSizeChanged(bannerSizes: BannerSizes) {}
    override func setBannerSize(width: Double, height: Double) {}
}

UIApplication.topViewController()（由 AppsKit.xcframework 以 UIApplication 扩展的形式提供）会从主窗口的根视图控制器开始，逐层遍历模态呈现的视图控制器、导航控制器和标签栏控制器，找到实际位于最前端的页面。当调用需要视图控制器，而你手头只有 UIView 或完全没有 UI 上下文时，就需要使用此方法。

插屏广告

swift

// Load only
AppsKitSDKAdsManagerIOS.instance.loadInterstitial(from: viewController, placeholder: placeholder, callback: adapter)

// Show a previously loaded interstitial
AppsKitSDKAdsManagerIOS.instance.showInterstitial(from: viewController, placeholder: placeholder, callback: adapter)

adapter 继承 AdsCallback：

swift

private class InterstitialCallbackAdapter: AdsCallback {
    private let onAdLoaded: () -> Void
    private let onAdFailed: () -> Void

    init(onAdLoaded: @escaping () -> Void, onAdFailed: @escaping () -> Void) {
        self.onAdLoaded = onAdLoaded
        self.onAdFailed = onAdFailed
        super.init()
    }

    override func onLoaded()         { onAdLoaded() }
    override func onFailedToLoad()   { onAdFailed() }
    override func onAdShown()        {}
    override func onAdDismissed()    {}
    override func onAdFailedToShow() {}
}

激励广告

swift

// Separate load/show — chain load→show in your adapter's onRewardedLoaded(), same pattern as banner/native
AppsKitSDKAdsManagerIOS.instance.loadRewarded(from: viewController, placeholder: placeholder, callback: adapter)

AppsKitSDKAdsManagerIOS.instance.showRewarded(from: viewController, placeholder: placeholder, callback: adapter)

adapter 继承 RewardedAdCallbacks，在 onRewardedLoaded() 中直接调用 showRewarded，并复用 self 作为展示阶段的回调对象：

swift

private class RewardedAdCallbackAdapter: RewardedAdCallbacks {
    private let placeholder: String
    private let onUserEarnedReward: () -> Void
    private let onFailed: (String) -> Void

    init(placeholder: String, onUserEarnedReward: @escaping () -> Void, onFailed: @escaping (String) -> Void) {
        self.placeholder = placeholder
        self.onUserEarnedReward = onUserEarnedReward
        self.onFailed = onFailed
        super.init()
    }

    override func onRewardedLoaded() {
        guard let vc = UIApplication.topViewController() else {
            onFailed("No active view controller found")
            return
        }
        AppsKitSDKAdsManagerIOS.instance.showRewarded(from: vc, placeholder: placeholder, callback: self)
    }
    override func onAdRewarded()            { onUserEarnedReward() }
    override func onRewardedCompleted()     { onUserEarnedReward() }
    override func onAdRewardedAdDismissed() {}
    override func onRewardedAdLoadFailure() { onFailed("Failed to load rewarded ad") }
    override func onRewardedFailedToShow()  { onFailed("Failed to show rewarded ad") }
}

AKS 还在 AppsKitSDKAdsManagerIOS 上提供了单次调用即可完成加载和展示的 loadAndShowRewarded(from:placeholder:callback:) 方法，接收 RewardedLoadAndShowCallback 回调对象。该协议仅包含 onRewardedAdSuccess()/onRewardedAdFailed()（由于它是协议而非抽象类，因此不需要调用 super.init()）。如果需要提前加载、稍后展示，请使用上面独立的 loadRewarded/showRewarded 方法；如果始终在加载完成后立即展示，请使用 loadAndShowRewarded。

开屏广告

swift

AppsKitSDKAdsManagerIOS.instance.loadAppOpen(placeholder: placeholder, callback: adapter)

AppsKitSDKAdsManagerIOS.instance.showAppOpen(from: viewController, placeholder: placeholder, callback: adapter)

adapter 继承 AppOpenAdCallbacks：

swift

private class AppOpenCallbackAdapter: AppOpenAdCallbacks {
    private let onAdLoaded: () -> Void
    private let onAdFailed: () -> Void

    init(onAdLoaded: @escaping () -> Void, onAdFailed: @escaping () -> Void) {
        self.onAdLoaded = onAdLoaded
        self.onAdFailed = onAdFailed
        super.init()
    }

    override func onLoaded()       { onAdLoaded() }
    override func onFailedToLoad() { onAdFailed() }
    override func onAdShown()      {}
    override func onDismiss()      {}
    override func onAdFailToShow() {}
}

这是手动控制开屏广告的方式。如果需要 AKS 根据远程配置在应用级别自动处理，请改用 AKSBaseAppDelegate 的内置流程（§4.6）。

横幅广告

swift

AppsKitSDKAdsManagerIOS.instance.loadBanner(from: viewController, placeholder: placeholder, callback: adapter)

AppsKitSDKAdsManagerIOS.instance.showBanner(from: viewController, placeholder: placeholder, container: bannerContainerView, callback: adapter)

adapter 继承 BannerCallback——参见上文 §5.1 中完整的 BannerCallbackAdapter 定义，该适配器在 onBannerLoaded() 中直接调用 showBanner。

BannerSizes：BANNER（320×50）、LARGE_BANNER（320×100）、MEDIUM_RECTANGLE（300×250）、FULL_BANNER（468×60）。

原生广告

swift

AppsKitSDKAdsManagerIOS.instance.loadNative(from: viewController, placeholder: placeholder, isShowInScrollView: true, callback: adapter)

AppsKitSDKAdsManagerIOS.instance.showNative(
    from: viewController, container: nativeContainerView, placeholder: placeholder,
    res: nil, isShowInScrollView: true, callback: adapter
)

adapter 继承 NativeCallback，在 onNativeLoaded() 中直接调用 showNative，模式与 BannerCallbackAdapter 相同：

swift

private class NativeCallbackAdapter: NativeCallback {
    private weak var container: UIView?
    private let placeholder: String
    private let onAdLoaded: () -> Void
    private let onAdFailed: (String) -> Void

    init(container: UIView, placeholder: String, onAdLoaded: @escaping () -> Void, onAdFailed: @escaping (String) -> Void) {
        self.container = container
        self.placeholder = placeholder
        self.onAdLoaded = onAdLoaded
        self.onAdFailed = onAdFailed
        super.init()
    }

    override func onNativeLoaded() {
        onAdLoaded()
        guard let vc = UIApplication.topViewController(), let view = container else {
            onAdFailed("No active view controller found")
            return
        }
        AppsKitSDKAdsManagerIOS.instance.showNative(
            from: vc, container: view, placeholder: placeholder,
            res: nil, isShowInScrollView: true, callback: self
        )
    }
    override func onNativeFailedToLoad() { onAdFailed("") }
    override func onNativeClicked()      {}
    override func onNativeShown()        {}
}

功能推广

与其他广告格式一样，功能推广也由 AppsKitSDKAdsManagerIOS 封装：

swift

// Optional — exclude features the user already has unlocked from being promoted
AppsKitSDKAdsManagerIOS.instance.setFeaturesAvailable(availableFeatures: ["premium_theme", "no_ads"])

AppsKitSDKAdsManagerIOS.instance.showFeaturePromotion(
    from: viewController,
    placeholder: placeholder,
    callback: adapter
)

adapter 遵循 OnFeaturePromotionClicked 协议——它是协议而非抽象类，因此不需要调用 super.init()：

swift

private class FeaturePromotionAdapter: NSObject, OnFeaturePromotionClicked {
    private let onClicked: (String) -> Void
    private let onFailed: (String) -> Void

    init(onClicked: @escaping (String) -> Void, onFailed: @escaping (String) -> Void) {
        self.onClicked = onClicked
        self.onFailed = onFailed
    }

    func onFeaturePromotionClicked(targetScreen: String)    { onClicked(targetScreen) }
    func onFailToShowFeaturePromotion(errorMessage: String) { onFailed(errorMessage) }
}

← 4. 初始化 SDK 6. AKS 事件与日志 →