文档 · 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 — 完整的 BannerCallbackAdapter 定义见上文 §5.1，它会在 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 事件与日志 →