개발자 문서 · AppsKitSDK (AKS) — Android 연동 가이드

1. 의존성

1.1 AKS SDK

앱 수준 build.gradle.kts에 SDK를 추가합니다.

kotlin

dependencies {
    implementation("com.github.Pentabit-Labs-LLC:appskitsdk-android:${LATEST_VERSION}")
}

${LATEST_VERSION}을 appskitsdk-android 릴리스의 최신 태그(또는 해당 저장소 README의 JitPack 배지에 표시된 버전)로 바꿉니다. 예: v6.4.0.0.

AKS는 의존성 정보가 포함된 Maven 모듈이 아니라 개별 .aar 파일 모음으로 배포되므로, 서드 파티 의존성이 전이 의존성으로 자동 추가되지 않습니다. 아래의 모든 의존성을 앱 모듈에 명시적으로 선언해야 합니다. 유일한 예외는 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 아티팩트를 혼용하면 바이너리 호환성 문제로 런타임 크래시가 발생합니다.

앱의 나머지 부분에서도 코루틴 (1.7.3), 직렬화 (1.9.0), Firebase BOM (34.3.0), SQLDelight (2.3.2) 버전을 AKS와 일치시키세요. 의존성 그래프의 다른 곳에 이전 버전이 남아 있지 않도록 해야 합니다. Firebase BOM은 메이저 버전 간에 호환성을 깨는 변경 사항이 있었습니다 (33.x → 34.x). Gradle이 별도 경고 없이 충돌 해결 규칙에 따라 특정 버전을 선택하더라도, 이러한 라이브러리를 호출하는 AKS 코드 경로의 바이너리 호환성이 보장되는 것은 아닙니다. 이는 가능하면 따르는 권장 사항이 아니라 필수 요구 사항입니다.

1.3 모바일 측정 파트너 (MMP) SDK (항상 필요)

AKS는 AKS 포털 / Firebase Remote Config에 설정된 키를 사용해 다음 세 SDK를 자동으로 초기화합니다. 앱에서 직접 호출하지는 않지만, 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 포털 설정에 이 중 일부 SDK의 키가 없어도 괜찮습니다. AKS는 런타임에 해당 SDK의 초기화를 건너뜁니다. 다만 앱을 빌드하려면 해당 의존성은 여전히 필요합니다.

1.4 광고 네트워크 / 미디에이션 SDK

AKS는 위에서 이미 나열한 IronSource 외에도 AdMob, AppLovin MAX, Chartboost Mediation (Helium)의 핸들러 코드를 동일한 AAR에 포함합니다. 실제로 광고를 게재할 네트워크는 원격으로 결정됩니다(광고 형식별로 결정되며 장애 시 대체 네트워크로 전환). 따라서 가장 안전한 방법은 모든 SDK를 포함하는 것이며, 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")
}

AKS 포털 설정에서 특정 네트워크(예: Helium)를 절대 활성화하지 않을 것이 확실하다면 해당 블록을 제거해도 됩니다. 다만 AKS 자체의 내부 AdNetwork 장애 조치 로직은 광고 형식별로 ADMOB, GAM, MAX, IRON_SOURCE, HELIUM 중 어느 네트워크로든 전환할 수 있으므로, 이 목록을 줄이면 원격 설정으로 제어할 수 있는 범위도 줄어듭니다.

← 개요 2. AndroidManifest.xml →