Dokümantasyon · iOS Entegrasyonu

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

Her çağrı, AKS portalında yapılandırılmış bir placeholder dizesi almaya devam eder — AKS, çalışma zamanında bu değeri bir reklam ağı ve yedek ağ listesiyle eşleştirir.

5.1 Köprüleme deseni

AKS'nin reklam geri çağırım 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 aşağıdaki adımları uygulayan küçük bir özel adaptör sınıfı oluşturmaktır:

AKS geri çağırım türünün alt sınıfını oluşturur 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, doğal (native) ve ödüllü reklamlar için yükleme→gösterim zincirini kendisi yönetir; yani adaptörün onBannerLoaded()/onNativeLoaded()/onRewardedLoaded() metot geçersiz kılması, ilgili show... çağrısını tetikler ve gösterim adımının geri çağırımı olarak da self kullanılı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 uzantı olarak sağlanır), etkin pencerenin kök görünüm denetleyicisinden başlayarak sunulan denetleyiciler, gezinme denetleyicileri ve sekme denetleyicileri boyunca ilerleyip en öndeki ekranı bulur. Bir çağrı görünüm denetleyicisi gerektirdiğinde ancak elinizde yalnızca bir UIView olduğunda veya hiç UI bağlamı bulunmadığında bu metoda 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 onRewardedLoaded() içinden doğrudan showRewarded çağrısını yapar; gösterim adımının geri çağırımı olarak da self kullanılır:

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 yükleyip gösteren 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). Önceden yükleyip daha sonra göstermeniz gerektiğinde yukarıdaki ayrı loadRewarded/showRewarded çiftini; her zaman yüklemenin hemen ardından gösterim yapacaksanız loadAndShowRewarded metodunu 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, uygulama açılış reklamlarını manuel 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() içinden doğrudan showBanner çağrısını yapan eksiksiz BannerCallbackAdapter 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).

Doğal 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, doğal reklamın görünümünün uygulamanızda değil AKS portalında tasarlanıp atandığı placeholder'lar içindir. Düzeni sizin sağlamanız gerekmediğinden res parametresi bulunmaz. AKS, bu placeholder için hangi portal şablonunun geçerli olduğunu belirler, şablonu getirir (ilk getirme işleminden sonra önbelleğe alınır) ve showNative ile aynı yükleme/gösterim akışını kullanarak doğal reklamı bu şablonla oluşturur. Placeholder'a atanmış bir şablon yoksa veya şablon getirilemiyorsa AKS, reklamı başarısız kılmak yerine kendi yerleşik varsayılan doğal reklam tasarımını kullanır. Bu nedenle, portal tarafında henüz bir şablon ayarlanmamış 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() içinden doğrudan showNative çağrısını yapar:

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üne uyar. Bu, soyut sınıf değil protokol olduğundan 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ı →