Android SDK 연동 가이드

본 문서는 Android 애플리케이션에 Mallpie SDK를 연동하기 위한 가이드입니다. SDK는 간편한 설정으로 Mallpie 서비스를 앱 내에 포함시킬 수 있는 환경을 제공합니다.

1. 연동 준비 및 요구 사항

• 최소 지원 Android 버전: Android 7.0 (API Level 24) 이상 (권장)

• 언어: Kotlin 권장

2. 프로젝트 설정 (설치)

SDK가 .aar(Android Archive) 파일 형태로 바이너리로 배포되는 경우, 패키지 내부의 외부 라이브러리 구조가 자동 해결되지 않습니다. 따라서 앱을 개발하는 모듈(app) 수준의 설정 작업이 추가로 필요합니다.

2.1 .aar 파일 프로젝트에 추가

앱 모듈의 libs 폴더에 전달받은 .aar 파일을 복사합니다. (예: app/libs/mallpie-sdk-release.aar)

2.2 build.gradle (Module: app) 설정

아래 의존성을 앱의 build.gradle 또는 build.gradle.kts 내의 dependencies { ... } 블록에 추가해주세요.

build.gradle (Module: app)

dependencies {
    // 1. SDK 로컬 파일 의존성
    implementation(fileTree(mapOf("dir" to "libs", "include" to listOf("*.aar"))))
    // 또는 특정 파일명 직접 지정: implementation(files("libs/mallpie-sdk-release.aar"))
    
    // 2. SDK 내부 작동을 위한 필수 라이브러리들 (Transitive Dependencies)
    implementation("androidx.core:core-ktx:1.9.0") // 버전은 프로젝트 상황에 맞게 최신버전 사용 권장
    implementation("androidx.appcompat:appcompat:1.6.1")
    implementation("com.google.android.material:material:1.10.0")
    implementation("androidx.activity:activity-ktx:1.8.0")
    implementation("androidx.constraintlayout:constraintlayout:2.1.4")
    
    // 코루틴 (네트워크 비동기 통신 처리용)
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3")
    
    // Google ADID (광고 식별자 획득용)
    implementation("com.google.android.gms:play-services-ads-identifier:18.0.1")
}

주의: 명시된 라이브러리들이 app 모듈에 추가되어 있지 않으면, 빌드 시점 또는 런타임에 에러(NoClassDefFoundError 등)가 발생하여 앱이 크래시될 수 있습니다.

---

3. 권한 설정 (AndroidManifest.xml)

SDK 연동을 위해 앱의 AndroidManifest.xml에 다음 권한을 추가해야 합니다.

• INTERNET: 서버 통신 및 웹뷰 컨텐츠 로드 용도

• AD_ID: 사용자 맞춤 식별 및 이벤트 트래킹을 위한 식별자(ADID) 수집 용도

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="com.google.android.gms.permission.AD_ID" />

3.1 외부 앱(결제 등) 딥링크 호출 설정 (Android 11 이상)

안드로이드 11(API Level 30) 이상 기기부터는 타사 앱(Toss, 카드사 앱, 백신 등)으로 넘어가는 딥링크(intent://)를 호출하기 위해, 매니페스트 레벨에서 외부 상호작용이 필요한 패키지나 인텐트를 미리 선언해주어야 합니다. 자세한 내용은 https://docs.tosspayments.com/guides/v2/webview 를 참고하시거나, 본 SDK의 샘플 프로젝트(MallpieAndroidMain/app) 설정을 확인해 주시기 바랍니다.

앱의 AndroidManifest.xml 내부 <manifest> 태그 바로 아래에 다음과 같이 <queries> 태그를 추가해 주시기 바랍니다.

<manifest ...>
    <!-- 권한 선언 ... -->

    <!-- 외부 결제 앱 연동을 위한 패키지명 정보 선언 -->
    <queries>
        <package android:name="vguard.android.joongang" />
        <package android:name="com.kftc.bankpay.android" />
        <package android:name="com.yettiesoft.smpay" />
        <package android:name="com.nhn.android.search" />
        <package android:name="kvp.jjy.MispAndroid320" />
        <package android:name="com.inicis.kpay" />
        <package android:name="com.shcard.smartpay" />
        <package android:name="com.shinhan.smartcaremgr" />
        <package android:name="com.kbcard.kbkookmincard" />
        <package android:name="com.kbstar.liivbank" />
        <package android:name="com.kbstar.reboot" />
        <package android:name="com.kbstar.kbbank" />
        <package android:name="nh.smart.nhallonepay" />
        <package android:name="nh.smart.mobilecard" />
        <package android:name="com.lumensoft.touchenappfree" />
        <package android:name="com.lcacApp" />
        <package android:name="com.lotte.lpay" />
        <package android:name="kr.co.samsungcard.mpocket" />
        <package android:name="com.samsung.android.spay" />
        <package android:name="kr.co.samsungcard.mpocket.hce" />
        <package android:name="com.samsung.android.samsungpay.gear" />
        <package android:name="com.wooricard.smartapp" />
        <package android:name="com.wooribank.smart.npib" />
        <package android:name="com.wooribank.pib.smart" />
        <package android:name="kr.co.citibank.citimobile" />
        <package android:name="com.hanaskcard.paycla" />
        <package android:name="kr.co.hanamembers.hm" />
        <package android:name="kr.co.hana.bcs.bcsapp" />
        <package android:name="com.hyundaicard.appcard" />
        <package android:name="com.nhn.android.payco" />
        <package android:name="com.ssg.ivs.android.sgnpay" />
        <package android:name="kr.co.tauth" />
        <package android:name="com.uplus.upluscorporation" />
        <package android:name="com.kakao.talk" />
        <package android:name="com.wooribank.pib.smart" />
        <package android:name="viva.republica.toss" />
        <package android:name="com.kakaobank.channel" />
        <package android:name="kr.co.samsunglife.monimo" />
    </queries>

    <application>
        ...

---

4. SDK 초기화 (Initialization)

앱 진입점(예: Application의 onCreate() 또는 최초 시작 Activity)에서 SDK를 초기화합니다. 정보 조회를 위해 비동기로 초기화가 진행되며, 콜백을 통해 성공 여부를 전달받을 수 있습니다.

4.1 초기화 파라미터 설명

• context: (필수) 안드로이드 Context 객체

• userKey: (필수) 사용자 고유 식별자 키

• apiKey: (필수) 발급받은 Mallpie API 키

• isDev: (선택) 개발 환경 여부 설정 (기본값: false)

• allowsSwipeBack: (선택) 스와이프 백 제스처 (왼쪽 엣지 스와이프) 활성화 여부 (기본값: false)

• backKeyBehavior: (선택) 하드웨어 뒤로 가기 버튼 동작 설정 (기본값: HISTORY)

• headerViewProvider: (선택) SDK 상단에 표시할 커스텀 헤더 뷰를 제공하는 콜백

• onBackKeyListener: (선택) 하드웨어 백 버튼 이벤트를 직접 제어할 리스너 (APP_CALLBACK 모드 사용 시)

• completion_handler: (선택) 초기화 완료 혹은 실패 결과를 전달받는 콜백

4.2 초기화 예시 코드

Kotlin

import com.genieworks.mallpiesdk.MallpieSDK
import com.genieworks.mallpiesdk.MallpieActivity

// ...

MallpieSDK.initialize(
    context = this,
    userKey = "YOUR_USER_KEY", // 발급받은 User Key
    apiKey = "YOUR_API_KEY",   // 발급받은 API Key
    isDev = false,             // 개발 환경 여부 (기본값: false)
    allowsSwipeBack = true,    // 스와이프 백 제스처 (기본값: false)
    backKeyBehavior = MallpieActivity.BackKeyBehavior.HISTORY, 
    completion_handler = { error ->
        if (error == null) {
            // 초기화 성공
            Log.d("Mallpie", "SDK 초기화 성공")
        } else {
            // 에러 처리 (error.message 참고)
            Log.e("Mallpie", "SDK 초기화 실패: ${error.message}")
        }
    }
)

4.3 뒤로 가기 동작 모드 (BackKeyBehavior)

MallpieSDK.initialize 파라미터 또는 서버/JS 콜백을 통해 하드웨어 뒤로 가기 버튼 동작을 4가지로 지정할 수 있습니다.

• HISTORY (기본값): 웹뷰의 이전 방문 기록이 있으면 뒤로 이동하고, 기록이 없으면 화면을 종료합니다.

• DEFAULT: 웹뷰 히스토리와 무관하게 즉시 네이티브 화면을 종료합니다.

• JS_CALLBACK: 뒤로가기 입력 시 네이티브 로직을 무시하고 자바스크립트의 onMallpieBack() 함수를 호출합니다. SPA(Single Page App) 형태에서 자체 라우터 제어가 필요할 때 유용합니다.

• APP_CALLBACK: 네이티브 초기화 시 설정한 onBackKeyListener 커스텀 리스너를 호출합니다.

---

5. SDK 화면 호출 및 사용

SDK 내장 MallpieActivity를 통해 Mallpie 전체 화면 영역을 노출하려면 start() 메서드를 호출합니다. 초기화가 내부적으로 완료되지 않았더라도 start()를 미리 호출하면 예약 모드로 전환되어, 권한과 네트워크 점검이 끝난 직후 화면이 자동으로 표시됩니다.

Kotlin

// 호출하려는 액티비티 내부에서 실행
val result = MallpieSDK.start(this)

if (result.isFailure) {
    Log.e("MallpieSDK", "런칭 실패: ${result.exceptionOrNull()?.message}")
}

---

6. 하이브리드 앱 또는 커스텀 UI 내 웹뷰 생성

SDK 기본 화면 액티비티를 사용하지 않고 앱 내의 특정 레이아웃, 프래그먼트, 탭 등에 임베디드 웹뷰를 직접 삽입하고 싶을 때는 createWebView()를 사용합니다.

Kotlin

// 1. SDK로부터 연동 규칙이 적용된 커스텀 웹뷰 인스턴스 생성
val mallpieWebView = MallpieSDK.createWebView(this)

// 2. 원하는 부모 레이아웃에 추가 (예: FrameLayout, LinearLayout 등)
binding.containerView.addView(mallpieWebView)

// 3. 로드할 URL 획득 및 렌더링
val urlResult = MallpieSDK.getMallpieUrl()
if (urlResult.isSuccess) {
    mallpieWebView.loadMallpieUrl(urlResult.getOrNull()!!)
} else {
    // 초기화 파라미터가 누락되었거나 환경 구성 실패 시 예외 처리
}

---

7. 고급 설정 및 이벤트 제어

7.1 커스텀 헤더 뷰 생성 (HeaderViewProvider)

기본으로 열리는 MallpieActivity 최상단에, 서비스 고유의 네이티브 뒤로 가기 버튼이나 로고 등을 직접 그리고 싶을 경우 사용할 수 있습니다.

Kotlin

MallpieSDK.initialize(
    // ... 기본 파라미터 생략 ...
    headerViewProvider = { activity ->
        // LayoutInflater를 통해 커스텀 디자인 뷰 반환
        val customHeader = LayoutInflater.from(activity).inflate(R.layout.my_custom_header, null)
        
        // 닫기 버튼 이벤트 바인딩 예시
        customHeader.findViewById<ImageView>(R.id.btn_close).setOnClickListener {
            activity.finish()
        }
        
        customHeader // 생성한 뷰 반환
    }
)

7.2 백 키 리스너 등록 (OnBackKeyListener)

모드를 APP_CALLBACK으로 설정한 경우 뒤로 가기를 가로채어 직접 처리할 수 있습니다.

Kotlin

MallpieSDK.initialize(
    // ... 기본 파라미터 생략 ...
    backKeyBehavior = MallpieActivity.BackKeyBehavior.APP_CALLBACK,
    onBackKeyListener = { activity, webView ->
        // 예: 종료 묻기 다이얼로그 표시
        AlertDialog.Builder(activity)
            .setMessage("쇼핑 화면을 종료하시겠습니까?")
            .setPositiveButton("종료") { _, _ -> activity.finish() }
            .setNegativeButton("취소", null)
            .show()
    }
)

---

8. 에러 핸들링 가이드 (MallpieSDKError)

SDK 초기화 및 구동 중 예외 상황이 발생하면 completion_handler 콜백을 통해 MallpieSDKError 객체가 반환됩니다. 에러 객체는 고유의 code와 message, 그리고 errorType을 포함하고 있어 서비스 측에서 상황에 맞는 적절한 UI 처리 및 예방 로직을 작성할 수 있습니다.

8.1 에러 확인 방법 예시

Kotlin

MallpieSDK.initialize(
    // ... 생략 ...
    completion_handler = { error ->
        if (error != null) {
            when (error) {
                // 특정 에러 코드 타입에 따른 대응
                is MallpieSDKError.SHOP_ID_NOT_INITIALIZED -> {
                    // API 응답 이상 또는 통신 불가 상태 노출
                    Log.e("Mallpie", "[E001] Shop ID 획득 실패. 통신 상태를 확인해주세요.")
                }
                is MallpieSDKError.NETWORK_ERROR -> {
                    // 사용자에게 네트워크 연결 확인 안내 
                    Toast.makeText(this, "네트워크 연결을 확인해주세요.", Toast.LENGTH_SHORT).show()
                }
                // 공통된 정보 출력
                else -> {
                    Log.e("Mallpie", "SDK 초기화 실패 [${error.code}]: ${error.message}")
                }
            }
        } else {
            // ... 성공 로직 ...
        }
    }
)

8.2 SDK 에러 명세

인증 및 초기화 관련 (E0xx)

에러 케이스 (클래스명)	대응 에러 코드	설명
SHOP_ID_NOT_INITIALIZED	E001	Shop ID가 초기화되지 않았습니다. API 연결 상태를 확인해주세요.
MEDIA_KEY_NOT_INITIALIZED	E002	API Key(Media Key)가 누락되거나 유효하지 않습니다.
USER_KEY_NOT_INITIALIZED	E003	User Key가 누락되었습니다. SDK 초기화 시점에 올바른 사용자 키를 입력해야 합니다.
INITIALIZING	E004	SDK가 이미 초기화 중입니다. 이전 호출의 응답을 기다려주세요.

네트워크 및 시스템 연동 (E1xx ~ E3xx)

에러 케이스 (클래스명)	대응 에러 코드	설명
NETWORK_ERROR	E100	네트워크 연결 오류 혹은 서버 상태 이상 시 발생합니다. (추가 detail 정보 포함)
INTERNAL_API_ERROR	E200	Mallpie 서버 간의 내부 통신 에러 발생 시 반환됩니다. (추가 detail 정보 포함)
OTHER_ERROR	E300	SDK 구동 중 알 수 없는 예외 상황 발생 시 반환됩니다. errorType에 따라 치명적 여부를 판단할 수 있습니다.

주의 (경고성 메시지)

에러 케이스 (클래스명)	대응 에러 코드	설명
AD_ID_NOT_INITIALIZED	W001	광고 식별자(ADID) 수집 실패. (SDK 기능 자체는 정상 작동하나, 추천상품 등 개인화된 서비스 제공에 제한이 있을 수 있습니다.)

---

끝.