Документация · Интеграция с 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 →