> For the complete documentation index, see [llms.txt](https://help-partner.mallpie.kr/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help-partner.mallpie.kr/api/sdk/android-sdk.md).

# Android SDK 연동 가이드

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

## 1. 연동 준비 및 요구 사항

* **최소 지원 Android 버전**: Android 7.0 (API Level 24) 이상 (권장)
* **언어**: Kotlin 권장

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

SDK가 `.aar`(Android Archive) 파일 형태로 바이너리로 배포되는 경우, 패키지 내부의 외부 라이브러리 구조가 자동 해결되지 않습니다. 따라서 앱을 개발하는 모듈(`app`) 수준의 설정 작업이 추가로 필요합니다.\
[\[MallpieSDK-release.aar\]](https://next-sellerd-stg.s3.ap-northeast-2.amazonaws.com/cps/prd/sdk/MallpieSDK-release.aar)

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

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

### 2.2 `build.gradle` (Module: `app`) 설정

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

```gradle
dependencies {
    // 1. SDK 로컬 파일 의존성
    implementation(fileTree(mapOf("dir" to "libs", "include" to listOf("*.aar"))))
    // 또는 특정 파일명 직접 지정: implementation(files("libs/mallpie-sdk-release-v1.0.1.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")
}
```

{% hint style="warning" %}
명시된 라이브러리들이 `app` 모듈에 추가되어 있지 않으면, 빌드 시점 또는 런타임에 에러(`NoClassDefFoundError` 등)가 발생하여 앱이 크래시될 수 있습니다.
{% endhint %}

## 3. 권한 설정 (AndroidManifest.xml)

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

* **INTERNET**: 서버 통신 및 웹뷰 컨텐츠 로드 용도
* **AD\_ID**: 사용자 맞춤 식별 및 이벤트 트래킹을 위한 식별자(ADID) 수집 용도

```xml
<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>` 태그를 추가해 주시기 바랍니다.

```xml
<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 키
* `isTrackingEnabled`: (선택) ADID 수집 활성화 여부 (기본값: `true`)
* `isDev`: (선택) 개발 환경 여부 설정 (기본값: `false`)
* `allowsSwipeBack`: (선택) 스와이프 백 제스처 (왼쪽 엣지 스와이프) 활성화 여부 (기본값: `false`)
* `backKeyBehavior`: (선택) 하드웨어 뒤로 가기 버튼 동작 설정 (기본값: `HISTORY`)
* `headerViewProvider`: (선택) SDK 상단에 표시할 커스텀 헤더 뷰를 제공하는 콜백
* `footerViewProvider`: (선택) SDK 하단에 표시할 커스텀 푸터 뷰를 제공하는 콜백
* `onBackKeyListener`: (선택) 하드웨어 백 버튼 이벤트를 직접 제어할 리스너 (`APP_CALLBACK` 모드 사용 시)
* `completion_handler`: (선택) 초기화 완료 혹은 실패 결과를 전달받는 콜백

### 4.2 초기화 예시 코드

```kotlin
import com.genieworks.mallpiesdk.android.MallpieSDK
import com.genieworks.mallpiesdk.android.MallpieActivity

// ...

MallpieSDK.initialize(
    context = this,
    userKey = "YOUR_USER_KEY", // 매체사 User Key 유저 식별값→ 회원 식별을 위한 해당 서비스의 고유한 userKey DATA로 몰파이 호출시에는 암호화하여 전달 50자 이내
    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 커스텀 푸터 뷰 생성 (FooterViewProvider)

기본으로 열리는 `MallpieActivity` 최하단에, 앱 고유의 커스텀 내비게이션 바나 안내 문구 등을 포함하고 싶을 경우 사용할 수 있습니다.

```kotlin
MallpieSDK.initialize(
    // ... 기본 파라미터 생략 ...
    footerViewProvider = { activity ->
        // 하단에 표시될 커스텀 푸터 UI 생성
        val footer = android.widget.LinearLayout(activity)
        footer.setBackgroundColor(android.graphics.Color.LTGRAY)
        
        val textView = android.widget.TextView(activity)
        textView.text = "커스텀 푸터 영역"
        footer.addView(textView)
        
        footer
    }
)
```

### 7.3 백 키 리스너 등록 (OnBackKeyListener)

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

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

### 7.4 자바스크립트 커스텀 네이티브 동작 추가 (`addCustomAction`)

Mallpie 웹뷰 내에서 호출할 수 있는 커스텀 네이티브 동작을 등록할 수 있습니다. 자바스크립트에서 특정 함수명으로 네이티브 이벤트를 호출할 수 있도록 연결합니다.

```kotlin
MallpieSDK.addCustomAction("myCustomFunction") { payload ->
    Log.d("Mallpie", "웹에서 전달받은 데이터: $payload")
    // 원하는 네이티브 동작 수행
}
```

### 7.5 푸터(Footer) 노출 설정 (`setFooterVisible`)

SDK 내부 하단 영역에 노출되는 푸터의 가시성을 동적으로 제어할 수 있습니다.

```kotlin
// 푸터 숨기기
MallpieSDK.setFooterVisible(false)

// 푸터 다시 보이기
MallpieSDK.setFooterVisible(true)
```

### 7.6 현재 웹뷰 URL 가져오기 (`getCurrentUrl`)

현재 실행 중인 Mallpie 웹뷰의 URL을 프로그래밍 방식으로 확인할 수 있습니다.

```kotlin
val currentUrl = MallpieSDK.getCurrentUrl()
if (currentUrl != null) {
    Log.d("Mallpie", "현재 로드된 URL: $currentUrl")
}
```

### 7.7 웹뷰 페이지 이동 이벤트 수신 (`onPageNavigation`)

웹뷰 내에서 새로운 페이지로 로딩이 시작될 때마다 호출되는 콜백을 등록하여, 현재 진입하는 URL을 실시간으로 확인할 수 있습니다.

```kotlin
MallpieSDK.onPageNavigation = { url ->
    Log.d("Mallpie", "웹뷰 페이지 이동 감지: $url")
    // 필요한 애널리틱스 트래킹이나 조건부 네이티브 로직 수행
}
```

## 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 기능 자체는 정상 작동하나, 추천상품 등 개인화된 서비스 제공에 제한이 있을 수 있습니다.) |