1. Các thư viện phụ thuộc
1.1 SDK AKS
Thêm SDK vào tệp build.gradle.kts cấp ứng dụng:
dependencies {
implementation("com.github.Pentabit-Labs-LLC:appskitsdk-android:${LATEST_VERSION}")
}Thay ${LATEST_VERSION} bằng tag mới nhất trong các bản phát hành appskitsdk-android (hoặc huy hiệu JitPack trong README của kho mã đó), ví dụ: v6.4.0.0.
AKS được phát hành dưới dạng tập hợp các tệp .aar thuần (không phải mô-đun Maven có khai báo thư viện phụ thuộc), nên không có thư viện phụ thuộc bên thứ ba nào được tự động kéo vào theo cơ chế phụ thuộc bắc cầu. Bạn phải khai báo tường minh tất cả các thư viện bên dưới trong mô-đun ứng dụng. Ngoại lệ duy nhất là SupportAKS (com.pentabit.aks_android_support_lib) — các lớp này được đóng gói trực tiếp trong artifact appskitsdk-android, nên bạn không cần thêm riêng com.pentabit:aks-android-helpers.
1.2 Các thư viện bắt buộc (luôn cần)
Mã đã biên dịch của AKS tham chiếu trực tiếp đến các thư viện này, nên chúng luôn bắt buộc, bất kể bạn thực sự bật mạng quảng cáo nào:
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")
}Giữ phiên bản Ktor nhất quán trên mọi artifact
ktor-*— trộn các artifact Ktor 2.x và 3.x trên cùng classpath sẽ gây sự cố khi chạy do không tương thích nhị phân.Đồng bộ phiên bản coroutines (
1.7.3), serialization (1.9.0), Firebase BOM (34.3.0) và SQLDelight (2.3.2) với AKS trong toàn bộ phần còn lại của ứng dụng, thay vì để phiên bản cũ tồn tại ở nơi khác trong đồ thị phụ thuộc. BOM của Firebase đã có những thay đổi phá vỡ tính tương thích giữa các phiên bản chính (33.x→34.x), và việc Gradle âm thầm chọn phiên bản "thắng" khi phân giải phụ thuộc không đảm bảo các luồng thực thi của AKS gọi đến những thư viện này vẫn tương thích nhị phân — đây là yêu cầu bắt buộc, không phải khuyến nghị tùy nghi.
1.3 SDK của đối tác đo lường di động (MMP) (luôn cần)
AKS tự động khởi tạo ba SDK này dựa trên các khóa được thiết lập trong cổng quản trị AKS / Firebase Remote Config — bạn không gọi trực tiếp đến chúng, nhưng mã đã biên dịch của AKS luôn tham chiếu đến các lớp SDK này mà không kiểm tra điều kiện, nên chúng phải có trên classpath:
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")
}Nếu cấu hình trên cổng quản trị AKS của bạn chưa có khóa cho một trong các SDK này thì cũng không sao — AKS sẽ bỏ qua việc khởi tạo SDK đó khi chạy. Tuy nhiên, thư viện phụ thuộc vẫn phải có để ứng dụng có thể biên dịch.
1.4 SDK mạng quảng cáo / mediation
AKS đóng gói mã xử lý cho AdMob, AppLovin MAX và Chartboost Mediation (Helium) trong cùng một AAR, bên cạnh IronSource (đã liệt kê ở trên). Mạng thực sự phân phối quảng cáo được quyết định từ xa (theo từng định dạng quảng cáo, có cơ chế chuyển sang mạng dự phòng), nên cách an toàn nhất — cũng là cách ứng dụng tham chiếu của Pentabit sử dụng — là thêm tất cả các SDK này:
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")
}Nếu chắc chắn một mạng cụ thể (ví dụ: Helium) sẽ không bao giờ được bật trong cấu hình trên cổng quản trị AKS, bạn có thể bỏ khối khai báo tương ứng — nhưng lưu ý rằng logic chuyển sang mạng dự phòng AdNetwork nội bộ của AKS có thể định tuyến đến bất kỳ mạng nào trong ADMOB, GAM, MAX, IRON_SOURCE hoặc HELIUM theo từng định dạng quảng cáo, nên việc rút gọn danh sách này sẽ làm giảm tính linh hoạt của cấu hình từ xa.