Ecom Interface Overview

구매 및 오너십 검증을 처리하는 인터페이스

Epic Games Store
16 분 소요

Ecom 인터페이스(Ecom Interface)에픽 온라인 서비스(EOS) 를 사용하는 개발자에게 에픽게임즈 스토어(EGS) 를 통해 게임 내 구매 기능을 지원합니다. 이 인터페이스를 통해 전체 게임, 다운로드 콘텐츠(DLC)에서 가상 상품과 게임 내 통화에 이르기까지 다양한 제품을 관리할 수 있습니다. 다시 말해 특가를 제안하거나 구매 트랜잭션을 완료하거나 오너십을 검증하거나 구매 아이템을 등록할 수 있습니다.

Ecom 인터페이스와 웹 API를 함께 사용하는 방법은 Ecom Web APIs 문서를 참고하세요.

Ecom 인터페이스에 액세스하려면 플랫폼 인터페이스 함수인 EOS_Platform_GetEcomInterface 를 통해 EOS_HEcom 핸들을 얻으세요. 모든 Ecom 인터페이스 함수에는 첫 번째 파라미터로 이 핸들이 필요합니다. 요청이 완료되었을 때 적절한 콜백을 트리거하려면 EOS_HPlatform 핸들의 틱이 실행 중인지 확인해야 합니다.

Ecom 인터페이스를 사용하려면 제품의 에픽 계정 서비스(EAS) 가 활성 상태여야 하며, 기본 프로필(Basic Profile) 데이터에 액세스하려면 플레이어/사용자 동의가 필요합니다. 개발자 포털에서 EAS를 활성화하거나 에픽 문서에서 자세한 내용을 확인할 수 있습니다. EAS와 플레이어 동의 없이도 EOS SDK와 Ecom 인터페이스를 초기화할 수 있지만, 백엔드 서비스에 보낸 모든 Ecom 인터페이스 함수 호출이 실패하게 됩니다.

게임 내 스토어 운영하기

EOS 산하의 게임 내 스토어는 두 가지 기능을 통해 운영됩니다. 먼저, 스토어에서 플레이어가 구매할 수 있는 카탈로그 오퍼(Catalog Offers) (단순히 '오퍼'라고도 함)를 제시합니다. 그러면 플레이어가 원하는 것을 구매할 수 있습니다. EOS SDK는 스토어의 카탈로그에서 오퍼 목록을 가져와 게임 개발자가 원하는 방식으로 표시하는 기능을 제공합니다. 오퍼 데이터에는 플레이어가 얻게 될 하나 또는 다수의 아이템뿐만 아니라 플레이어에게 오퍼에 대한 정보를 제공할 때 사용할 주요 이미지와 릴리즈 디테일도 포함됩니다.

플레이어가 구매를 선택하면 체크아웃 프로세스가 데이터를 EGS 오버레이 에 푸시하여 구매 프로세스가 완료됩니다. 그러면 EOS가 구매 완료 시 게임이 주문을 처리할 수 있도록 게임에 트랜잭션 핸들을 제공하며 트랜잭션 결과를 알립니다.

EOS_PF_DISABLE_OVERLAY 플래그가 설정되어 있으면 Ecom 인터페이스의 구매 관련 기능은 비활성화됩니다.

카탈로그 오퍼 데이터

카탈로그 오퍼(EOS_Ecom_CatalogOffer 타입)에는 스토어를 살펴보는 플레이어에 맞춰 현지화된 가격 책정 정보와 설명 텍스트가 포함됩니다. 가격 현지화는 할인 적용과 현지 통화로의 변환을 포함합니다. 현지화된 가격은 'USD'(미국 달러)와 같은 통화 코드를 포함하며 해당 통화를 최저 단위로 표시합니다. 가령, 미화 2.99달러의 오퍼에 대응하는 값은 299입니다.

스토어의 카탈로그 표시

EOS_Ecom_QueryOffers 함수를 호출하여 개발자 포털에 정의된 카탈로그 오퍼 목록을 가져올 수 있습니다. 이 함수는 EOS_Ecom_QueryOffersOptions 데이터 구조체를 사용하며 완료 시 EOS_Ecom_QueryOffersCallbackInfo 타입의 델리게이트를 호출합니다. EOS_Ecom_QueryOffersOptions 구조체를 다음과 같이 초기화합니다.

프로퍼티
ApiVersionEOS_ECOM_QUERYOFFERS_API_LATEST
LocalUserId쿼리를 요청하는 로컬 플레이어의 EOS_EpicAccountId
OverrideCatalogNamespace제품 네임스페이스 옵션(초기화할 때 지정된 게 아닌 경우)

델리게이트가 받는 EOS_Ecom_QueryOffersCallbackInfo 안의 ResultCode 가 성공일 경우, 요청한 오퍼 데이터를 임시 캐시에서 사용할 수 있습니다. EOS_Ecom_GetOfferCount 를 사용하여 캐시에 저장된 오퍼 개수를 확인하고 EOS_Ecom_CopyOfferByIndex 로 캐시에서 개별 오퍼(EOS_Ecom_CatalogOffer 타입)의 사본을 가져올 수 있습니다. 오퍼 내의 각 아이템에는 해당 아이템과 관련된 이미지와 릴리즈 디테일에 대한 데이터가 포함되며, 이러한 데이터는 따로 가져올 수 있습니다. 오퍼의 사본이 더 이상 필요 없으면 EOS_Ecom_CatalogOffer_Release 를 사용하여 릴리즈하세요.

개별 아이템 데이터 표시하기

캐시에서 오퍼를 가져온 후 EOS_Ecom_GetOfferItemCount 를 호출하여 오퍼에 포함된 아이템의 수를 파악한 다음 EOS_Ecom_CopyOfferItemByIndex 를 사용하여 개별 EOS_Ecom_CatalogItem 의 사본을 가져올 수 있습니다. 이 구조체에는 구매 시 제공할 권한의 ID뿐 아니라 현지화된 추가 텍스트도 포함됩니다. 데이터 사본에 할당된 메모리를 릴리즈하려면 EOS_Ecom_CatalogItem_Release 를 호출합니다.

아이템과 관련된 이미지는 캐시에서도 사용할 수 있습니다. EOS_Ecom_GetItemImageInfoCount 를 호출하여 지정 아이템과 관련된 이미지 수를 확인한 다음 EOS_Ecom_CopyItemImageInfoByIndex 를 사용하여 이미지의 URL, 치수, 용도에 대한 EOS_Ecom_KeyImageInfo 를 얻을 수 있습니다. 이 데이터의 사본이 더 이상 필요 없으면 EOS_Ecom_KeyImageInfo_Release 로 이미 사용한 메모리를 확보하세요.

캐시에서 아이템의 릴리즈 디테일을 가져오려면 먼저 EOS_Ecom_GetItemReleaseCount 를 사용하여 현재 있는 데이터 항목의 수를 확인합니다. 그런 다음, EOS_Ecom_CopyItemReleaseByIndex 를 사용하여 개별 데이터 조각(EOS_Ecom_CatalogRelease 타입)을 가져옵니다. 이 데이터가 더 이상 필요 없으면 EOS_Ecom_CatalogRelease_Release 를 호출하여 데이터를 릴리즈하세요.

스토어에서 구매하기

플레이어가 스토어에서 제품을 구매할 경우 플레이어는 카탈로그 오퍼를 수락하게 됩니다. 구매가 완료되면 플레이어는 오퍼 목록의 해당 아이템을 소유하게 되며, 각 제품은 구매자의 플레이어 계정에 권한(Entitlement) 을 추가합니다.

스토어에서 구매하는 과정에는 3가지 작업이 수반됩니다. 구매하기, 오너십 검증하기, 그리고 권한 등록하기(옵션) 작업이 그것입니다.

플레이어가 구매를 결정하면 EOS_Ecom_CheckoutOptions 구조체를 사용하여 EOS_Ecom_Checkout 을 호출합니다. 구조체를 다음과 같이 초기화합니다.

프로퍼티
ApiVersionEOS_ECOM_CHECKOUT_API_LATEST
LocalUserId구매하는 로컬 플레이어의 EOS_EpicAccountId
OverrideCatalogNamespace입력하지 않은 경우 현재 SandboxId 가 카탈로그 네임스페이스로 입력됩니다.
EntryCountEntries 파라미터에서 이 구조에 제공되는 EOS_EcomCheckoutEntry 요소의 수입니다.
EntriesEOS_Ecom_CheckoutEntry 요소의 배열로, 여기에는 플레이어가 구매하려는 각 오퍼의 EOS_Ecom_CatalogOfferId 데이터 및 이 구조체와 동일한 ApiVersion 이 포함되어 있습니다.

이 호출을 수행하면 EOS가 이 정보를 사용하여 구매 토큰을 생성합니다. 그런 다음, EOS는 이 구매 토큰을 사용하여 자체 오버레이를 엽니다. 그러면 플레이어가 구매를 검토하고 결제 옵션을 선택하고 트랜잭션을 확인하거나 취소할 수 있습니다. 성공, 실패 또는 플레이어의 취소 결정으로 인해 오버레이가 닫히면 트랜잭션 디테일이 포함된 EOS_Ecom_CheckoutCallbackInfo 파라미터와 함께 콜백(EOS_Ecom_OnCheckoutCallback 타입)이 실행됩니다. 콜백 정보 내에서 트랜잭션이 성공한 경우 TransactionId 는 null이 아니며 트랜잭션이 실패 또는 취소된 경우에는 null이 됩니다.

콜백을 통해 처음 호출이 반환되기 전에 EOS_Ecom_Checkout 에 추가 호출을 수행하면 EOS_AlreadyPending 오류가 발생합니다.

구매 완료된 데이터에 액세스하기

플레이어의 구매가 성공한 후 유효한 트랜잭션 ID를 가지고 있다면 이를 EOS_Ecom_CopyTransactionById 함수에 전달하여 EOS_Ecom_HTransaction 을 받을 수 있습니다. EOS_Ecom_Transaction_GetEntitlementsCount 는 트랜잭션과 연결된 권한 수를 반환하고 EOS_Ecom_Transaction_CopyEntitlementByIndex 는 개별 권한을 가져옵니다. 이 데이터가 더 이상 필요 없으면 EOS_Ecom_Entitlement_Release 를 호출하여 이 데이터를 릴리즈하세요.

트랜잭션 ID와 연결된 권한은 EOS_Ecom_QueryEntitlement 함수를 통해 얻은 것과 동일한 데이터를 포함하지만 다른 캐시 정책이 적용됩니다. 이러한 차이로 인해 구매 후에 트랜잭션 ID를 사용하여 획득한 권한은 플레이어가 EOS_Ecom_Transaction_Release 를 명시적으로 호출하기 전까지는 트랜잭션 전용 캐시에 남게 됩니다.

오너십 검증하기

게임 클라이언트 내에서 오너십을 검증하는 것은 권장하지 않으며, 최종 플레이어가 소프트웨어 치트를 사용하여 오너십 검증을 우회할 수 있습니다. 가급적 신뢰할 수 있는 게임 서버나 API에서 오너십을 검증하세요.

불법 복제 방지에 도움이 될 최신 권장 사항

불법 복제를 방지하기 위해서는 개발자가 게임과 모든 DLC에 오너십 검증 확인을 구현하는 것이 좋습니다. 신뢰할 수 있는 서버나 API를 통한 온라인 오너십 검증을 적극 권장합니다. 온라인 오너십 검증은 불법 복제를 효과적으로 방지하는 유일한 방법으로 널리 알려져 있습니다. 클라이언트 측 검증은 수정되지 않은 게임 파일을 재배포하는 수준의 단순한 공격만 줄일 수 있습니다.

멀티플레이어 게임 및 온라인 게임:

  • Ecom 인터페이스 또는 웹 API를 사용하여 신뢰할 수 있는 게임 서버나 백엔드 API에 오너십 확인 구현

    • 일반적으로 인증 단계 중에 또는 레벨/매치에 입장하는 시점에 확인하도록 구현됩니다.
  • 플레이어가 오너십 확인에 패스하지 못하면 액세스가 거부되도록 조치하세요. 적절히 구현하면 플레이어가 API 응답을 변경하거나 게임 클라이언트 자체를 수정하는 방법으로는 이 확인을 우회할 수 없습니다.

  • 활동량이 비정상적으로 많은 계정을 모니터링하고 여러 명의 최종 플레이어가 하나의 계정을 공유한다면 계정을 차단하세요.

    • 계정당 동시 세션 수는 1개로 제한하는 것이 좋습니다.

모든 게임:

클라이언트 측 제어로는 불법 복제를 완벽하게 막을 수 없지만, 다음 몇 가지 방법으로 단순한 수법의 공격과 공유를 줄일 수 있습니다.

  • 오너십 검증 API를 호출하기 전에 게임 실행 파일과 모든 실행 코드(.exe/.dll/.so/기타)의 SHA1 체크섬과 디지털 서명을 검증하세요. 또한 EOS SDK와 서드 파티 라이브러리도 검증해야 합니다. 변조가 감지되면 액세스를 거부하도록 조치하세요.

  • 온라인 활성화를 요구하고, 플레이어가 온라인 검증을 패스한 경우에만 오프라인 액세스를 허용하는 암호 검증 토큰을 반환하세요.

    • 토큰을 특정 하드웨어/플레이어 프로퍼티에 연결하고 사전 정의한 기간이 지나면 만료되게 할 수 있습니다.

    • 게임 바이너리에 포함된 공개 키를 수정할 수 없도록 보호해야 효과가 있습니다.

    • 특정 계정이 너무 자주 활성화되거나 매우 많은 디바이스에서 활성화되면 활성화를 거부하도록 조치하세요.

  • 상용화된 난독화 및 변조 방지 솔루션을 활용하여 변조 확인을 역설계하거나 수정하기 어렵게 만드세요.

  • DLC를 메인 게임 파일에 포함하지 마세요. DLC 콘텐츠는 에픽게임즈 스토어를 통해 배포하거나 서버 측 오너십 확인으로 액세스가 제어되는 추가 다운로드로 제공하세요.

Ecom 인터페이스는 '온라인' 메서드와 '오프라인' 메서드로 알려진 두 가지 오너십 검증 기능을 제공합니다. 온라인 메서드는 에픽 권한 서비스(Epic Entitlement Service)와 직접 통합하고, 오프라인 메서드는 플레이어가 검증할 수 있는 서명된 토큰을 제공하거나 타사 서비스에 전달합니다. 온라인 메서드는 신뢰할 수 있는 게임 서버를 확인하거나 클라이언트 서버에서 보안성이 낮은 간단한 유효성 검사를 수행할 때 유용합니다. 오프라인 메서드는 게임 클라이언트, 플레이어, 권한에 대한 정보가 포함된 토큰을 제공할 뿐만 아니라 게임 클라이언트나 외부 서비스에서 검증할 수 있는 서명도 제공합니다. 오너십을 검증하는 타사 서비스와 통합하려는 경우에는 오프라인 확인을 사용하는 것이 좋습니다. 오프라인 확인은 외부 서비스에서 플레이어의 데이터에 액세스하지 못하게 하기 때문입니다.

RESTful 엔드포인트를 통해 타이틀과 서비스에 대한 오너십 정보에 접근하는 것을 선호한다면 Ecom 웹 API를 참조하세요.

온라인 오너십 검증하기

플레이어 구매를 검증하는 바람직한 방법은 자체 백엔드 서비스를 사용하는 것입니다. 그러면 플레이어의 악성 행동에 취약해지지 않습니다. 자세한 내용은 Ecom Web APIs 문서를 참고하세요.

플레이어가 특정 카탈로그 아이템을 소유하고 있는지를 확인하려면 EOS_Ecom_QueryOwnership 을 호출하고 EOS_Ecom_QueryOwnershipOptions 구조체를 전달해 보세요. 그러면 서버에서 오너십 정보를 가져와 플레이어가 제공한 EOS_Ecom_OnQueryOwnershipCallback 콜백 함수에 전달합니다. 콜백 함수는 플레이어가 지정한 void 포인터도 가져오는데, 여기에는 요청 컨텍스트를 이해하기 위한 제품에 필요한 정보가 포함될 수 있습니다. 시작하려면 EOS_Ecom_QueryOwnershipOptions 구조체에 다음 정보를 채웁니다.

프로퍼티
ApiVersionEOS_ECOM_QUERYOWNERSHIP_API_LATEST
LocalUserId쿼리할 오너십을 가진 로컬 플레이어의 EOS_EpicAccountId . 카탈로그 아이템(또는 아이템) 설명 텍스트와 가격 책정 정보를 현지화하는 데 필요
CatalogItemIds오너십을 확인할 카탈로그 아이템 ID의 목록
CatalogItemIdCountCatalogItemIds 의 요소 수
CatalogNamespace제품 네임스페이스 옵션(초기화할 때 지정된 게 아닌 경우)

완료되면 EOS가 EOS_Ecom_OnQueryOwnershipCallback 구조체에 저장된 플레이어 요청 데이터(및 void 포인터)를 사용하여 콜백 함수를 호출합니다. 이 구조체에는 EOS_Ecom_ItemOwnership 멤버의 배열이 포함되며, 각 멤버는 플레이어가 쿼리한 아이템 중 하나를 설명하고 플레이어에게 해당 아이템이 있는지를 나타냅니다. 서버에서 인식하지 못하는 아이템은 미소유 아이템으로 돌아옵니다.

오프라인 오너십 검증하기

플레이어 구매를 검증하는 바람직한 방법은 자체 백엔드 서비스를 사용하는 것입니다. 그러면 플레이어의 악성 행동에 취약해지지 않습니다. 자세한 내용은 Ecom Web APIs 문서를 참고하세요.

오너십을 확인하고 몇 분 동안 결과를 로컬에서 캐시하려면 EOS_Ecom_QueryOwnershipToken 을 사용합니다. 이 함수는 다음과 같이 초기화된 EOS_Ecom_QueryOwnershipTokenOptions 구조체를 사용합니다.

프로퍼티
ApiVersionEOS_ECOM_QUERYOWNERSHIPTOKEN_API_LATEST
LocalUserId소유 권한을 쿼리할 플레이어의 FUniqueNetId
CatalogItemIds권한을 확인할 최대 32개(EOS_ECOM_QUERYOWNERSHIPTOKEN_MAX_CATALOGITEM_IDS )의 카탈로그 아이템 배열(EOS_Ecom_CatalogItemId 타입)
CatalogItemIdCountCatalogItemIds 의 카탈로그 아이템 수
CatalogNamespace제품 네임스페이스 옵션(초기화할 때 지정된 게 아닌 경우)

작업이 완료되면 콜백 함수(EOS_Ecom_OnQueryOwnershipTokenCallback 타입)가 5분 후에 만료되는 JSON 웹 토큰(JWT)이 포함된 EOS_Ecom_QueryOwnershipTokenCallbackInfo 구조체를 받게 됩니다. 공개 키를 사용하여 JWT를 검증하고 압축을 풀어 키 ID를 추출할 수 있습니다. 이를 타사 서비스에 보내 EGS에서 가져온 권한 정보를 검증할 수도 있습니다. 추가적인 웹 호출로 가져왔거나 조직과 공유한 공개 키는 JWT에서 서명을 검증하는 데 사용할 수 있는 JSON 웹 키(JWK)의 형태를 띱니다. HTTP 요청을 하려면 https://ecommerceintegration-public-service-ecomprod02.ol.epicgames.com/ecommerceintegration/api/public/publickeys/{kid} 에 GET를 보냅니다. 요청 샘플은 다음과 같습니다.

GET
/ecommerceintegration/api/public/publickeys/pbvnNIE97vErdePGIRoG41h8hnP_2wIxG8xbwZCIj3g HTTP/1.1
Host: ecommerceintegration-public-service-ecomprod02.ol.epicgames.com
{
"kty": "RSA",
"e": "AQAB",
"kid": "pbvnNIE97vErdePGIRoG41h8hnP_2wIxG8xbwZCIj3g",
"n": "gcStqtD8XD9c9ifNuxXT9Xd_EEZLLCw34yxINRQPt0MxEWkoOFsuisRWGktSFtGrnUuQnp8GQY0k4Pyl_yDItWAcRtO7JUjrhQnxx3xXp_0P8xJMH1ny-RcxHF3bEJWhDzNW5PBpBjQTQZis-83499z-4OlNA7oUnDKEJkqNfzh4mMDFluPxvW_Hwpaw71nhzJI7-N-BdsPsLdqUANajLsFKq9fr06Lek_tm-6-RUxNPE3yS0x0UIsGyapA4Apcczz0xTzRDfwOkq_TyKGZiZc7vtgjkWnqdsCyXZC7dzKJvg0ggO3mKXhqZNNC_2pz24o1X_xCbG8rXtuvX8-ux-Q"
}

오너십 검증 토큰 디테일

오너십 검증 토큰(Ownership Verification Token)은 RS512(SHA-512를 사용한 RSA PKCS#1 서명, RSA 키 크기 2048)를 사용하여 서명한 JWT로, 생성 후 5분이 지나면 만료됩니다. 토큰에는 다음과 같은 클레임이 포함됩니다.

클레임설명
jti이 토큰의 고유 식별자
sub토큰을 요청하는 데 사용된 계정의 계정 ID
clid토큰을 요청하는 데 사용된 클라이언트의 클라이언트 ID
ent이 토큰에 대해 검증된 권한의 배열. 이 값이 비어 있으면 지정 sandboxId에서 요청된 권한이 하나도 계정에 부여되지 않음
iat토큰이 발급된 시간을 나타내는 Unix 타임스탬프
exp토큰이 만료되는 시간을 나타내는 Unix 타임스탬프

구매 처리하기

구매 후 플레이어의 계정 은 권한을 얻지만 플레이어는 아직 게임 속에서 구매 결과를 볼 수 없습니다. 어떤 때는 구매 처리 과정이 매우 간단해서 플레이어가 특정 권한을 소유하고 있는지 확인하고 그 결과에 게임 로직에만 적용하면 됩니다. 이럴 땐 EOS SDK를 통해 오너십을 검증하는 것만으로 충분합니다. 하지만 소모성 아이템이나 게임 통화를 구매하는 등의 경우에는 권한을 등록하여 인게임에서 또는 타사 백엔드 서비스를 통해 주문을 등록해야 할 수도 있습니다.

권한 나열하기

플레이어 계정의 권한을 가져오려면 EOS_Ecom_QueryEntitlementsOptions 구조체로 EOS_Ecom_QueryEntitlements 함수를 호출합니다.

참고로, EOS_Ecom_QueryEntitlements API는 지속성 콘텐츠를 검증하는 데 사용하지 않아야 말아야 합니다. 시즌 패스에 포함된 개별 DLC 같이 연관 카탈로그 아이템 간의 관계를 고려하지 않기 때문입니다. 따라서 EOS_Ecom_QueryEntitlements 는 주로 소모성 오퍼에 사용되며, 지속성 콘텐츠는 위 오너십 검증 섹션에서 명시된 대로 관리합니다.

EOS_Ecom_QueryEntitlementsOptions 는 다음과 같이 초기화됩니다.

프로퍼티
ApiVersionEOS_ECOM_QUERYENTITLEMENTS_API_LATEST
LocalUserId권한을 가져올 대상인 로컬 플레이어의 EOS_EpicAccountId
EntitlementNames확인할 권한 이름(Entitlement Name)의 배열.
EntitlementNameCountEntitlementNames 프로퍼티에 포함된 권한 이름 수입니다. 수락할 최대 EOS_ECOM_QUERYENTITLEMENTS_MAX_ENTITLEMENT_IDS 수입니다. 0을 입력하면 해당 플레이어 계정과 관련된 모든 권한을 요청합니다.
bIncludeRedeemedtrue인 경우 등록한 권한이 결과에 포함됩니다.

작업이 완료되면 EOS가 결과 정보를 캐시하고 EOS_Ecom_QueryEntitlementsCallbackInfo 파라미터를 사용하여 콜백 함수(EOS_Ecom_OnQueryEntitlementsCallback 타입)를 실행합니다. 이 파라미터의 ResultCodeEOS_Success 면 요청한 데이터가 캐시에 포함됩니다. EOS_Ecom_GetEntitlementsCount 를 호출하여 캐시의 권한 수를 파악하고 EOS_Ecom_CopyEntitlementByIndex 를 호출하여 권한을 제공한 카탈로그 아이템 ID, 해당 권한의 고유 ID 및 기타 관련 데이터를 비롯한 개별 요소(EOS_Ecom_Entitlement 타입)의 사본을 가져올 수 있습니다.

권한 등록하기

소모성 권한을 처리하거나 타사 서비스를 통한 처리를 관리한 후에는 EOS_Ecom_RedeemEntitlementsOptions 구조체를 사용하여 EOS_Ecom_RedeemEntitlements 함수를 호출합니다. 구조체를 다음과 같이 초기화합니다.

프로퍼티
ApiVersionEOS_ECOM_REDEEMENTITLEMENTS_API_LATEST
LocalUserId권한을 등록하는 플레이어 계정의 ID
EntitlementIdCountEntitlementIds 의 요소 수
EntitlementIds등록할 권한(EOS_Ecom_EntitlementId 타입)

완료되면 EOS_Ecom_OnRedeemEntitlementsCallback 타입의 콜백이 EOS_Ecom_RedeemEntitlementsCallbackInfo 구조체를 받게 됩니다.

권한을 등록한 후에는 EOS_Ecom_QueryEntitlementsOptions 파라미터의 bIncludeRedeemedtrue로 설정되지 않은 이상 EOS_Ecom_QueryEntitlements 호출 결과에 더 이상 권한이 표시되지 않습니다. 권한은 등록한 후 캐시에 저장되며 캐시를 지우는 방법은 없습니다.

Ecom 인터페이스 용어

이 섹션은 Ecom 인터페이스에서 자주 사용되는 용어와 정의를 설명합니다.

용어정의
카탈로그 오퍼(Catalog Offers)카탈로그 오퍼는 하나 이상의 카탈로그 아이템과 해당 가격(0도 가능)을 페어링한 항목입니다. 오퍼를 구매하면 각 아이템의 권한이 부여됩니다.
카탈로그 아이템(Catalog Item)카탈로그 아이템은 전체 게임, 다운로드 콘텐츠, 게임 내 통화나 무기 스킨과 같은 가상 상품이 될 수 있습니다. 아이템은 계정에 권한이 부여되는 방식을 정의하는 데 사용됩니다. 카탈로그 항목은 에픽게임즈 스토어의 다이내믹 번들 기능을 통해 다른 카탈로그 항목을 허가할 수 있도록 구성할 수 있으며, 이를 통해 시간에 따라 연관 오퍼를 업데이트할 수 있도록 합니다. 예를 들어, 이 기능을 통해 시즌 패스 소유자가 새로운 DLC가 출시되는 대로 오너십을 부여할 수 있습니다.
권한(Entitlement)권한은 플레이어가 에픽게임즈 스토어 인프라 내에서 소유한 모든 것을 의미합니다. 권한은 하나 이상의 카탈로그 아이템에 대한 액세스를 허가할 수 있습니다.
소모성 권한(Consumable Entitlement)소모성 권한은 계속 지속되지 않으며, 게임에서 아이템을 사용할 때마다 '사용 횟수'가 감소합니다. 소모성 권한은 일반적으로 게임 내 통화, XP 부스트, 소진 후 다시 충전 구매 가능한 아이템 등에 사용됩니다. 어떤 경우에는 외부 서비스가 권한을 처리합니다. 외부 서비스가 권한에 대한 정보를 받으면 권한을 등록합니다. 사용 횟수가 0이 되면 실질적으로 플레이어 계정에서 해당 권한을 제거합니다. 외부 서비스에는 해당 시점 이후로 게임 내에 아이템이 미치는 영향을 처리할 책임이 있습니다.
지속성 권한(Durable Entitlement)특정 형태의 다운로드 콘텐츠나 심지어 전체 게임 등의 일부 구매 아이템은 계속 지속됩니다.
처리(Fulfillment)권한이 플레이어 계정에 부여된 후에도 권한은 여전히 처리되어야 합니다. 이는 암시적일 수도 있고(SDK API로 확인), 타사 서비스가 백엔드 API 호출을 통해 처리에 대한 책임을 수락할 수도 있습니다.

다음 테이블에는 Ecom 인터페이스에서 사용되는 다양한 ID 타입과 각 ID 타입의 출처 및 설명이 나와 있습니다.

ID 타입설명
카탈로그 오퍼 ID(Catalog Offer ID)카탈로그 오퍼 ID는 스토어에 있는 오퍼의 고유 식별자입니다. 이러한 ID는 제품 내에서 고유합니다. 체크아웃 프로세스를 진행하려면 카탈로그 오퍼 ID가 필요합니다.
카탈로그 아이템 ID(Catalog Item ID)카탈로그 아이템 ID는 제품 내에서 고유하며 단일 카탈로그 아이템을 식별합니다. 특정 플레이어가 해당 카탈로그 아이템을 소유하고 있는지 확인하려면 이 ID가 필요합니다.
권한 이름(Entitlement Name)각 카탈로그 아이템은 그와 연결된 권한 이름을 가질 수 있습니다. 권한 이름은 그룹화할 때 사용할 수 있습니다. 단, 권한 이름은 주로 카탈로그 아이템 ID와 동일한 값을 가집니다. Ecom 인터페이스에서 권한을 부여한 카탈로그 오퍼의 카탈로그 아이템과 관련된 권한 이름을 토대로 권한을 쿼리할 수 있습니다.
권한 ID(Entitlement ID)처리된 카탈로그 오퍼와 플레이어 계정에 플레이어와 함께 특정 권한으로 저장되어 나타난 카탈로그 아이템입니다. 각 권한에는 자체 고유 식별자가 있습니다. 이 ID는 Ecom 인터페이스에서 권한을 등록할 때 사용됩니다.