온라인 서비스 상거래 인터페이스(Online Services Commerce Interface) 는 게임플레이 외부에서 게임 콘텐츠를 구매하고 등록할 수 있는 기능을 플레이어에게 제공하는 모든 게임 서비스에 대한 언리얼 엔진의 기반입니다. 상거래 인터페이스는 두 가지 주요 구성 요소는 다음과 같습니다.
- 트랜잭션(Transactions) : 플랫폼 화폐로 스토어 아이템을 구매하는 프로세스입니다.
- 트랜잭션이 완료되면, 인터페이스가 플레이어에게 적절한 권한을 부여합니다.
- 권한(Entitlements) : 플레이어가 받거나 사용할 수 있는 콘텐츠입니다.
- 플레이어는 아이템을 구매했거나 게임 코드를 등록했으므로 권한을 받거나 사용할 수 있습니다.
API 개요
다음 테이블에서는 상거래 인터페이스에 포함된 함수에 대한 개괄적인 설명을 확인할 수 있습니다.
| 함수 | 설명 |
|---|---|
| 오퍼 | |
QueryOffers |
스토어에서 사용할 수 있는 모든 오퍼 목록을 가져와 인터페이스에 캐시합니다. 여기에는 사용할 수 있는 모든 다운로드 가능한 콘텐츠(DLC), 번들, 아이템 등이 포함됩니다. |
QueryOffersById |
제공된 ID 목록에서 사용할 수 있는 오퍼 목록을 가져와 인터페이스에 캐시합니다. |
GetOffers |
인터페이스에서 QueryOffers 에 의해 캐시된 오퍼를 가져옵니다. |
GetOffersById |
인터페이스에 캐시된 제공된 ID 목록에서 오퍼를 가져옵니다. |
| 스토어 | |
ShowStoreUI |
사용자가 게임 클라이언트 외부에서 트랜잭션을 처리하거나 스토어 정보를 확인할 수 있도록 네이티브 스토어 UI를 표시합니다. |
| 체크아웃 | |
Checkout |
GetOffers 또는 GetOffersById 로 가져온 하나 이상의 구매 오퍼로 구매 프로세스를 개시합니다. |
| 이벤트 리스닝 | |
OnPurchaseCompleted |
로컬 사용자가 트랜잭션을 완료할 때마다 발동되는 이벤트입니다. 이 이벤트는 Checkout 에 의해 내부적으로 개시될 수도 있고 네이티브 스토어 UI를 통해 외부적으로 개시될 수도 있습니다. |
| 권한 | |
QueryTransactionEntitlements |
Checkout 호출 성공에 해당하는 게임 내 권한을 확인하여 이러한 혜택을 플레이어에게 제공합니다. |
QueryEntitlements |
스토어에서 특정 사용자에 대해 이미 획득한 권한 목록을 가져와 인터페이스에 캐시합니다. |
GetEntitlements |
인터페이스에서 QueryEntitlements 에 의해 캐시된 권한을 가져옵니다. |
RedeemEntitlement |
권한을 '등록됨(redeemed)'으로 표시합니다. 그러면 나중에 쿼리될 때 해당 권한에 등록됨 플래그가 포함됩니다. 이는 권한을 관리하는 외부 게임 서비스가 없을 때 유용합니다. |
| 검증 | |
RetreiveS2SToken |
플랫폼과 커뮤니케이션하고 주어진 권한의 오너십을 검증하기 위해 게임 서비스 백엔드로 전송할 수 있는 토큰을 반환합니다. |
프로세스 흐름
이제 사용자가 게임을 실행하고 게임 내 스토어에 들어가 구매하고, 그 구매를 사용하기 위해 검증하는 흐름을 규제하는 온라인 서비스 상거래 인터페이스 사용 예시 프로세스 흐름을 살펴보겠습니다.
게임 실행하기
사용자가 게임을 실행하고 원하는 온라인 서비스로 인증에 성공한 다음에는 게임이 QueryEntitlements 를 호출합니다. 게임은 QueryEntitlements 에 의해 캐시된 데이터를 사용자의 저장 데이터에 등록된 권한과 비교하여 사용자가 오프라인 상태였을 때 어떤 권한이 부여되었는지 확인하고 그 권한을 사용자에게 적절하게 적용합니다. 동시에, 게임은 OnPurchaseCompleted 이벤트를 사용하여 향후에 사용자가 구매를 완료하면 메시지를 수신합니다.
게임 내 스토어 인터페이스 들어가기
사용자가 게임 내에서 스토어 메뉴를 엽니다. 게임은 QueryOffers를 호출하는 동안 스토어를 여는 사용자에게 로딩 화면을 표시합니다. 쿼리가 해결되면 게임은 GetOffers를 호출하여 데이터의 로컬 사본을 가져옵니다. 그런 다음, 로컬 사본을 UI 프레임워크에 전달하여 게임 오퍼를 렌더링하고 표시합니다.
트랜잭션 수행하기
오퍼의 아이템을 보고 사용자가 특정 제품을 구매하기로 하면, 이를 PRODUCT_A 라고 하겠습니다. 사용자는 PRODUCT_A 를 게임 내 UI가 처리하는 게임 내 장바구니에 추가하고 해당 트랜잭션을 확인합니다. 사용자를 인증한 뒤 게임은 PRODUCT_A 의 ID로 Checkout 을 호출합니다. 그러면 최종 확인 및 결제 처리를 위한 플랫폼 UI가 시작됩니다.
Checkout 이 성공적으로 해결되고 OnPurchaseCompleted 이벤트가 발동되면, 게임은 주어진 트랜잭션 ID에 대해 QueryTransactionEntitlements 를 호출하여 트랜잭션의 일부로 사용자에게 부여된 게임 내 권한 ID를 획득하고 이 권한 ID를 사용자의 저장 게임에 적용합니다. PRODUCT_A 가 사용자의 게임플레이에 글로벌하게 부여되면 안 되는 경우, 게임은 PRODUCT_A 에 대한 권한이 중복되지 않도록 RedeemEntitlement 를 호출합니다.
트랜잭션 검증하기
PRODUCT_A 를 성공적으로 구매하고 등록한 뒤, 사용자가 새로 구매한 PRODUCT_A 로 온라인 플레이를 시작하기로 결정합니다. 게임 서버 인증 중에 게임은 로컬 사용자가 새 권한을 요청하는 것을 인식하고 그 제품이 적법한지 확인하기 위해 인증 토큰을 요청합니다. 게임은 검증을 위해 제공된 ID에 대해 RetrieveS2SToken 을 호출하고 JSON 웹 토큰(JWT)을 획득합니다. 그러면 해당 백엔드 서비스에서는 이 JWT를 사용하여 플랫폼 서비스에 연결하고 제품의 오너십을 검증합니다. 이 반환이 성공하면, 사용자는 새로 구매한 아이템을 가지고 온라인 플레이를 시작할 수 있습니다.
온라인 서브시스템에서 코드 변환하기
온라인 서비스 상거래 인터페이스는 온라인 서브시스템의 스토어(Store) (읽기 전용 코드) 및 구매(Purchase) (읽기/쓰기 코드) 인터페이스에서 소유한 모든 코드를 담당합니다. 다음 테이블에서 온라인 시스템 상거래 인터페이스의 오브젝트와 이전 온라인 서브시스템의 대응 항목 간의 대응을 확인할 수 있습니다.
추가 정보
헤더 파일
필요에 따라 Commerce.h 헤더 파일에서 직접 추가 정보를 참조하시기 바랍니다. Commerce.h 상거래 인터페이스 헤더 파일은 다음 디렉터리에 있습니다.
UNREAL_ENGINE_ROOT\Engine\Plugins\Online\OnlineServices\Source\OnlineServicesInterface\Public\Online
UE 소스 코드를 획득하는 방법에 대한 단계별 가이드는 언리얼 엔진 소스 코드 내려받기 문서를 참조하세요.
함수 파라미터 및 반환 타입
파라미터 전달 방법 및 / 함수 반환 시 결과 처리 방법을 포함한 함수 파라미터 및 반환 타입에 대한 설명은 온라인 서비스 개요 페이지의 함수 섹션을 참조하세요.
