文档 · 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
)

// Show the native ad using the design you created for this placeholder in the
// AKS portal, instead of an XIB — see below.
AppsKitSDKAdsManagerIOS.instance.showTemplatedNative(
    from: viewController, container: nativeContainerView, placeholder: placeholder,
    isShowInScrollView: true, callback: adapter
)

showTemplatedNative 适用于在 AKS 管理平台上设计并分配原生广告样式的 placeholder，而不是在应用内定义样式的情况。此方法完全没有 res 参数，因为无需由你提供布局。AKS 会确定适用于该 placeholder 的平台模板，获取模板（首次获取后会缓存），然后通过与 showNative 相同的加载和展示流程，使用该模板渲染原生广告。如果 placeholder 未分配模板，或无法获取模板，AKS 会回退到自身内置的默认原生广告样式，而不会导致广告展示失败。因此，即使尚未在管理平台上设置模板，也可以安全调用此方法。

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 事件与日志 →