Documentação · Integração com iOS

5. Chamando os formatos de anúncio

Cada chamada continua recebendo uma string de placeholder configurada no portal AKS — em tempo de execução, o AKS a resolve para uma rede + uma lista de alternativas em caso de falha.

5.1 O padrão de adaptação

Os tipos de callback de anúncios do AKS (AdsCallback, BannerCallback, NativeCallback, RewardedAdCallbacks, AppOpenAdCallbacks) são classes das quais você cria subclasses e sobrescreve métodos com override — não são closures. O padrão idiomático (usado em todo o código que consome AppsKitSDKAdsManagerIOS) é uma pequena classe adaptadora privada por formato que:

Herda do tipo de callback do AKS e chama super.init().
Encaminha cada evento do ciclo de vida conforme as necessidades da sua camada de UI.
Para banner, nativo e premiado, encadeia por conta própria carregamento→exibição — ou seja, a sobrescrita de onBannerLoaded()/onNativeLoaded()/onRewardedLoaded() no adaptador é o que dispara a chamada show... correspondente, reutilizando self também como callback da etapa de exibição.

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() (fornecido por AppsKit.xcframework como uma extensão de UIApplication) percorre a hierarquia a partir do view controller raiz da janela principal (key window), passando por controladores apresentados, de navegação ou de abas, para encontrar a tela que está de fato em primeiro plano — você precisa disso sempre que uma chamada exige um view controller, mas você só tem uma UIView ou nenhum contexto de UI.

Intersticial

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

Premiado

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 herda de RewardedAdCallbacks e encadeia onRewardedLoaded() diretamente com showRewarded, reutilizando self como callback da etapa de exibição:

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") }
}

O AKS também expõe loadAndShowRewarded(from:placeholder:callback:) em AppsKitSDKAdsManagerIOS para carregar e exibir em uma única chamada, recebendo um RewardedLoadAndShowCallback — um protocolo com apenas onRewardedAdSuccess()/onRewardedAdFailed() (não é necessário chamar super.init(), pois é um protocolo, não uma classe abstrata). Use o par de chamadas separadas loadRewarded/showRewarded acima quando precisar carregar com antecedência e exibir depois; use loadAndShowRewarded quando a exibição sempre ocorrer imediatamente após o carregamento.

Abertura do app (App Open)

swift

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

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

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

Este é o fluxo manual de App Open — para o gerenciamento automático do AKS no nível do aplicativo, controlado por configuração remota, use o fluxo integrado de 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 herda de BannerCallback — veja a definição completa de BannerCallbackAdapter na seção §5.1 acima, que encadeia onBannerLoaded() diretamente com showBanner.

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

Nativo

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 é destinado a placeholders cujo visual do anúncio nativo foi criado e atribuído no portal AKS, e não no seu app — não há parâmetro res, pois não cabe a você fornecer o layout. O AKS identifica qual template do portal se aplica a esse placeholder, faz o download (armazenando-o em cache após o primeiro download) e renderiza o anúncio nativo com ele pelo mesmo pipeline de carregamento/exibição usado por showNative. Se nenhum template estiver atribuído ao placeholder, ou se não for possível baixá-lo, o AKS usa seu próprio design nativo padrão integrado em vez de causar uma falha no anúncio — portanto, é sempre seguro fazer essa chamada, mesmo antes de configurar um template no portal.

adapter herda de NativeCallback e encadeia onNativeLoaded() diretamente com showNative, seguindo o mesmo padrão de 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()        {}
}

Promoção de recursos (Feature Promotion)

Feature Promotion é encapsulado por AppsKitSDKAdsManagerIOS, assim como os outros formatos:

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 adota OnFeaturePromotionClicked — um protocolo, não uma classe abstrata, portanto não é necessário chamar 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. Inicialização do SDK 6. Eventos e logs do AKS →