التوثيق · AppsKitSDK (AKS) — دليل التكامل مع 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)

// Show the native ad using the design you created for this placeholder in the
// AKS portal, instead of a layout resource — see below.
AdsManager.showTemplatedNative(activity, frameLayout, placeholder, isShowInScrollView = false, callback)

تُستخدم showTemplatedNative لمعرّفات المواضع الإعلانية التي صُمّم مظهر إعلانها المدمج مع المحتوى وعُيّن في بوابة AKS بدلاً من كود تطبيقك — ولا تتضمن مَعلمة res إطلاقاً، لأنك لا تحتاج إلى توفير التخطيط بنفسك. يحدّد AKS قالب البوابة المرتبط بهذا المعرّف، ويجلبه (مع تخزينه مؤقتاً بعد الجلب الأول)، ثم يعرض الإعلان المدمج مع المحتوى باستخدامه عبر مسار التحميل والعرض نفسه الذي تستخدمه showNative. إذا لم يكن هناك قالب معيّن لهذا المعرّف، أو تعذّر جلبه، يستخدم AKS تصميمه الافتراضي المدمج للإعلانات المدمجة مع المحتوى بدلاً من إفشال الإعلان — لذا يمكن استدعاؤها بأمان دائماً، حتى قبل إعداد قالب في البوابة.

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

الترويج للميزات هو شكل الإعلانات الذاتية الخاص بـ 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) { }
})