Apps Kit SDK logoApps Kit SDK
Tài liệu · Tích hợp iOS

5. Gọi các định dạng quảng cáo

Mỗi lệnh gọi vẫn nhận một chuỗi placeholder được cấu hình trên cổng AKS — AKS ánh xạ chuỗi này tới một mạng quảng cáo + danh sách dự phòng tại thời điểm chạy.

5.1 Mẫu triển khai lớp cầu nối

Các kiểu callback quảng cáo của AKS (AdsCallback, BannerCallback, NativeCallback, RewardedAdCallbacks, AppOpenAdCallbacks) là các lớp mà bạn cần kế thừa và override — không phải closure. Mẫu triển khai thông dụng (được dùng xuyên suốt ở những nơi sử dụng AppsKitSDKAdsManagerIOS) là tạo một lớp adapter riêng tư nhỏ cho mỗi định dạng để:

  1. Kế thừa kiểu callback của AKS và gọi super.init().
  2. Chuyển tiếp từng sự kiện vòng đời tới phần xử lý tương ứng trong lớp UI của bạn.
  3. Với banner, native và rewarded, tự nối chuỗi tải→hiển thị — tức là phương thức ghi đè onBannerLoaded()/onNativeLoaded()/onRewardedLoaded() của adapter sẽ kích hoạt lệnh gọi show... tương ứng, đồng thời dùng lại self làm callback cho bước hiển thị.
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() (do AppsKit.xcframework cung cấp dưới dạng extension của UIApplication) duyệt từ view controller gốc của key window qua các controller được trình bày, controller điều hướng hoặc controller tab để tìm màn hình thực sự ở trên cùng — bạn cần phương thức này ở bất cứ đâu lệnh gọi yêu cầu một view controller nhưng bạn chỉ có UIView hoặc hoàn toàn không có ngữ cảnh UI.

Quảng cáo xen kẽ (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 kế thừa 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() {}
}

Quảng cáo có thưởng (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 kế thừa RewardedAdCallbacks và nối trực tiếp onRewardedLoaded() với showRewarded, dùng lại self làm callback cho bước hiển thị:

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 cũng cung cấp phương thức loadAndShowRewarded(from:placeholder:callback:) trên AppsKitSDKAdsManagerIOS để tải và hiển thị chỉ bằng một lệnh gọi. Phương thức này nhận một RewardedLoadAndShowCallback — một protocol chỉ có onRewardedAdSuccess()/onRewardedAdFailed() (không cần super.init() vì đây là protocol, không phải lớp trừu tượng). Dùng cặp phương thức riêng biệt loadRewarded/showRewarded ở trên khi bạn cần tải trước và hiển thị sau; dùng loadAndShowRewarded khi bạn luôn hiển thị ngay sau khi tải xong.

Quảng cáo khi mở ứng dụng (App Open)

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

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

adapter kế thừa 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() {}
}

Đây là luồng xử lý App Open thủ công — nếu muốn AKS tự động xử lý ở cấp ứng dụng dựa trên cấu hình từ xa, hãy dùng luồng tích hợp sẵn của AKSBaseAppDelegate (§4.6).

Quảng cáo biểu ngữ (Banner)

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

AppsKitSDKAdsManagerIOS.instance.showBanner(from: viewController, placeholder: placeholder, container: bannerContainerView, callback: adapter)

adapter kế thừa BannerCallback — xem định nghĩa đầy đủ của BannerCallbackAdapter ở §5.1 phía trên, trong đó onBannerLoaded() được nối trực tiếp với showBanner.

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

Quảng cáo gốc (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
)

adapter kế thừa NativeCallback và nối trực tiếp onNativeLoaded() với showNative, theo cùng mẫu với 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()        {}
}

Quảng bá tính năng (Feature Promotion)

Feature Promotion được đóng gói qua AppsKitSDKAdsManagerIOS, giống các định dạng khác:

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 tuân thủ OnFeaturePromotionClicked — đây là một protocol, không phải lớp trừu tượng, nên không cần 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. Khởi tạo SDK6. Sự kiện và log AKS →