# 문제 해결

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

## 초기화 문제

### "SDK initialization failed" 에러가 나요

**가능한 원인:**

1. **appKey나 appSecret이 틀림**

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

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

   드물지만 애드체인 서버 점검 중일 수 있습니다. 잠시 후 다시 시도하거나 <contact@1self.world>로 문의하세요.

문제가 계속되면 로그를 복사해서 <contact@1self.world>로 보내주시면 더 빠르게 도와드릴 수 있습니다.

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

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

```typescript
await AdchainSdk.initialize({ appKey: '...', appSecret: '...' });

// 약간 후에 확인
const isReady = await AdchainSdk.isInitialized();
```

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

## 로그인 문제

### 로그인이 계속 실패해요

**확인사항:**

1. SDK 초기화가 완료됐나요?
2. 인터넷 연결이 되나요?
3. userId에 특수문자가 들어갔나요?

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

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

`login()`이 완료된 후 오퍼월을 열어야 합니다. `await`로 로그인이 끝날 때까지 기다리세요:

```typescript
await AdchainSdk.login({ userId: 'user123' });
await AdchainSdk.openOfferwall('main_offerwall');
```

## 오퍼월 문제

### 오퍼월이 흰 화면만 나와요

**Android 측 확인:**

1. **인터넷 권한 확인** — `android/app/src/main/AndroidManifest.xml`에 있나요?

   ```xml
   <uses-permission android:name="android.permission.INTERNET" />
   ```
2. **Cleartext HTTP 설정** — 일부 광고가 HTTP를 씁니다:

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

**iOS 측 확인:**

1. **App Transport Security 확인** — `ios/YourApp/Info.plist`에:

   ```xml
   <key>NSAppTransportSecurity</key>
   <dict>
       <key>NSAllowsArbitraryLoads</key>
       <true/>
   </dict>
   ```
2. **실제 기기 테스트** — 시뮬레이터가 아닌 실제 기기에서 테스트해보세요.

### 오퍼월이 너무 느려요

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

**빠르게 하려면:**

1. 사용자가 버튼을 누르기 전에 미리 로딩
2. 네트워크 상태 확인 (Wi-Fi vs 모바일 데이터)
3. 이미지나 리소스가 많은 화면이면 시간이 더 걸릴 수 있음

### "Placement not found" 에러가 나요

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

## 빌드 문제

### Android 빌드 에러

**일반 클린 빌드:**

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

**"Duplicate class" 에러:** `android/app/build.gradle`에 다음을 추가:

```groovy
android {
    packagingOptions {
        exclude 'META-INF/*.kotlin_module'
    }
}
```

**"Unable to resolve dependency" 에러:** `android/build.gradle`에 JitPack 저장소가 있는지 확인하세요. ([시작하기 — Android 추가 설정](https://adchain-doc.1self.world/undefined-6/pages/olDNQ4trPQXTXbo5mq9b#3-android-추가-설정-필수) 참고)

### iOS 빌드 에러

**CocoaPods 에러:**

```bash
cd ios
pod deintegrate
pod install
cd ..
```

**"Library not found" 에러:** Xcode에서 `.xcworkspace` 파일을 열었나요? (`.xcodeproj`가 아니라)

**"Undefined symbol" 에러:** Xcode에서 Clean Build Folder (Cmd+Shift+K) 후 다시 빌드.

### Metro bundler 에러

```bash
npm start -- --reset-cache
```

## ProGuard 문제

릴리스 빌드에서 크래시가 나면 `android/app/proguard-rules.pro`에 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>;
}
```

## 로그 확인 방법

### React Native (Metro)

가장 먼저 Metro 콘솔을 확인하세요. `console.log`로 찍은 로그가 여기 나옵니다.

### Android 네이티브 로그

```bash
npx react-native log-android
```

또는 `AdChain` 키워드로 필터링:

```bash
adb logcat | grep AdChain
```

### iOS 네이티브 로그

```bash
npx react-native log-ios
```

또는 Xcode Console에서 "AdChain" 검색.

## 그래도 안 되면

위 방법으로도 안 되면:

1. **로그 복사**: 전체 에러 로그를 복사하세요
2. **환경 정보**:
   * SDK 버전
   * React Native 버전
   * OS 버전 (Android 12, iOS 16 등)
   * 기기 모델
   * 재현 방법
3. **문의**: <contact@1self.world>로 위 정보와 함께 보내주세요

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://adchain-doc.1self.world/undefined-6/common-issues.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.