Ecom 인터페이스 개요

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

팁: Ecom 인터페이스 기능을 이해하기 쉽도록 이 페이지의 특정 용어는 볼드 체로 되어 있습니다. 이러한 용어에 대한 설명은 Ecom 인터페이스 용어에서 찾을 수 있습니다.

Ecom 인터페이스를 사용하려면 제품의 에픽 계정 서비스(EAS)가 구성되어 있어야 하며 기본 프로필 데이터에 액세스하려면 사용자 동의가 필요합니다. 데브 포털에서 EAS 애플리케이션을 구성하거나 에픽 계정 서비스 문서를 참조하여 자세한 내용을 알아보세요. EAS와 사용자 동의 없이도 EOS SDK와 Ecom 인터페이스를 초기화할 수 있지만, 백엔드 서비스에 보낸 모든 Ecom 인터페이스 함수 호출이 실패하게 됩니다.

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

두 가지 기능을 수행하여 인게임 스토어를 운영할 수 있습니다. 스토어로부터 카탈로그 오퍼(Catalog Offer)(오퍼 라고도 함)를 제시하고, 사용자가 이 카탈로그 오퍼를 구매하도록 지원하는 것입니다. SDK는 스토어의 카탈로그에서 오퍼 목록을 가져와 인게임을 표시하는 기능을 제공합니다. 오퍼 데이터에는 사용자가 오퍼 구매 후 얻게 될 하나 또는 다수의 카탈로그 아이템(오디언스 라고도 함)뿐만 아니라 사용자에게 오퍼 정보를 제공할 때 사용할 릴리즈 디테일도 포함됩니다.

사용자가 구매를 선택하면 체크아웃 API가 데이터를 **오버레이로 푸시하여 사용자가 구매를 완료하기 위한 체크아웃 플로를 표시합니다. 구매가 완료되면 콜백이 트리거되어 게임에 트랜잭션 결과를 알리고 트랜잭션 핸들을 제공함으로써 게임이 처리 를 수행하게 합니다.

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

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

델리게이트가 받는 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_GetItemReleaseCount 를 사용하여 현재 있는 데이터 항목의 수를 확인합니다. 그런 다음, EOS_Ecom_CopyItemReleaseByIndex 를 사용하여 개별 데이터 조각(EOS_Ecom_CatalogRelease 타입)을 가져옵니다. 이 데이터가 더 이상 필요 없으면 EOS_Ecom_CatalogRelease_Release 를 호출하여 데이터를 릴리즈하세요.

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

구매하기, 오너십 검증하기, 그리고 권한 등록하기(선택 사항) 등 스토어 구매와 관련된 세 가지 액션이 있습니다.

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

이 정보는 구매 토큰 생성에 사용됩니다. 오버레이가 표시되어 사용자가 구매를 검토하고, 구매 옵션을 선택하고, 트랜잭션을 확정 또는 취소하도록 지원합니다. 성공, 실패 또는 사용자의 취소 결정으로 인해 오버레이가 닫히면 트랜잭션 디테일이 포함된 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 를 호출하여 이 데이터를 릴리즈하세요.

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

멀티유저 또는 온라인 게임:

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

  • 이러한 확인은 일반적으로 인증 단계 중에 또는 레벨/매치에 입장하는 시점에 구현됩니다.

• 사용자가 오너십 확인에 패스하지 못하면 액세스가 거부되도록 조치하세요. 적절히 구현하면 사용자가 API 응답을 변경하거나 게임 클라이언트 자체를 수정하는 방법으로는 이 확인을 우회할 수 없습니다..

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

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

모든 게임:

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

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

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

  • 토큰을 특정 하드웨어/사용자 프로퍼티에 연결하고 사전 정의된 시간이 지나면 만료됩니다.

  • 게임 바이너리에 내장된 공개 키가 수정되지 않도록 보호해야만 효과적으로 사용할 수 있습니다.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

사용자의 계정 권한을 가져오려면, EOS_Ecom_QueryEntitlementsOptions 구조체를 사용하여 EOS_Ecom_QueryEntitlements 함수를 호출합니다.

EOS_Ecom_QueryEntitlements API를 지속성 콘텐츠(durable content) 를 검증하는 용도로 사용하면 안 됩니다. 이 API는 시즌 패스에 포함된 개별 DLC 등의 관련 카탈로그 아이템 간의 관계를 고려하지 않기 때문입니다. 따라서 EOS_Ecom_QueryEntitlements 는 보통 소모성 오퍼에 사용되며, 지속성 콘텐츠는 위의 오너십 검증하기 섹션에서 설명한 대로 관리됩니다.

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

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

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

권한을 열거하고 몇 분 동안 결과를 로컬에서 캐시하려면 EOS_Ecom_QueryEntitlementToken 을 사용합니다. 이 함수는 다음과 같이 초기화된 EOS_Ecom_QueryEntitlementTokenOptions 구조체를 사용합니다.

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

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

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

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

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

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

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