개발자 문서 · 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 릴리스의 최신 태그(예: v6.4.0.0)로 바꿉니다. 해당 저장소 README의 JitPack 배지에서도 최신 태그를 확인할 수 있습니다.

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

    // 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) 버전을 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에 포함합니다. 실제로 광고를 게재할 네트워크는 원격으로 결정되며, 광고 형식별로 장애 조치(failover)를 지원합니다. 따라서 가장 안전한 방법은 모든 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 →