التوثيق · AppsKitSDK (AKS) — دليل التكامل مع Android

1. التبعيات

1.1 حزمة AKS SDK

أضِف حزمة SDK نفسها إلى ملف build.gradle.kts على مستوى التطبيق:

kotlin
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 إلى هذه المكتبات مباشرةً، لذا فهي مطلوبة بغض النظر عن شبكات الإعلانات التي تفعّلها فعليًا:

kotlin
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")

    // SQLDelight — backs AKS's own local analytics database (AksLocalDbManager). It's
    // referenced directly by AKS's compiled code, and — like every other dependency in this
    // guide — carries no dependency metadata on the JitPack AAR (bare .pom, no .module), so
    // omitting it doesn't fail the build, it crashes at runtime the first time
    // AppsKitSDK.initialize() runs: NoClassDefFoundError: app/cash/sqldelight/Transacter.
    implementation("app.cash.sqldelight:runtime:2.3.2")
    implementation("app.cash.sqldelight:android-driver:2.3.2")

    // 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) وSQLDelight (2.3.2) في بقية تطبيقك لتطابق الإصدارات التي تستخدمها AKS، بدلًا من ترك إصدار أقدم في موضع آخر ضمن مخطط التبعيات. شهدت BOM الخاصة بـ Firebase تغييرات غير متوافقة مع الإصدارات السابقة عند الانتقال بين الإصدارات الرئيسية (33.x → 34.x)، واختيار Gradle تلقائيًا للإصدار الذي «يفوز» عند حل تعارض التبعيات لا يضمن بقاء مسارات الكود في AKS التي تستدعي هذه المكتبات متوافقة ثنائيًا — هذه متطلبات إلزامية وليست مجرد اقتراحات تُتَّبع قدر الإمكان.

1.3 حزم SDK لشركاء قياس أداء تطبيقات الجوال (MMP) (ضرورية دائمًا)

تُهيّئ AKS هذه الحزم الثلاث تلقائيًا باستخدام المفاتيح المحددة في بوابة AKS / Firebase Remote Config — لا تستدعيها أنت مباشرةً، لكن الكود المترجَم في AKS يشير إلى أصناف SDK الخاصة بها دون أي شروط، لذا يجب أن تكون موجودة في مسار الأصناف:

kotlin
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 — هو تضمينها جميعًا:

kotlin
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 لكل تنسيق إعلان، لذا فإن تقليص هذه القائمة يحدّ من مرونة الإعدادات عن بُعد.