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 — khi chạy, AKS ánh xạ chuỗi này tới một mạng quảng cáo và danh sách dự phòng.

5.1 Mẫu triển khai 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 để bạ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 ở các thành phần sử dụng AppsKitSDKAdsManagerIOS) là tạo một lớp adapter riêng tư nhỏ cho mỗi định dạng để:

Kế thừa kiểu callback của AKS và gọi super.init().
Chuyển tiếp từng sự kiện vòng đời tới phần xử lý tương ứng trong tầng UI của bạn.
Với banner, native và rewarded, tự nối chuỗi tải→hiển thị — tức là phần 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 kỳ đâu mà lệnh gọi yêu cầu view controller nhưng bạn chỉ có một 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ỉ với một lệnh gọi. Phương thức này nhận 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 loadRewarded/showRewarded riêng biệt ở 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à cách xử lý App Open thủ công — để AKS tự động xử lý ở cấp ứng dụng theo cấu hình từ xa, hãy dùng luồng tích hợp sẵn của 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 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
)

// 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 dành cho các placeholder có giao diện quảng cáo native được thiết kế và gán trên cổng AKS thay vì trong ứng dụng — phương thức này không có tham số res vì bạn không cần cung cấp bố cục. AKS xác định mẫu trên cổng áp dụng cho placeholder này, tải mẫu về (lưu vào bộ nhớ đệm sau lần tải đầu tiên) rồi dùng mẫu đó để kết xuất quảng cáo native thông qua cùng quy trình tải/hiển thị mà showNative sử dụng. Nếu placeholder chưa được gán mẫu hoặc không tải được mẫu, AKS sẽ dùng thiết kế native mặc định tích hợp sẵn thay vì báo lỗi quảng cáo — vì vậy, bạn luôn có thể gọi phương thức này một cách an toàn, ngay cả khi chưa thiết lập mẫu trên cổng.

adapter kế thừa NativeCallback và nối trực tiếp onNativeLoaded() với showNative, theo cùng mẫu triển khai như 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, tương tự 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à 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 SDK 6. Sự kiện và log AKS →

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

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

Quảng cáo xen kẽ (Interstitial)

Quảng cáo có thưởng (Rewarded)

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

Quảng cáo banner

Quảng cáo gốc (Native)

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