문제 해결

SDK 사용 중 자주 발생하는 문제들과 해결 방법입니다.

초기화 문제

"SDK initialization failed" 에러가 나요

가능한 원인:

  1. appKey나 appSecret이 틀림

    초기화할 때 넣은 값이 맞는지 확인하세요. 공백이 들어가거나 복사할 때 잘못됐을 수 있습니다.

  2. 인터넷 연결 안 됨

    SDK 초기화할 때 애드체인 서버에 연결해서 설정을 받아옵니다. 인터넷 연결을 확인하세요.

  3. 애드체인 서버 점검 중

    드물지만 애드체인 서버 점검 중일 수 있습니다. 잠시 후 다시 시도하거나 [email protected]로 문의하세요.

해결 방법:

// Android
AdchainSdk.initialize(
    application = this,
    config = config,
    listener = object : AdchainSdkInitListener {
        override fun onSuccess() {
            Log.d("AdChain", "초기화 성공")
        }
        override fun onFailure(error: AdchainError) {
            // 에러 코드와 메시지를 확인하세요
            Log.e("AdChain", "에러 코드: ${error.code}")
            Log.e("AdChain", "메시지: ${error.message}")
        }
    }
)

에러 메시지를 복사해서 [email protected]로 보내주시면 더 빠르게 도와드릴 수 있습니다.

초기화는 됐는데 isInitialized()가 false예요

초기화는 비동기로 작동합니다. onSuccess() 콜백이 온 다음에 확인해야 합니다:

AdchainSdk.initialize(..., listener = object : AdchainSdkInitListener {
    override fun onSuccess() {
        // 여기서 확인하면 true
        if (AdchainSdk.isInitialized()) {
            // 이제 다른 기능 사용 가능
        }
    }
    ...
})

로그인 문제

로그인이 계속 실패해요

확인사항:

  1. SDK 초기화가 완료됐나요?

  2. 인터넷 연결이 되나요?

  3. userId에 특수문자가 들어갔나요?

userId는 일반적인 문자, 숫자, 하이픈, 언더스코어만 쓰는 게 안전합니다. 이모지 같은 건 피하세요.

로그인은 됐는데 오퍼월이 안 열려요

로그인 콜백을 받은 다음에 오퍼월을 열어야 합니다:

AdchainSdk.login(user, object : AdchainSdkLoginListener {
    override fun onSuccess() {
        // 로그인 성공 - 여기서 오퍼월 열기
        AdchainSdk.openOfferwall(...)
    }
    ...
})

오퍼월 문제

오퍼월이 흰 화면만 나와요

Android:

  1. 인터넷 권한 확인

    AndroidManifest.xml에 있나요?

    <uses-permission android:name="android.permission.INTERNET" />

  2. Cleartext HTTP 설정

    일부 광고가 HTTP를 씁니다. AndroidManifest.xml에:

    <application
    android:usesCleartextTraffic="true"
    ...>

iOS:

  1. App Transport Security 확인

    Info.plist에:

    <key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>

  2. 네트워크 권한

    시뮬레이터가 아닌 실제 기기에서 테스트해보세요.

오퍼월이 너무 느려요

첫 로딩은 WebView 초기화 + 콘텐츠 로드 때문에 2-3초 걸립니다. 정상입니다.

빠르게 하려면:

  1. 사용자가 버튼을 누르기 전에 미리 로딩

  2. 네트워크 상태 확인 (Wi-Fi vs 모바일 데이터)

  3. 이미지나 리소스가 많은 화면이면 시간이 더 걸릴 수 있음

"Placement not found" 에러가 나요

placementId가 애드체인 서버에 등록되지 않았을 수 있습니다. 테스트 중이라면 아무 값이나 써도 됩니다. 프로덕션에서 특정 placement를 쓰려면 [email protected]로 문의하세요.

빌드 문제

Android 빌드 에러

"Duplicate class" 에러:

./gradlew clean
./gradlew assembleDebug

안 되면:

// build.gradle
android {
    packagingOptions {
        exclude 'META-INF/*.kotlin_module'
    }
}

"Unable to resolve dependency" 에러:

settings.gradle.kts에 JitPack 저장소가 있나요?

repositories {
    google()
    mavenCentral()
    maven { url = uri("https://jitpack.io") }  // 이거
}

"Could not find io.adjoe:adjoe-sdk-android" 에러:

이 에러는 Adjoe SDK를 찾을 수 없다는 뜻입니다. AdChain SDK가 내부적으로 Adjoe SDK를 사용하기 때문에 Adjoe Maven 저장소를 추가해야 합니다.

settings.gradle.kts 또는 build.gradle에 다음을 추가하세요:

repositories {
    google()
    mavenCentral()
    maven { url = uri("https://jitpack.io") }
    maven { url = uri("https://releases.adjoe.io/maven") }  // 이거 추가
}

또는 build.gradle (allprojects):

allprojects {
    repositories {
        maven { url 'https://releases.adjoe.io/maven' }  // 이거 추가
        google()
        mavenCentral()
        maven { url 'https://www.jitpack.io' }
    }
}

저장소를 추가한 후 Gradle Sync를 다시 실행하세요.

React Native에서 Adjoe SDK 에러:

React Native 프로젝트도 동일한 문제가 발생할 수 있습니다. android/build.gradle 파일에 Adjoe 저장소를 추가하세요:

allprojects {
    repositories {
        maven { url 'https://releases.adjoe.io/maven' }  // 추가
        // 기존 저장소들...
    }
}

자세한 내용은 Android 시작하기 또는 React Native 시작하기를 참고하세요.

iOS 빌드 에러

CocoaPods 에러:

cd ios
pod deintegrate
pod install
cd ..

"Library not found" 에러:

Xcode에서 .xcworkspace 파일을 열었나요? (.xcodeproj가 아니라)

"Undefined symbol" 에러:

Xcode에서 Clean Build Folder (Cmd+Shift+K) 후 다시 빌드.

React Native 빌드 에러

Metro bundler 에러:

npm start -- --reset-cache

Android 빌드 에러:

cd android
./gradlew clean
cd ..
npx react-native run-android

iOS 빌드 에러:

cd ios
pod install
cd ..
npx react-native run-ios

이벤트 추적 문제

trackEvent()를 호출했는데 대시보드에 안 보여요

이벤트는 즉시 전송되지 않고 배치로 모아서 보냅니다 (기본: 10개 또는 30초마다).

즉시 보내려면:

AdchainSdk.trackEvent("my_event", mapOf("key" to "value"))
AdchainSdk.flushEvents()  // 즉시 전송

그리고 대시보드에 반영되려면 몇 분 걸릴 수 있습니다.

ProGuard 문제

릴리스 빌드에서 크래시가 나면 ProGuard 규칙을 추가하세요:

# AdChain SDK
-keep class com.adchain.sdk.** { *; }
-keepclassmembers class com.adchain.sdk.** { *; }

# Retrofit & OkHttp
-keepattributes Signature
-keepattributes *Annotation*
-keep class retrofit2.** { *; }
-keep class okhttp3.** { *; }

# Moshi
-keep class com.squareup.moshi.** { *; }
-keepclassmembers class ** {
    @com.squareup.moshi.* <methods>;
}

로그 확인 방법

Android

adb logcat | grep AdChain

또는 Android Studio의 Logcat에서 "AdChain" 필터.

iOS

Xcode Console에서 "AdChain" 검색.

또는 터미널에서:

log stream --predicate 'subsystem contains "AdChain"' --level debug

React Native

npx react-native log-android  # Android
npx react-native log-ios      # iOS

그래도 안 되면

위 방법으로도 안 되면:

  1. 로그 복사: 전체 에러 로그를 복사하세요

  2. 환경 정보:

    • SDK 버전

    • OS 버전 (Android 12, iOS 16 등)

    • 기기 모델

    • 재현 방법

  3. 문의: [email protected]로 위 정보와 함께 보내주세요

보통 1-2일 내로 답변 드립니다.

PreviousFAQ (자주 묻는 질문)Next릴리스 노트

Last updated