1. التبعيات
1.1 حزمة AKS SDK
أضف SDK نفسها إلى ملف build.gradle.kts على مستوى التطبيق:
dependencies {
implementation("com.github.Pentabit-Labs-LLC:appskitsdk-android:${LATEST_VERSION}")
}استبدل ${LATEST_VERSION} بأحدث وسم من إصدارات appskitsdk-android (أو من شارة JitPack في ملف README لذلك المستودع)، مثل v6.4.0.0.
تُنشر AKS كمجموعة من ملفات .aar الخام (وليست وحدة Maven تتضمن معلومات التبعيات)، لذا لا تُضاف أي من تبعياتها الخارجية تلقائيًا كتبعيات غير مباشرة. يجب التصريح صراحةً بكل ما يلي في وحدة التطبيق. الاستثناء الوحيد هو SupportAKS (com.pentabit.aks_android_support_lib) — إذ تُضمَّن هذه الأصناف مباشرةً داخل حزمة appskitsdk-android نفسها، ولذلك لا تضف com.pentabit:aks-android-helpers بشكل منفصل.
1.2 المكتبات المطلوبة (ضرورية دائمًا)
تشير الشيفرة المُصرَّفة لـ AKS مباشرةً إلى هذه المكتبات، لذا فهي مطلوبة بغض النظر عن شبكات الإعلانات التي تفعّلها فعليًا:
dependencies {
// Firebase (Remote Config drives almost all AKS behavior; Analytics is used for AKS events)
implementation(platform("com.google.firebase:firebase-bom:34.3.0"))
implementation("com.google.firebase:firebase-analytics")
implementation("com.google.firebase:firebase-config")
implementation("com.google.android.gms:play-services-measurement-api:23.0.0")
// Coroutines / serialization / datetime — used throughout AdsManager and AppsKitSDK
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3")
implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.9.0")
implementation("org.jetbrains.kotlinx:kotlinx-datetime:0.7.1")
// Ktor — AKS's internal network client for fetching ad/config data
implementation("io.ktor:ktor-client-core:3.3.3")
implementation("io.ktor:ktor-client-okhttp:3.3.3")
implementation("io.ktor:ktor-client-content-negotiation:3.3.3")
implementation("io.ktor:ktor-serialization-kotlinx-json:3.3.3")
implementation("io.ktor:ktor-client-logging:3.3.3")
// Local storage AKS uses for its own preferences/session/ad-state tracking
implementation("com.russhwolf:multiplatform-settings:1.1.1")
implementation("com.russhwolf:multiplatform-settings-serialization:1.1.1")
// Jetpack Compose — AKS's Feature/Cross-Promotion ad screens, the Configuration
// Dashboard, and the Test Suite (§10) are all built with Compose. Pull these in via
// the Compose BOM so versions stay aligned with whatever else in your app uses Compose.
implementation(platform("androidx.compose:compose-bom:2025.08.01"))
implementation("androidx.compose.runtime:runtime")
implementation("androidx.compose.foundation:foundation")
implementation("androidx.compose.material3:material3")
implementation("androidx.compose.ui:ui")
implementation("androidx.compose.ui:ui-tooling-preview")
// Image loading used by AKS's built-in cross-promotion / feature-promotion ad screens
implementation("io.coil-kt.coil3:coil:3.3.0")
implementation("io.coil-kt.coil3:coil-compose:3.3.0")
implementation("io.coil-kt.coil3:coil-compose-core:3.3.0")
implementation("io.coil-kt.coil3:coil-network-ktor3:3.3.0")
implementation("media.kamel:kamel-image:0.9.5")
// Used by enableAppAutoUpdate() in the AKS base Activities
implementation("com.google.android.play:app-update:2.1.0")
// Powers AppsKitSDKUtils.askForRating() — AKS's built-in in-app review flow
implementation("com.google.android.play:review:2.0.1")
implementation("androidx.recyclerview:recyclerview:1.4.0")
// IronSource core — AKS's base Activity classes call IronSource.onResume()/onPause()
// unconditionally on every screen, so this is required even if you never select
// IronSource as an ad network in the AKS portal.
implementation("com.ironsource.sdk:mediationsdk:8.5.0")
}احرص على توحيد إصدار Ktor في جميع حزم
ktor-*— فالجمع بين حزم Ktor 2.x و3.x في مسار الأصناف نفسه يؤدي إلى أعطال أثناء التشغيل بسبب عدم التوافق الثنائي.وحِّد أيضًا إصدارات coroutines (
1.7.3) وserialization (1.9.0) وFirebase BOM (34.3.0) في بقية التطبيق لتطابق الإصدارات التي تستخدمها AKS، بدلًا من إبقاء إصدار أقدم في موضع آخر من مخطط التبعيات. شهدت BOM الخاصة بـ Firebase تغييرات تكسر التوافق بين الإصدارات الرئيسية (33.x→34.x)، واختيار Gradle تلقائيًا للإصدار الذي «يفوز» عند حل تعارض التبعيات لا يضمن بقاء مسارات تنفيذ شيفرة AKS التي تستدعي هذه المكتبات متوافقة ثنائيًا — هذه متطلبات إلزامية وليست مجرد توصيات تُطبَّق حسب الإمكان.
1.3 حزم SDK لشركاء قياس أداء تطبيقات الأجهزة المحمولة (MMP) (ضرورية دائمًا)
تهيّئ AKS هذه الحزم الثلاث تلقائيًا باستخدام المفاتيح المحددة في بوابة AKS / Firebase Remote Config — لن تستدعيها مباشرةً، لكن الشيفرة المُصرَّفة لـ AKS تشير إلى أصناف SDK الخاصة بها دون قيد أو شرط، لذا يجب أن تكون موجودة في مسار الأصناف:
dependencies {
// AppsFlyer
implementation("com.appsflyer:af-android-sdk:6.13.0")
implementation("com.appsflyer:adrevenue:6.9.0")
implementation("com.miui.referrer:homereferrer:1.0.0.6")
implementation("com.android.installreferrer:installreferrer:2.2")
// Adjust
implementation("com.adjust.sdk:adjust-android:4.38.3")
// Solar Engine (Reyun)
implementation("com.reyun.solar.engine.oversea:solar-engine-core:1.3.1.4")
}إذا لم تكن لديك مفاتيح لإحدى هذه الحزم في إعدادات بوابة AKS، فلا مشكلة — ستتخطى AKS تهيئتها أثناء التشغيل فحسب. ومع ذلك، يجب أن تظل التبعية موجودة حتى ينجح بناء التطبيق.
1.4 حزم SDK لشبكات الإعلانات / الوساطة الإعلانية
تُضمِّن AKS شيفرة معالجة AdMob وAppLovin MAX وChartboost Mediation (Helium) داخل ملف AAR نفسه، بالإضافة إلى IronSource (المذكورة أعلاه). تُحدَّد الشبكة التي تعرض الإعلان فعليًا عن بُعد (لكل تنسيق إعلان، مع الانتقال إلى شبكة بديلة عند الفشل)، لذا فإن النهج الأكثر أمانًا — وهو النهج الذي يستخدمه التطبيق المرجعي الخاص بـ Pentabit — هو تضمينها جميعًا:
dependencies {
// ---- AdMob / Google Mobile Ads + mediation adapters ----
implementation("com.google.android.gms:play-services-ads:24.4.0")
implementation("com.google.ads.mediation:applovin:13.0.1.0")
implementation("com.google.ads.mediation:ironsource:8.5.0.1")
implementation("com.google.ads.mediation:chartboost:9.8.2.0")
implementation("com.google.ads.mediation:vungle:7.4.2.0")
implementation("com.google.ads.mediation:facebook:6.18.0.0")
implementation("com.google.ads.mediation:mintegral:16.9.71.0")
implementation("com.google.ads.mediation:pangle:6.4.0.4.0")
implementation("com.google.ads.mediation:unity:4.12.5.0") {
exclude(group = "com.google.android.gms", module = "play-services-cronet")
}
// ---- AppLovin MAX + adapters ----
implementation("com.applovin:applovin-sdk:13.3.0")
implementation("com.applovin.mediation:google-adapter:+")
implementation("com.applovin.mediation:google-ad-manager-adapter:+")
implementation("com.applovin.mediation:ironsource-adapter:8.7.0.0.0")
implementation("com.applovin.mediation:facebook-adapter:+")
implementation("com.applovin.mediation:vungle-adapter:+")
implementation("com.applovin.mediation:mintegral-adapter:+")
implementation("com.applovin.mediation:bytedance-adapter:6.5.0.8.1")
implementation("com.applovin.mediation:unityads-adapter:+") {
exclude(group = "com.google.android.gms", module = "play-services-cronet")
}
// ---- Chartboost Mediation (Helium) + adapters ----
implementation("com.chartboost:chartboost-mediation-sdk:4.7.1")
implementation("com.chartboost:chartboost-mediation-adapter-admob:4.22.3.0.4")
implementation("com.chartboost:chartboost-mediation-adapter-applovin:4.12.0.0.0")
implementation("com.chartboost:chartboost-mediation-adapter-ironsource:4.7.5.2.0.0")
implementation("com.chartboost:chartboost-mediation-adapter-vungle:4.7.1.0.0")
implementation("com.chartboost:chartboost-mediation-adapter-meta-audience-network:4.6.16.0.0")
implementation("com.chartboost:chartboost-mediation-adapter-pangle:4.5.5.0.3.0")
}إذا كنت متأكدًا من أن شبكة معينة (مثل Helium) لن تُفعَّل أبدًا في إعدادات بوابة AKS، فيمكنك حذف كتلة التبعيات الخاصة بها — لكن تذكّر أن منطق الانتقال إلى شبكة بديلة عند الفشل، المضمَّن في AdNetwork داخل AKS، يمكنه التوجيه إلى أي من ADMOB أو GAM أو MAX أو IRON_SOURCE أو HELIUM لكل تنسيق إعلان، لذا فإن تقليص هذه القائمة يحدّ من مرونة الإعدادات عن بُعد.