التوثيق · 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")

    // 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 عبر بقية تطبيقك، بدلًا من ترك إصدار أقدم في موضع آخر ضمن شجرة التبعيات. فقد شهدت Firebase BOM تغييرات غير متوافقة مع الإصدارات السابقة عند الانتقال بين الإصدارات الرئيسية (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 لكل تنسيق إعلاني، لذا فإن تقليص هذه القائمة يحدّ من مرونة الإعداد عن بُعد.