Unity IAP 5: IAP 4에서 변경된 사항과 마이그레이션 방법은 무엇인가요?
관련주제
- #Unity
- # IAP 5
- # IAP 4
- # 마이그레이션
- # StoreKit 1
2026.08.12
Unity 인앱 구매(IAP) 버전 5는 IAP 4의 인터페이스 기반 아키텍처를 단일 이벤트 기반 StoreController 클래스로 대체합니다. 마이그레이션을 위해서는 코드 변경이 필요합니다. IStoreListener 및 IDetailedStoreListener 인터페이스와 ConfigurationBuilder가 제거되고, 초기화는 비동기적으로 이루어지며, 구매는 라이프사이클 이벤트를 통해 처리됩니다. IAP 5는 웹에서 모바일로의 수익 창출, 맞춤형 결제 처리기(예: Stripe 및 Coda) 및 독립형 웹숍도 지원합니다.
Unity IAP 5에 대해 알아야 할 사항
- Unity IAP 5에서는 IAP 4에 필요했던 IStoreListener 및 IDetailedStoreListener 인터페이스가 제거되었습니다.
- Unity IAP 5의 모든 구매 로직은 하나의 클래스를 통해 실행됩니다. UnityIAPServices.StoreController()는 구매 라이프사이클 전반에 걸쳐 이벤트를 발생시킵니다.
- IAP 4의 ConfigurationBuilder가 제거되었습니다. 제품 정의는 ID와 제품 유형을 포함하는 ProductDefinition 객체로 FetchProducts() 함수에 직접 전달됩니다.
- IAP 5에서는 기존 ID 클래스의 이름이 StoreSpecificIds로 변경되었습니다.
- Unity IAP 5 초기화는 비동기식이며, await UnityServices.InitializeAsync()를 통해 Unity Gaming Services 먼저 초기화되어야 합니다.
- IAP 5의 Apple 영수증은 개발자에게 전달되기 전에 StoreKit 2를 통해 자동으로 유효성 검사를 거칩니다. Google Play 스토어 인증을 받으려면 개발자의 Google 라이선스 키가 필요하며, 이 키는 IAP 패키지에 포함된 도구를 사용하여 난독화됩니다.
- iOS 15.0으로 업그레이드할 수 없는 기기(iPhone 6s 이전 모델)의 경우, IAP 5에서 StoreKit 1 지원이 다시 제공됩니다.
- 패키지에는 작동하는 참조 구현체가 포함되어 있습니다. Unity 패키지 관리자에서 다운로드할 수 있는 최소 코드 IAP 샘플(PaywallManager 스크립트)을 참조하십시오.
Unity IAP 5는 주요 아키텍처 개선, 초기화 구조 변경 및 더욱 깔끔해진 제품 가져오기 워크플로를 도입했습니다. 또한, 이는 Stripe 및 Coda와 같은 직접 결제 제공업체와 웹숍을 포함하여 향후 더욱 발전된 생태계 기능을 위한 기반을 마련해 줍니다. 이러한 기능을 통해 판매 타겟팅을 더욱 효과적으로 하고 구매 수익의 더 큰 부분을 확보할 수 있습니다. Unity IAP 4에서 IAP 5로 마이그레이션하든, Unity 게임 엔진에서 모바일 인앱 구매를 처음 설정하든, 이 단계별 설명은 전체 구현 워크플로를 다룹니다.
Unity IAP 4와 IAP 5 비교
Unity IAP 4에서 IAP 5로 마이그레이션하는 방법
마이그레이션은 다음 네 단계를 따릅니다.
초기화 및 연결. Unity Gaming Services 초기화하고, StoreController를 얻고, 해당 이벤트에 구독하고, Connect()를 호출하여 Google Play 또는 Apple App Store 연결합니다. OnStoreConnected 및 OnStoreDisconnected를 사용하여 구매 UI를 켜고 끌 수 있습니다.
제품을 가져오세요. 에디터의 IAP 제품 카탈로그 또는 코드에서 List을 생성하고(예: new ProductDefinition("gem_chest_01", ProductType.Consumable)) 이를 FetchProducts()에 전달합니다. 해당 상점은 현지화된 가격과 상품 설명을 반환합니다.
구매 대기 중인 내역을 가져옵니다. 중단되거나 연기된 거래를 복구하려면 FetchPurchases() 함수를 호출하십시오. 주문 대기 정보는 OnPurchasePending 이벤트를 통해 전달되지만, 일부 iOS 버전에서는 대기 이벤트가 누락될 수 있으므로 개발자는 orders.PendingOrders도 처리해야 합니다. 확정된 비소모품 및 구독 상품은 이 시점에서 재권한 부여가 가능합니다.
구매, 승인, 확인. PurchaseProduct(product)를 호출합니다. OnPurchasePending에서 항목을 승인하고 영수증을 검증한 다음 ConfirmPurchase(pendingOrder)를 호출합니다. OnPurchaseFailed에서 실패를 처리하세요. 사용자 취소의 경우에는 메시지가 필요하지 않지만, 다른 오류는 플레이어에게 표시해야 합니다.
Unity IAP 5 구매 절차
아래 인포그래픽을 통해 Unity IAP5의 전체 구매 흐름(새로운 기능, 웹샵, 카탈로그 및 결제 제공업체 포함)을 확인하세요.
IAP 5로 업그레이드할 때 흔히 발생하는 문제점
- 중복 승인: 동일한 주문이 OnPurchasePending과 수동 보류 주문 처리 모두를 통해 나타날 수 있습니다. OnPurchasesConfirmed에서 생성된 HashSet에 처리된 거래 내역을 추적하고, 승인 전에 이를 확인합니다.
- 동시 구매 방지: 주문 진행 중에는 중복 구매 요청을 방지하기 위해 구매 버튼을 비활성화합니다.
- 이벤트 누출: IAP 5는 이벤트 기반입니다. 구매 관리자가 삭제되면 모든 StoreController 이벤트 구독을 해제하십시오.
- StoreKit 1의 구매 보류 문제: iOS 15 이전 기기에서 확인되지 않은 구매로 인해 플레이어가 동일한 제품을 재구매하지 못하는 경우가 발생할 수 있습니다. 이러한 구매를 추적하고 처리하는 백엔드 시스템을 사용하는 것이 좋습니다.
서버 측 검증
IAP 5 주문의 거래 ID는 서버 측 검증을 위해 Unity Cloud 코드로 전송될 수 있으며, 아이템은 Unity Economy 통해 플레이어에게 지급됩니다.
