iOS SDK 연동 가이드

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

1. 연동 준비 및 요구 사항

• 최소 지원 iOS 버전: iOS 13.0 이상

• 언어: Swift

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

[MallpieSDK.xcframework] 파일을 Xcode 프로젝트에 추가해야 합니다.

1

Xcode 프로젝트 네비게이터 열기

Xcode 프로젝트 네비게이터(Project Navigator)를 엽니다.

2

General 탭으로 이동

타겟(Target) 설정의 General 탭으로 이동합니다.

3

Frameworks, Libraries, and Embedded Content에 추가

Frameworks, Libraries, and Embedded Content 섹션에 MallpieSDK.xcframework를 끌어다 놓습니다.

4

Embed 옵션 확인

추가된 프레임워크의 Embed 옵션이 Embed & Sign 으로 설정되어 있는지 확인합니다.

3. 권한 설정 (Info.plist)

추적 권한(App Tracking Transparency)을 획득하기 위해 애플리케이션의 Info.plist 파일에 다음 항목을 반드시 추가해야 합니다. 이 권한은 SDK 내부적으로 ADID 식별자를 수집하여 사용자 식별을 돕는 데 사용됩니다. (이 권한 팝업은 iOS 14.0 이상 기기에서 동작하며, SDK가 이를 적절히 처리합니다.)

<key>NSUserTrackingUsageDescription</key>
<string>고객님에게 맞춤형 서비스 혜택을 제공하기 위해 추적 권한이 필요합니다.</string>

3.1 외부 앱(결제 등) 딥링크 호출 설정 (Info.plist)

Mallpie 서비스 내에서 토스페이먼츠(Toss Payments) 및 기타 카드사 앱을 통해 결제를 진행하려면 해당 앱들의 스키마(Scheme)가 SDK 호스트 앱의 Info.plist 내 권한 목록에 선언되어 있어야 합니다. 애플 정책상 이를 누락하면 외부 결제 수단으로 넘어갈 수 없습니다. 자세한 내용은 토스페이먼츠 웹뷰 가이드를 참고하시거나, 본 SDK의 샘플 프로젝트(MallpieIOSSample) 설정을 확인해 주시기 바랍니다.

<key>LSApplicationQueriesSchemes</key>
<array>
    <string>supertoss</string>
    <string>kb-acp</string>
    <string>liivbank</string>
    <string>newliiv</string>
    <string>kbbank</string>
    <string>nhappcardansimclick</string>
    <string>nhallonepayansimclick</string>
    <string>nonghyupcardansimclick</string>
    <string>lottesmartpay</string>
    <string>lotteappcard</string>
    <string>mpocket.online.ansimclick</string>
    <string>ansimclickscard</string>
    <string>tswansimclick</string>
    <string>ansimclickipcollect</string>
    <string>vguardstart</string>
    <string>samsungpay</string>
    <string>scardcertiapp</string>
    <string>shinhan-sr-ansimclick</string>
    <string>smshinhanansimclick</string>
    <string>com.wooricard.wcard</string>
    <string>newsmartpib</string>
    <string>citispay</string>
    <string>citicardappkr</string>
    <string>citimobileapp</string>
    <string>cloudpay</string>
    <string>hanawalletmembers</string>
    <string>hdcardappcardansimclick</string>
    <string>smhyundaiansimclick</string>
    <string>shinsegaeeasypayment</string>
    <string>payco</string>
    <string>lpayapp</string>
    <string>ispmobile</string>
    <string>tauthlink</string>
    <string>ktauthexternalcall</string>
    <string>upluscorporation</string>
    <string>kftc-bankpay</string>
    <string>kakaotalk</string>
    <string>wooripay</string>
    <string>lmslpay</string>
    <string>naversearchthirdlogin</string>
    <string>hanaskcardmobileportal</string>
    <string>kb-bankpay</string>
    <string>kakaobank</string>
    <string>monimopay</string>
    <string>monimopayauth</string>
</array>

4. SDK 초기화 (Initialization)

앱이 시작되는 시점(예: AppDelegate의 didFinishLaunchingWithOptions 내부)에 MallpieSDK.shared.initialize() 메서드를 한 번 호출하여 SDK를 초기화합니다.

4.1 초기화 파라미터 설명

• userKey: (필수) 암호화된 사용자 고유 식별자 키 (복호화 필요 없음.)

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

• isTrackingEnabled: (선택) ADID 수집 활성화 여부 (기본값: true)

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

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

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

• footerViewProvider: (선택) SDK 하단에 표시할 커스텀 푸터 뷰를 제공하는 클로저

• delegate: (선택) 뒤로가기 및 화면 닫힘 이벤트를 제어할 델리게이트 객체

• completion_handler: (선택) 초기화 완료 혹은 실패 결과를 전달받는 클로저 (nil 이면 결과 상관없이 패스)

4.2 초기화 예시 코드

import UIKit
import MallpieIOS

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    var window: UIWindow?

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        
        // 1. SDK 초기화
        MallpieSDK.shared.initialize(
            userKey: "사용자_고유_키",
            apiKey: "발급받은_API_KEY",
            isDev: false,
            allowsSwipeBack: true,
            completion_handler: { error in
                if error == nil {
                    print("SDK 초기화 성공")
                } else {
                    print("SDK 초기화 실패: \(String(describing: error))")
                }
            }
        )
        
        // 2. 윈도우 구성 
        let window = UIWindow(frame: UIScreen.main.bounds)
        window.rootViewController = MyRootViewController() // 여러분의 루트 뷰컨트롤러
        self.window = window
        window.makeKeyAndVisible()
        
        return true
    }
}

// 닫기 버튼의 Action을 처리할 헬퍼 클래스 예시
class CloseActionTarget {
    weak var viewController: UIViewController?
    
    init(viewController: UIViewController) {
        self.viewController = viewController
    }
    
    @objc func close() {
        guard let vc = viewController else { return }
        if let nav = vc.navigationController ?? vc.presentedViewController?.navigationController {
            nav.popViewController(animated: true)
        } else {
            vc.dismiss(animated: true)
        }
    }
}

5. SDK 화면 호출 및 사용

앱의 특정 화면(버튼 클릭 이벤트 등)에서 SDK 진입을 실행할 때는 start() 메서드를 호출합니다.

import MallpieIOS

// SDK를 띄울 ViewController를 명시적으로 파라미터로 전달합니다. (내부적으로 Push 또는 Present 처리됨)
let result = MallpieSDK.shared.start(from: self)

switch result {
case .success:
    print("SDK 화면 호출 성공")
case .failure(let error):
    print("SDK 화면 호출 실패: \(error)")
}

참고: start()를 호출한 시점에 아직 initialize() 과정이 끝나지 않았다면, SDK는 초기화가 끝날 때까지 백그라운드 모드로 대기한 뒤 완료 즉시 자동으로 화면을 띄워줍니다.

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

기본 화면 호출 방식 외에도, 직접 네이티브 뷰(UIView) 계층에 Mallpie 전용 웹뷰를 삽입하고 싶을 때는 createWebView()를 사용합니다.

if let mallpieWebView = MallpieSDK.shared.createWebView() {
    // 반환된 mallpieWebView 객체를 뷰 계층에 추가해주면 됩니다.
    mallpieWebView.translatesAutoresizingMaskIntoConstraints = false
    view.addSubview(mallpieWebView)
    
    // 오토 레이아웃 설정
    NSLayoutConstraint.activate([
        mallpieWebView.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor),
        mallpieWebView.leadingAnchor.constraint(equalTo: view.leadingAnchor),
        mallpieWebView.trailingAnchor.constraint(equalTo: view.trailingAnchor),
        mallpieWebView.bottomAnchor.constraint(equalTo: view.bottomAnchor)
    ])
} else {
    print("SDK 초기화가 완료되지 않아 뷰를 생성할 수 없습니다.")
}

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

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

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

MallpieSDK.shared.initialize(
    // ... 기본 파라미터 생략 ...
    headerViewProvider: { viewController in
        // 상단에 표시될 커스텀 헤더 UI 생성 (예: 높이 50)
        let header = UIView(frame: CGRect(x: 0, y: 0, width: UIScreen.main.bounds.width, height: 50))
        header.backgroundColor = .systemBlue
        
        // 닫기 버튼 생성
        let closeButton = UIButton(type: .system)
        closeButton.setTitle("닫기", for: .normal)
        closeButton.setTitleColor(.white, for: .normal)
        closeButton.translatesAutoresizingMaskIntoConstraints = false
        
        // 닫기 버튼 액션 연결 (#selector 방식)
        let target = CloseActionTarget(viewController: viewController)
        // 액션 타겟을 메모리에 유지하기 위해 associated object 등으로 참조를 잡아두는 것을 권장합니다.
        objc_setAssociatedObject(closeButton, "closeAction", target, .OBJC_ASSOCIATION_RETAIN_NONATOMIC)
        closeButton.addTarget(target, action: #selector(CloseActionTarget.close), for: .touchUpInside)
        
        header.addSubview(closeButton)
        
        // ... 제약 조건 설정 로직 등 (예제 생략)
        return header
    }
)

7.2 커스텀 푸터 뷰 생성 (FooterViewProvider)

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

MallpieSDK.shared.initialize(
    // ... 기본 파라미터 생략 ...
    footerViewProvider: { viewController in
        // 하단에 표시될 커스텀 푸터 UI 생성 (예: 높이 60)
        let footer = UIView(frame: CGRect(x: 0, y: 0, width: UIScreen.main.bounds.width, height: 60))
        footer.backgroundColor = .systemGroupedBackground
        
        let label = UILabel()
        label.text = "커스텀 푸터 영역"
        label.sizeToFit()
        footer.addSubview(label)
        
        return footer
    }
)

7.3 SDK 델리게이트 이벤트 수신 (MallpieSDKDelegate)

MallpieSDK.shared.initialize() 선언부 영역에서 등록할 수 있는 MallpieSDKDelegate 델리게이트는 사용자가 뒤로가기 동작을 했거나 화면이 사라지는 시점을 후킹하여 동작을 제어할 수 있도록 도와줍니다.

class MySDKDelegate: MallpieSDK.MallpieSDKDelegate {
    static let shared = MySDKDelegate()
    
    func mallpieSDKShouldHandleBackAction(_ webView: MallpieWebView) -> Bool {
        // 뒤로가기 액션(왼쪽 스와이프 등)이 발생했을 때 호출됩니다.
        // webView.canGoBack 을 파악하여 현재 웹뷰의 히스토리 등을 판별할 수 있습니다.
        
        // true를 반환하면 SDK의 내부 기본 동작(웹 히스토리 백 -> 없으면 화면 종료)을 따릅니다.
        // false를 반환하면 SDK가 자체적으로 아무 행동도 하지 않아 연동 측에서 직접 제어가 가능합니다.
        return true 
    }
    
    func mallpieSDKWillDismiss() {
        // SDK 화면 자체가 닫히기 직전에 최종적으로 호출됩니다.
        print("SDK 뷰가 닫힙니다.")
    }
}

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

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

MallpieSDK.shared.addCustomAction(functionName: "myCustomFunction") { payload in
    print("웹에서 전달받은 데이터: \(payload ?? "없음")")
    // 원하는 네이티브 동작 수행
}

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

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

// 푸터 숨기기
MallpieSDK.shared.setFooterVisible(false)

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

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

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

let currentUrl = MallpieSDK.shared.getCurrentUrl()
if let url = currentUrl {
    print("현재 로드된 URL: \(url)")
}

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

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

MallpieSDK.shared.onPageNavigation = { url in
    print("웹뷰 페이지 이동 감지: \(url)")
    // 필요한 애널리틱스 트래킹이나 조건부 네이티브 로직 수행
}

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

SDK 초기화 및 구동 중 예외 상황이 발생하면 completion_handler 콜백을 통해 MallpieSDKError 열거형(Enum) 객체가 반환됩니다. 에러 객체는 고유의 케이스를 가지고 있어 서비스 측에서 상황에 맞는 적절한 UI 처리 및 예방 로직을 작성할 수 있습니다.

8.1 에러 확인 방법 예시

MallpieSDK.shared.initialize(
    // ... 파라미터 생략 ...
    completion_handler: { error in
        if let error = error {
            switch error {
            case .shopIdNotInitialized:
                print("[E001] Shop ID 획득 실패. 통신 상태를 확인해주세요.")
            case .networkError(let message):
                print("[E100] 네트워크 에러 발생: \(message)")
            default:
                print("SDK 초기화 실패: \(error)")
            }
        } else {
            print("SDK 초기화 성공")
        }
    }
)

8.2 SDK 에러 명세 (MallpieSDKError Enum)

인증 및 초기화 관련 (E0xx)

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

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

에러 케이스	대응 에러 코드	설명
networkError(message:)	E100	네트워크 연결 오류 혹은 서버 상태 이상 시 발생합니다.
internalApiError(message:)	E200	Mallpie 서버 간의 내부 통신 에러 발생 시 반환됩니다.
otherError(message:)	E300	SDK 구동 중 알 수 없는 예외 상황 발생 시 반환됩니다.

주의 (경고성 메시지)

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