문제 해결

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

초기화 문제

"SDK initialization failed" 에러가 나요

가능한 원인:

1. appKey나 appSecret이 틀림

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

2. 인터넷 연결 안 됨

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

3. 애드체인 서버 점검 중

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

해결 방법:

// Android
val config = AdchainSdkConfig(
    appKey = "YOUR_APP_KEY",
    appSecret = "YOUR_APP_SECRET"
)

AdchainSdk.initialize(
    application = this,
    sdkConfig = config
)

// 초기화 상태 확인
Handler(Looper.getMainLooper()).postDelayed({
    if (AdchainSdk.isInitialized()) {
        Log.d("AdChain", "초기화 성공")
    } else {
        Log.e("AdChain", "초기화 실패 - 네트워크나 인증키 확인 필요")
    }
}, 2000) // 2초 후 확인

문제가 계속되면 로그를 복사해서 [email protected]로 보내주시면 더 빠르게 도와드릴 수 있습니다.

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

SDK 초기화는 백그라운드에서 비동기로 진행됩니다. initialize() 호출 직후에는 false일 수 있습니다:

// Application onCreate()
AdchainSdk.initialize(this, config)

// 바로 확인하면 false일 수 있음
Log.d("AdChain", "즉시: ${AdchainSdk.isInitialized()}") // false 가능

// 잠시 후 확인 (1-2초 소요)
Handler(Looper.getMainLooper()).postDelayed({
    if (AdchainSdk.isInitialized()) {
        // 이제 다른 기능 사용 가능
        Log.d("AdChain", "초기화 완료")
    }
}, 2000)

참고: 일반적으로 앱이 시작되고 사용자가 로그인하기 전까지 충분한 시간이 있으므로, 명시적으로 대기할 필요는 없습니다.

로그인 문제

로그인이 계속 실패해요

확인사항:

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

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

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

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

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

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

AdchainSdk.login(
    adchainSdkUser = user,
    listener = object : AdchainSdkLoginListener {
        override fun onSuccess() {
            // 로그인 성공 - 여기서 오퍼월 열기
            AdchainSdk.openOfferwall(
                context = this@MainActivity,
                placementId = "main"
            )
        }
        override fun onFailure(errorType: AdchainSdkLoginListener.ErrorType) {
            Log.e("AdChain", "로그인 실패: $errorType")
        }
    }
)

오퍼월 문제

오퍼월이 흰 화면만 나와요

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일 내로 답변 드립니다.