Dokümantasyon · iOS Entegrasyonu

5. Reklam formatlarını çağırma

Her çağrı, yine AKS portalında yapılandırılmış bir placeholder dizesi alır — AKS, çalışma zamanında bunu bir reklam ağı ve yedek ağ listesiyle eşleştirir.

5.1 Köprüleme deseni

AKS'nin reklam callback türleri (AdsCallback, BannerCallback, NativeCallback, RewardedAdCallbacks, AppOpenAdCallbacks), alt sınıfını oluşturup metotlarını override ettiğiniz sınıflardır; closure değildir. Yaygın kullanım deseni (AppsKitSDKAdsManagerIOS kullanan kodların genelinde olduğu gibi), her format için şu işlemleri yapan küçük, özel bir adaptör sınıfı oluşturmaktır:

AKS callback türünden türetilir ve super.init() çağrısını yapar.
Her yaşam döngüsü olayını kendi UI katmanınızın ihtiyaçlarına göre iletir.
Banner, yerel (native) ve ödüllü reklamlar için yükleme→gösterim zincirini kendisi yönetir — yani adaptördeki onBannerLoaded()/onNativeLoaded()/onRewardedLoaded() metotlarının override edilmiş sürümleri, ilgili show... çağrısını tetikler ve gösterim adımında da callback olarak self kullanır.

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 tarafından UIApplication üzerinde bir extension olarak sağlanır), en öndeki ekranı bulmak için anahtar pencerenin (key window) kök view controller'ından başlayıp sunulan view controller, navigation controller ve tab controller hiyerarşisini dolaşır. Bir çağrı view controller gerektirdiğinde ancak elinizde yalnızca bir UIView olduğunda veya hiç UI bağlamı bulunmadığında buna ihtiyaç duyarsınız.

Geçiş reklamı (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 sınıfından türetilir:

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

Ödüllü reklam (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 sınıfından türetilir ve gösterim adımında callback olarak yine self kullanarak onRewardedLoaded() metodunu doğrudan showRewarded çağrısına bağlar:

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 ayrıca AppsKitSDKAdsManagerIOS üzerinde, tek çağrıyla çalışan loadAndShowRewarded(from:placeholder:callback:) metodunu sunar. Bu metot, yalnızca onRewardedAdSuccess()/onRewardedAdFailed() metotlarını içeren RewardedLoadAndShowCallback protokolünü alır (soyut sınıf değil protokol olduğu için super.init() gerekmez). Reklamı önceden yükleyip daha sonra göstermek istediğinizde yukarıdaki ayrı loadRewarded/showRewarded çiftini kullanın; yüklemenin hemen ardından her zaman gösterim yapacaksanız loadAndShowRewarded kullanın.

Uygulama açılış reklamı (App Open)

swift

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

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

adapter, AppOpenAdCallbacks sınıfından türetilir:

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

Bu, App Open reklamlarını manuel olarak yönetme yöntemidir — AKS'nin uzaktan yapılandırmayla yönetilen, uygulama düzeyindeki otomatik işleyişi için bunun yerine AKSBaseAppDelegate içindeki yerleşik akışı kullanın (§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 sınıfından türetilir — onBannerLoaded() metodunu doğrudan showBanner çağrısına bağlayan BannerCallbackAdapter sınıfının tam tanımı için yukarıdaki §5.1 bölümüne bakın.

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

Yerel reklam (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, yerel reklam görünümünün uygulamanızda değil AKS portalında tasarlanıp atandığı placeholder'lar içindir — yerleşimi sizin sağlamanız gerekmediğinden res parametresi yoktur. AKS, bu placeholder için hangi portal şablonunun geçerli olduğunu belirler, şablonu getirir (ilk alımdan sonra önbelleğe alınır) ve showNative ile aynı yükleme/gösterim akışını kullanarak yerel reklamı bu şablonla oluşturur. Placeholder'a atanmış bir şablon yoksa veya şablon alınamıyorsa AKS, reklamı başarısız saymak yerine kendi yerleşik varsayılan yerel reklam tasarımını kullanır. Bu nedenle, portal tarafında henüz bir şablon oluşturulmamış olsa bile bu metodu çağırmak her zaman güvenlidir.

adapter, NativeCallback sınıfından türetilir ve BannerCallbackAdapter ile aynı deseni kullanarak onNativeLoaded() metodunu doğrudan showNative çağrısına bağlar:

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

Özellik tanıtımı (Feature Promotion)

Özellik tanıtımı da diğer formatlar gibi AppsKitSDKAdsManagerIOS üzerinden sunulur:

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 protokolünü uygular — bu bir soyut sınıf değil protokol olduğu için super.init() gerekmez:

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'yı Başlatma 6. AKS Olayları ve Logları →

5. Reklam formatlarını çağırma

5.1 Köprüleme deseni

Geçiş reklamı (Interstitial)

Ödüllü reklam (Rewarded)

Uygulama açılış reklamı (App Open)

Banner reklam

Yerel reklam (Native)

Özellik tanıtımı (Feature Promotion)