기술 자료

Development

User Acquisition

Monetization

산업 분야

In-App Purchasing

IAP 클라이언트 API

IAP SDK API

웹숍 관리자 API

웹숍 클라이언트 API

In-App Purchasing

LiveOps
​
​
시작하기
  • 개요
  • IAP 소개
  • IAP v5의 새로운 사항
  • IAP v4에서 v5로 업그레이드
소비자 (D2C)에 대한 직접 결제
  • 소비자 (D2C) 결제 제공업체에게 직접 제공
웹숍
  • 개요
  • 시작하기
  • 빌드 및 퍼블리시
  • 구성
  • 게임에 연결
  • 관리자
  • 웹숍 문제 해결
플랫폼 네이티브 스토어
  • 플랫폼 네이티브 스토어에 대한 IAP 설정
  • 코드리스 IAP
카탈로그 및 스토어 관리
  • 제품 카탈로그 생성
  • 지원되는 스토어
  • 레퍼런스
Purchases
  • 구매 관리 및 이행
IAP 성능 모니터링
  • 개요
  • IAP 수익 성과
  • D2C 성능
개인정보
  • 개인정보 보호 및 동의
  1. Unity 인앱 구매

IAP 버전 4에서 버전 5로 업그레이드

이 가이드를 따라 Unity 인앱 구매 버전 4에서 버전 5로 마이그레이션합니다.
읽는 시간 6분
최근 업데이트: 2달 전
인앱 구매(IAP) 버전 5(v5)는 연결 및 구매 흐름의 각 단계를 더 잘 제어할 수 있도록 아키텍처를 크게 개선했습니다. 마이그레이션을 수행하려면 기존 IAP 구현을 상당히 업데이트해야 하지만, 이 가이드에서는 전환에 도움이 되는 단계별 지침과 코드 샘플을 제공합니다.
참고
SDK v5.4부터 Unity IAP는 개발자 데이터 프레임워크의 일부로 개발자 데이터를 처리합니다. 따라서 Unity 동의 모듈을 사용하여 사용자 동의를 관리할 책임이 있습니다.
참고
IAP 버전 5.3.0부터 IAP AI 기술에 액세스하여 프로젝트를 버전 4에서 버전 5로 마이그레이션할 수 있습니다.
프로젝트 설정 > 서비스 > 인앱 구매 하단에서 다음 옵션 중 하나를 선택합니다.
  • 기술 폴더 열기: 기술 파일이 포함된 폴더를 엽니다. 이 옵션을 사용하여 원하는 AI 툴에 IAP AI 기술을 복사하거나 설치합니다.
  • 클라우드 코드 설치: 기술을 Claude Code에 직접 추가합니다. 이렇게 하면 
    in-app-purchases
    라는 기술이 설치됩니다.
기술을 설치한 후 AI 툴에서 
in-app-purchases
를 실행하고 프로젝트를 버전 4에서 버전 5로 마이그레이션하라는 메시지를 표시합니다.

변경 사항 개요

다음 표에는 IAP v5의 변경 사항과 구현 시 업데이트해야 하는 사항이 요약되어 있습니다. 업그레이드의 이점에 대한 자세한 내용은 Unity 인앱 구매(IAP) v5.x 지원 문서를 참고하십시오.

변경

필수 업데이트

초기화는 스토어 연결, 상품 페치, 구매 페치에 대한 별도의 비동기 호출로 분할됩니다.Replace UnityPurchasing.Initialize()
ConfigurationBuilder
가 제거됩니다. 이제 제품은 
CatalogProvider
또는 
ProductDefinitions
목록을 통해 정의됩니다.		ConfigurationBuilder 교체
스토어 확장 기능은 스토어 확장 서비스로 대체됩니다.ConfigurationBuilder 교체
IDetailedStoreListener
및 
IStoreListener
은 
StoreController
및 개별 스토어 서비스에서 이벤트 핸들러(선택 사항)로 대체됩니다.		IDetailedStoreListener 및 IStoreListener 교체
IStoreController
는 
UnityIAPServices.StoreController()
를 통해 언제든지 가져올 수 있는 
StoreController
로 대체됩니다.		IStoreController 교체
ProcessPurchase
콜백은 새 구매에 대한 
OnPurchasePending
와 복원된 구매에 대한 
OnPurchasesFetched
로 대체됩니다.		구매 흐름 교체
RestoreTransactions
는 스토어 확장에서 
StoreController
및 
PurchaseService
로 이동했습니다.		복원 거래
자격 검사는 이제 
FetchPurchases
또는 
CheckEntitlement
를 사용하여 이벤트에 기반합니다.		자격 검사 대체
Apple 앱 스토어 영수증 확인은 지원이 중단됩니다. Google Play 영수증 확인은 이제 
Order.Info.Receipt
를 사용합니다.		영수증 확인 업데이트
CodelessIAPStoreListener.initializationComplete
를 
CodelessIAPStoreListener.IsInitialized()
으로 대체한다.		코드리스 IAP 업데이트

Replace UnityPurchasing.Initialize()

IAP v5부터 Unity IAP 패키지를 유연하게 초기화할 수 있습니다. 스토어에 연결하고 제품을 가져오고 구매를 독립적으로 비동기식으로 처리할 수 있습니다. 이 접근 방식은 성공적인 초기화를 차단할 수 있는 문제를 식별하고 해결하는 데 도움이 될 수 있습니다.
참고
버전 4 이하에서는 Unity IAP 패키지가 스토어에 연결되고 제품을 가져오고 패키지 초기화 시 구매를 동기식으로 가져옵니다. 패키지는 이러한 모든 단계를 완료한 후에만 성공적인 초기화를 리포트합니다.
다음 단계에 따라 
UnityPurchasing.Initialize()
의 동작을 대체합니다.
  1. 전화 및 대기 
    StoreController.Connect()
    :
    • 이 호출이 완료되면 IAP가 현재 앱 스토어 연결됩니다.
  2. 호출:
    • 제품을 
      ConfigurationBuilder
      에 추가하는 것과 마찬가지로 제품을 
      CatalogProvider
      인스턴스에 추가할 수 있습니다. 
      ProductDefinitions
      목록을 
      ProductService.FetchProducts()
      또는 
      StoreController.FetchProducts()
      에 전달할 수도 있습니다. 자세한 내용은 새 초기화 프로세스의 코드 샘플을 참고하십시오.
    • 요청이 성공적으로 완료되면 
      OnProductsFetched
      이벤트 핸들러가 호출됩니다. 지정된 제품을 가져올 수 없으면 
      OnProductsFetchFailed
      가 호출됩니다.
  3. 제품이 성공적으로 페치되면 
    FetchPurchases()
    를 호출합니다.
    • 요청이 성공적으로 완료되면 
      OnPurchasesFetched
      이벤트 핸들러가 호출됩니다. 
      Orders
      객체는 앱 스토어에서 반환한 모든 디퍼드, 보류 중, 완료된 주문의 필터링 가능한 컬렉션을 포함합니다. 실패 시 
      OnPurchasesFetchFailed
      가 호출됩니다.
참고
기본적으로 호출 
FetchPurchases
는 세션에서 아직 처리되지 않은 보류 중인 구매에 대해 
OnPurchasePending
를 호출합니다. 
StoreController.ProcessPendingOrdersOnPurchasesFetched(false)
를 사용하여 이 동작을 비활성화할 수 있습니다.

StoreController를 사용한 새 초기화 프로세스의 코드 샘플

다음 예시는 IAP v5를 초기화하는 방법을 보여 줍니다.
StoreController m_StoreController;    async void InitializeIAP()  {      m_StoreController = UnityIAPServices.StoreController();        m_StoreController.OnPurchasePending += OnPurchasePending;        await m_StoreController.Connect();        m_StoreController.OnProductsFetched += OnProductsFetched;    m_StoreController.OnPurchasesFetched += OnPurchasesFetched;        var initialProductsToFetch = new List<ProductDefinition>      {          new(goldProductId, ProductType.Consumable),          new(diamondProductId, ProductType.Consumable)      };        m_StoreController.FetchProducts(initialProductsToFetch);  }void OnProductsFetched(List<Product> products)  {      // Handle fetched products      m_StoreController.FetchPurchases();  }  void OnPurchasesFetched(Orders orders) {     // Process purchases, for example, check for entitlements from completed orders  }

IDetailedStoreListener와 IStoreListener 교체

IAP v5에서는 구매 또는 초기화 처리를 위한 
IDetailedStoreListener
또는 
IStoreListener
구현이 더 이상 필요하지 않습니다. 이전에 
IDetailedStoreListener
에서 처리한 기능을 
StoreController
또는 개별 
ProductService
, 
PurchaseService
및 
StoreService
서비스에 이벤트 핸들러를 연결하여 교체합니다.
StoreController
에 이벤트 핸들러를 추가하는 예제는 새 초기화 프로세스의 코드 샘플을 참고하십시오.
참고
언제든지 이벤트 핸들러를 추가하거나 제거할 수 있지만 특정 메서드를 호출하기 전에 특정 이벤트 핸들러를 사용할 것을 권장합니다. Unity IAP는 권장 이벤트 핸들러가 연결되기 전에 함수를 호출할 때 경고를 표시합니다.
마이그레이션하려면 각 
IDetailedStoreListener
함수를 다음으로 대체합니다.

함수

IAP v5 교체

OnPurchaseFailed(Product, PurchaseFailureDescription)
StoreController.OnPurchaseFailed(FailedOrder)
또는 
PurchaseService.OnPurchaseFailed(FailedOrder)
에 이벤트 핸들러 추가
OnInitialized(IStoreController controller, IExtensionProvider extensions)
StoreController.Connect()
또는 
StoreService.Connect()
가 완료된 후에도 실행을 계속합니다.
OnInitializeFailed(InitializationFailureReason error)
StoreService.OnStoreDisconnected(StoreConnectionFailureDescription)
, 
ProductService.OnProductsFetchFailed(ProductFetchFailed)
, 
PurchaseService.OnPurchasesFetchFailed(PurchasesFetchFailureDescription)
에 이벤트 핸들러를 추가합니다. 
StoreController
를 통해 이러한 이벤트 핸들러를 추가할 수도 있습니다.
OnInitializeFailed(InitializationFailureReason error, string message = null)
StoreController.OnStoreDisconnected(StoreConnectionFailureDescription)
또는 
StoreService.OnStoreDisconnected(StoreConnectionFailureDescription)
에 이벤트 핸들러 추가
PurchaseProcessingResult ProcessPurchase(PurchaseEventArgs args)
StoreController.OnPurchasePending(PendingOrder)
또는 
PurchaseService.OnPurchasePending(PendingOrder)
에 이벤트 핸들러 추가

ConfigurationBuilder 교체

다음 
ConfigurationBuilder
함수를 다음 동작으로 교체합니다.

함수

IAP v5 교체

ConfigurationBuilder.AddProduct()
ConfigurationBuilder.AddProduct()
를 호출하는 대신 
CatalogProvider.AddProduct()
또는 
CatalogProvider.AddProducts()
를 통해 
CatalogProvider
의 인스턴스에 제품을 추가할 수 있습니다. 제품을 가져오려면 
CatalogProvider.FetchProducts
를 호출하고 
UnityIAPServices.DefaultProduct().FetchProductsWithNoRetries
와 같은 콜백을 전달하십시오. 제품 및 
CatalogProvider
에 대한 자세한 내용은 에디터에서 카탈로그 만들기를 참조하십시오. 
ProductDefinitions
를 생성하고 
StoreController
또는 
ProductService
에서 
FetchProducts()
호출에 직접 전달할 수도 있습니다.
4 및 5확장 스토어 서비스(예: 
AppleStoreExtendedService
)에서 
IAppleConfiguration
및 
IGoogleConfiguration
의 기능을 찾을 수 있습니다.
참고
지원되지 않는 플랫폼(예: 에디터 또는 Android에서 
AppleStoreExtendedService
가져오기)에서 스토어 확장 서비스를 가져오는 경우 서비스가 null이 됩니다. 이벤트 핸들러를 추가하거나 설정을 변경하기 전에 서비스가 null이 아닌지 항상 확인하십시오.

IStoreController 교체

IStoreController
를 
StoreController
로 교체합니다. 
StoreController
는 
IStoreListener
와 유사한 IAP 기능을 노출하지만, 언제든지 
UnityIAPServices.StoreController()
를 호출하여 
StoreController
를 가져올 수 있습니다.
IStoreController
의 이러한 방법을 
StoreController
의 다음 방법으로 대체합니다.

IStoreController

StoreController

참고 사항

products
GetProducts
GetProducts
는 제품 목록을 반환합니다.
InitiatePurchase
Purchase
또는 
PurchaseProduct
Purchase
함수에는 더 이상 
payload
인수가 없습니다. Google Billing v3에서 개발자 페이로드에 대한 지원이 중단되었습니다.
FetchAdditionalProducts
FetchProducts
FetchProducts
는 초기 제품을 가져오는 데에도 사용됩니다.
ConfirmPendingPurchase
ConfirmPurchase
ConfirmPurchase
에는 
PendingOrder
가 필요해

구매 플로 교체

구매를 시작하려면 
Purchase()
또는 
PurchaseProduct()
on 
StoreController
또는 
PurchaseService
에 전화하십시오. 보류 중인 구매를 확인하려면 확인하려는 
PendingOrder
가 있는 
StoreController.ConfirmPurchase(PendingOrder)
또는 
PurchaseService.ConfirmPurchase(PendingOrder)
에 문의하십시오. 구매 흐름에 대한 자세한 내용은 구매를 참고하십시오.
IAP v4 이하에서 
ProcessPurchase
메서드는 모든 구매 이벤트를 자동으로 처리했습니다. IAP v5에서 구매 핸들링은 다음 콜백을 사용합니다.
  • OnPurchasePending
    : 새 구매가 호출되었습니다.
  • OnPurchasesFetched
    : 복원된 구매에 대해 호출됩니다.
이러한 두 새로운 콜백 내에서 기존의 
ProcessPurchase
로직을 사용합니다.

거래 복원

RestoreTransactions
는 스토어 확장에서 
StoreController
및 
PurchaseService
로 이동했습니다.
확인된 구매는 
FetchPurchases()
또는 
CheckEntitlement()
호출을 통해 자동으로 복원됩니다.

자격 검사 교체

제품에 대한 사용자의 권한을 확인하기 위해 IAP는 이벤트에 의존합니다. 
FetchPurchases
를 호출하고 
OnPurchasesFetched
이벤트를 처리하여 가져온 모든 제품의 자격을 확인할 수 있습니다. 단일 제품의 자격을 확인하려면 
CheckEntitlement
에 전화하여 
OnCheckEntitlement
이벤트를 처리하십시오.

추가 상품 페치

추가 제품 목록과 함께 
StoreController
또는 
ProductService
에서 
FetchProducts
을 호출하여 
OnPurchasesFetched
이벤트 핸들러를 트리거합니다. 또는 
CatalogProvider
인스턴스에서 
FetchProducts
를 호출할 수도 있습니다. 
ProductService
를 통해 상품을 가져오는 예제는 새 초기화 프로세스의 코드 샘플을 참고하십시오. 
CatalogProvider
에서 
FetchProducts
호출 예제는 에디터에서 카탈로그 만들기를 참조하십시오.

영수증 확인

Apple 앱 스토어 영수증 확인은 지원이 중단되었습니다. 영수증 확인은 Google Play 스토어에서만 지원됩니다. 영수증을 가져오려면 
Product.Receipt
대신 
Order
에서 
Order.Info.Receipt
를 사용하십시오.
참고
가능한 한 빨리 StoreKit 1 영수증에서 StoreKit 2 jwsRepresentation으로 전환하여 신뢰성, 보안, 성능을 향상시키고 최종적으로 사용자에게 더 나은 경험을 제공합니다.
참고
서버 측 확인을 위해 OrderInfo.Apple.jwsRepresentation을 사용합니다.

코드리스 IAP 세부 사항

다음의 
CodelessIAPStoreListener
함수를 다음과 같이 대체합니다.

CodelessIAPStoreListener
함수

IAP v5 교체

CodelessIAPStoreListener.initializationComplete
CodelessIAPStoreListener.IsInitialized()
Copyright © 2026 Unity Technologies
법률 정보개인정보 처리방침쿠키Documentation Terms of Use개인 정보 판매 또는 공유 금지개인정보 보호 선택(쿠키 설정)

'Unity', Unity 로고 및 기타 Unity 상표는 미국 및 기타 지역 내 Unity Technologies 또는 그 계열사의 상표 또는 등록상표입니다(자세한 내용은 여기에서 확인하세요). 기타 명칭 또는 브랜드는 해당 소유자의 상표입니다.

일부 페이지는 편의를 위해 기계 번역되었으며 부정확한 내용이 있을 수 있습니다. 정보가 상충되는 경우, 영어 버전을 우선으로 참조하세요.

  • 보고 있는 페이지

    • 변경 사항 개요

    • Replace UnityPurchasing.Initialize()

      • StoreController를 사용한 새 초기화 프로세스의 코드 샘플

    • IDetailedStoreListener와 IStoreListener 교체

    • ConfigurationBuilder 교체

    • IStoreController 교체

    • 구매 플로 교체

    • 거래 복원

    • 자격 검사 교체

    • 추가 상품 페치

    • 영수증 확인

    • 코드리스 IAP 세부 사항

이 페이지의 문제 보고
​
​