Документация · Интеграция с iOS

5. Вызов рекламных форматов

Каждый вызов по-прежнему принимает строку placeholder, настроенную на портале AKS. Во время выполнения 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-контекста.

Межстраничная реклама (Interstitial)

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() {}
}

Реклама с вознаграждением (Rewarded)

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 и вызывает showRewarded непосредственно из onRewardedLoaded(), повторно передавая 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, если показ всегда следует сразу за загрузкой.

Реклама при открытии приложения (App Open)

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() {}
}

Это ручной способ управления App Open. Для автоматической обработки на уровне приложения средствами 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 выше, где showBanner вызывается непосредственно из onBannerLoaded().

BannerSizes: BANNER (320×50), LARGE_BANNER (320×100), MEDIUM_RECTANGLE (300×250), FULL_BANNER (468×60).

Нативная реклама (Native)

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, а не в приложении. Параметра res здесь вообще нет, поскольку вам не нужно передавать макет. AKS определяет, какой шаблон портала назначен этому плейсхолдеру, загружает его (и кеширует после первой загрузки), а затем отображает с его помощью нативную рекламу, используя тот же процесс загрузки и показа, что и showNative. Если плейсхолдеру не назначен шаблон или его не удалось загрузить, AKS использует собственное встроенное оформление нативной рекламы по умолчанию, а не завершает показ с ошибкой. Поэтому метод можно безопасно вызывать, даже если шаблон на портале ещё не настроен.

adapter наследуется от NativeCallback и вызывает showNative непосредственно из onNativeLoaded() — по тому же принципу, что и 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()        {}
}

Продвижение функций (Feature Promotion)

Для Feature Promotion, как и для остальных форматов, используется обёртка 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 →