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을 상속하고, BannerCallbackAdapter와 동일한 패턴으로 onNativeLoaded()에서 바로 showNative를 호출하도록 연결합니다.

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 이벤트 및 로그 →