التوثيق · التكامل مع Android

6. استدعاء أشكال الإعلانات

يتطلب كل استدعاء إعلان مفتاح موضع إعلان (placeholder) — وهو مفتاح نصي يُربط بأحد أشكال الإعلانات في بوابة AKS (مثل "1"). يحدد AKS أثناء التشغيل شبكة الإعلانات الأساسية وقائمة الشبكات البديلة المرتبطة بهذا المفتاح؛ ولا تحتاج أبدًا إلى الإشارة إلى معرّف وحدة إعلانية مباشرةً في الكود.

الإعلانات البينية

kotlin
// Load only
AdsManager.loadInterstitial(context, placeholder, object : AdsCallback() {
    override fun onLoaded() { }
    override fun onFailedToLoad() { }
    override fun onAdShown() { }
    override fun onAdDismissed() { }
    override fun onAdFailedToShow() { }
})

// Show a previously loaded interstitial
AdsManager.showInterstitial(activity, placeholder, callback)

// Load and show in one call
AdsManager.loadAndShowInterstitialAd(activity, placeholder, callback)

// Check availability before showing
AdsManager.isInterstitialAvailable(placeholder)

الإعلانات بمكافأة

kotlin
AdsManager.loadRewarded(context, placeholder, object : RewardedAdCallbacks() {
    override fun onRewardedLoaded() { }
    override fun onRewardedAdLoadFailure() { }
    override fun onRewardedCompleted() { }
    override fun onAdRewarded() { }
    override fun onAdRewardedAdDismissed() { }
    override fun onRewardedFailedToShow() { }
})

AdsManager.showRewarded(activity, placeholder, callbacks)

// Load and show in one call — simpler success/fail callback
AdsManager.loadAndShowRewardedAd(activity, placeholder, object : RewardedLoadAndShowCallback {
    override fun onRewardedAdSuccess() { }
    override fun onRewardedAdFailed() { }
})

AdsManager.isRewardedAvailable(placeholder)

إعلانات فتح التطبيق

kotlin
AdsManager.loadAppOpen(application, placeholder, object : AppOpenAdCallbacks() {
    override fun onLoaded() { }
    override fun onFailedToLoad() { }
    override fun onDismiss() { }
    override fun onAdShown() { }
    override fun onAdFailToShow() { }
})

AdsManager.showAppOpen(activity, placeholder, callbacks)

إذا أردت استخدام آلية AKS المدمجة للتعامل مع شاشة البداية وإعلانات فتح التطبيق (التي يتحكم فيها علم الإعداد عن بُعد isAppOpenAtApplicationLvl) بدلًا من إدارة إعلانات فتح التطبيق بنفسك، فاستخدم loadDefaultAppOpen / showDefaultAppOpen في الفئة الفرعية المشتقة من AppsKitSDKApplication — أو استدعِ ببساطة requestSplashAppOpenAd(callbacks, addInDefaultDelay)، التي توفر الفئة الأساسية Application تنفيذًا كاملًا لها بالفعل.

إعلانات البانر

kotlin
AdsManager.loadBanner(context, placeholder, object : BannerCallback() {
    override fun onBannerLoaded() { }
    override fun onBannerFailedToLoad() { }
    override fun onBannerClicked() { }
    override fun onBannerShown() { }
    override fun onBannerSizeChanged(bannerSizes: BannerSizes) { }
    override fun setBannerSize(width: Double, height: Double) { }
})

// layout is a FrameLayout (BannerContainer) you've placed in your screen
AdsManager.showBanner(activity, layout, placeholder, callback)

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

الإعلانات المدمجة مع المحتوى

kotlin
AdsManager.loadNative(activity, placeholder, isShowInScrollView = false, object : NativeCallback() {
    override fun onNativeLoaded() { }
    override fun onNativeFailedToLoad() { }
    override fun onNativeClicked() { }
    override fun onNativeShown() { }
})

// frameLayout is the BannerContainer that will host the native ad view; res is an
// optional custom native-ad layout resource (pass null to use AKS's default layout)
AdsManager.showNative(activity, frameLayout, placeholder, isShowInScrollView = false, res = null, callback)

الترويج للميزات

الترويج للميزات هو شكل إعلانات داخلية خاص بـ AKS، يتيح الترويج لإحدى ميزات تطبيقك للمستخدمين الذين لم يفتحوا إمكانية الوصول إليها بعد — ويعمل حصريًا عبر شبكة AKS (وليس AdMob أو MAX أو غيرها). تُضبط العناصر المُروَّج لها على جانب الخادم في بوابة AKS، وتُربط بمفتاح موضع الإعلان.

kotlin
// Optional — exclude features the user already has unlocked from being promoted
AdsManager.setFeaturesAvailable(listOf("premium_theme", "no_ads"))

AdsManager.showFeaturePromotion(activity, placeholder, object : OnFeaturePromotionClicked {
    override fun onFeaturePromotionClicked(targetScreen: String) {
        // user tapped the promotion — navigate them to targetScreen
    }

    override fun onFailToShowFeaturePromotion(errorMessage: String) { }
})