Android

Android 앱에 애드체인 SDK를 연동하는 방법을 소개합니다.

시작하기 전에

SDK를 설치하기 전에 다음을 준비해주세요:

• Android Studio: Arctic Fox 이상 버전

• minSdkVersion: 24 (Android 7.0) 이상

• Kotlin: 1.9.0 이상

• appKey & appSecret: 애드체인 ADMIN에서 발급받은 인증 정보 ([email protected]로 문의)

1. Gradle 설정

settings.gradle.kts

프로젝트 루트의 settings.gradle.kts 파일을 열어서 필요한 저장소들을 추가합니다:

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://jitpack.io") }  // AdChain SDK용
        maven { url = uri("https://releases.adjoe.io/maven") }  // Adjoe SDK용 (필수)
    }
}

중요: https://releases.adjoe.io/maven 저장소는 꼭 추가해야 합니다. Adjoe SDK의 Maven 저장소 설정이 필요합니다. (자세한 내용은 아래 참조)

또는, 프로젝트가 build.gradle 파일을 사용한다면:

allprojects {
    repositories {
        maven { url 'https://releases.adjoe.io/maven' }  // Adjoe SDK용 (필수)
        google()
        mavenCentral()
        maven { url 'https://www.jitpack.io' }  // AdChain SDK용
    }
}

app/build.gradle.kts

앱 모듈의 build.gradle.kts 파일에 SDK 의존성을 추가합니다:

dependencies {
    implementation("com.github.1selfworld-labs:adchain-sdk-android:v1.0.32")

    // 기존 의존성들...
}

추가하고 나면 Gradle Sync를 실행해주세요.

2. AndroidManifest.xml 설정

app/src/main/AndroidManifest.xml 파일에 필요한 권한과 Activity를 추가합니다:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">

    <!-- 인터넷 권한 (필수) -->
    <uses-permission android:name="android.permission.INTERNET" />

    <!-- 광고 ID 권한 (필수) -->
    <uses-permission android:name="com.google.android.gms.permission.AD_ID" />

    <application>
        <!-- 기존 내용... -->

        <!-- 오퍼월 화면 추가 -->
        <activity
            android:name="com.adchain.sdk.offerwall.AdchainOfferwallActivity"
            android:configChanges="orientation|screenSize|keyboardHidden"
            android:theme="@style/Theme.AppCompat.Light.NoActionBar" />
    </application>
</manifest>

광고 ID 권한은 타겟팅 정확도를 위해 필수입니다.

3. ProGuard 설정 (릴리스 빌드 시)

릴리스 빌드에서 ProGuard나 R8을 사용한다면, proguard-rules.pro 파일에 다음을 추가해주세요:

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

# Retrofit & OkHttp (SDK 내부에서 사용)
-keepattributes Signature
-keepattributes *Annotation*
-keep class retrofit2.** { *; }
-keep class okhttp3.** { *; }

# Moshi (JSON 파싱용)
-keep class com.squareup.moshi.** { *; }
-keepclassmembers class ** {
    @com.squareup.moshi.* <methods>;
}

4. SDK 초기화

Application 클래스에서 초기화

SDK는 앱이 시작될 때 한 번만 초기화합니다. Application 클래스를 만들거나, 이미 있다면 onCreate()에 다음 코드를 추가합니다:

import android.app.Application
import com.adchain.sdk.core.AdchainSdk
import com.adchain.sdk.core.AdchainSdkConfig

class MyApplication : Application() {

    override fun onCreate() {
        super.onCreate()

        // SDK 설정
        val config = AdchainSdkConfig(
            appKey = "YOUR_APP_KEY",        // 발급받은 앱 키
            appSecret = "YOUR_APP_SECRET"   // 발급받은 시크릿
        )

        // SDK 초기화
        AdchainSdk.initialize(
            application = this,
            sdkConfig = config
        )
    }
}

그리고 AndroidManifest.xml에서 이 Application 클래스를 등록해야 합니다:

<application
    android:name=".MyApplication"
    ...>

초기화 확인하기

SDK 초기화는 백그라운드에서 비동기로 진행됩니다. 초기화 완료 여부는 아래 메서드로 확인할 수 있습니다:

if (AdchainSdk.isInitialized()) {
    // 초기화 완료 - 로그인 및 다른 기능 사용 가능
} else {
    // 아직 초기화 안 됨 - 서버 검증 진행 중
}

참고: initialize() 호출 직후에는 false일 수 있습니다. 일반적으로 앱 시작 후 1-2초 내에 완료됩니다.

5. 사용자 로그인

SDK를 사용하려면 사용자 로그인이 필요합니다. 일반적으로 앱의 로그인 화면에서 처리합니다:

import com.adchain.sdk.core.AdchainSdk
import com.adchain.sdk.core.AdchainSdkUser
import com.adchain.sdk.core.AdchainSdkLoginListener

// 사용자 정보 생성
val user = AdchainSdkUser(
    userId = "user123",                      // 앱의 사용자 ID (필수)
    gender = AdchainSdkUser.Gender.MALE,     // 성별 (선택)
    birthYear = 1990                         // 출생연도 (선택)
)

// 로그인
AdchainSdk.login(
    adchainSdkUser = user,
    listener = object : AdchainSdkLoginListener {
        override fun onSuccess() {
            // 로그인 성공
            // 이제 오퍼월이나 다른 기능 사용 가능
        }

        override fun onFailure(errorType: AdchainSdkLoginListener.ErrorType) {
            // 로그인 실패
            when (errorType) {
                AdchainSdkLoginListener.ErrorType.NOT_INITIALIZED ->
                    Log.e("AdChain", "SDK가 아직 초기화되지 않았습니다")
                AdchainSdkLoginListener.ErrorType.NETWORK_ERROR ->
                    Log.e("AdChain", "네트워크 오류")
                AdchainSdkLoginListener.ErrorType.AUTHENTICATION_FAILED ->
                    Log.e("AdChain", "인증 실패")
                else ->
                    Log.e("AdChain", "로그인 실패: $errorType")
            }
        }
    }
)

userId는 앱에서 사용하는 사용자 식별자를 사용합니다. 성별이나 출생연도는 선택사항이지만, 제공하면 광고 타겟팅 정확도가 향상됩니다.

6. 오퍼월 띄우기

버튼을 누르면 오퍼월이 열리도록 설정할 수 있습니다:

import com.adchain.sdk.core.AdchainSdk

// 버튼 클릭 시
button.setOnClickListener {
    AdchainSdk.openOfferwall(
        context = this,
        placementId = "main_offerwall"  // 배치 위치 구분용 (선택)
    )
}

placementId는 오퍼월을 여러 곳에 배치할 때 구분하려고 쓰는 건데, 일단은 아무 값이나 넣어도 됩니다.

샘플 프로젝트

전체 예제 코드를 보고 싶으시면 GitHub 샘플 프로젝트를 참고하세요:

Android 샘플: https://github.com/1selfworld-labs/adchain-sdk-android-sample

샘플 프로젝트에는 오퍼월, 퀴즈, 이벤트 추적 등 모든 기능의 사용 예시가 포함되어 있습니다.

다음 단계

기본 설정이 끝났습니다. 이제 다른 기능들을 써볼 수 있습니다:

• 오퍼월 상세 사용법

• 퀴즈 사용하기

• 미션 사용하기

• 이벤트 추적하기

문제가 생겼다면

초기화나 로그인이 안 된다면 문제 해결 페이지를 확인해보세요.