퀵스타트 가이드

에픽게임즈 스토어는 다운로드 가능한 콘텐츠(Downloadable Content, DLC)나 가상 화폐 등 게임과 관련하여 구매 및 등록 가능한 아이템을 관리하는 광범위한 이커머스 기능 세트를 제공합니다. 이 시스템은 계층구조로 구성되어 있어 제품 서비스 내에서 번들을 최적화할 수 있습니다. 아래에서는 이 시스템을 더 자세히 다루고, 필수 용어를 개괄하고, 이커머스 API를 사용하여 게임 내 및 백엔드 기능을 지원하는 방법에 대한 일반적인 사용 사례를 소개합니다.

이커머스 API에 대한 추가 정보는 API 레퍼런스를 참고하세요.

에픽게임즈 스토어 이커머스 기능에 대한 이해를 돕기 위해 아래의 환경설정을 예로 들겠습니다.

그림 1. 제품 이커머스 환경설정 예시

이 예시에서 제품 (My Game)은 3개의 샌드박스(Sandbox) 로 환경설정되어 있습니다. 세 가지 샌드박스란 데브(Dev), 스테이지(Stage), 라이브(Live)입니다. 각 샌드박스에는 다음 중 하나 이상으로 구성된 자체 이커머스 환경설정이 있습니다.

• 카탈로그 오퍼(Catalog Offer) : 오퍼라고도 하는 카탈로그 오퍼는 카탈로그 아이템과 해당 가격(무료 가능)을 페어링한 것입니다. 사용자는 에픽게임즈 스토어에서 오퍼를 구매할 수 있습니다. 사용자가 오퍼를 구매하면, 백엔드 서비스는 오퍼에 포함된 각 아이템에 대한 권한 을 사용자에게 부여합니다.

  • 참고: 권한(Entitlement)은 사용자가 에픽게임즈 스토어 인프라 내에서 소유하는 무언가를 의미합니다. 권한은 하나 이상의 카탈로그 아이템에 대한 액세스를 허가할 수 있습니다.

• 카탈로그 아이템(Catalog Item) : 대상 이라고도 하는 카탈로그 아이템은 전체 게임, 게임 내 화폐 또는 무기 스킨, 기타 유형의 다운로드 가능한 콘텐츠 같은 가상 상품을 의미할 수 있습니다. 서비스는 카탈로그 아이템을 사용하여 사용자에게 권한을 어떻게 허가할지 정의합니다. 권한은 단일 카탈로그 아이템과 직접 연결되며, 이는 추가 카탈로그 아이템에 대한 오너십을 허가할 수 있습니다.

  • 팁 : 에픽게임즈 스토어의 다이내믹 번들 기능을 통해 카탈로그 아이템이 다른 카탈로그 아이템을 제공하도록 환경설정할 수 있습니다. 이 기능을 통해 연결된 오퍼를 시간이 지남에 따라 업데이트할 수 있습니다. 예를 들면 새 DLC가 출시되는 즉시 시즌 패스 소유자가 DLC의 오너십 자격을 얻도록 할 수 있습니다.

• 라이브러리 아이템(Library item) : 게임 아이템이라고도 하는 라이브러리 아이템은 에픽게임즈 스토어 인프라에서 아티팩트 ID나 클라우드 세이브 환경설정 등 카탈로그 아이템의 추가 프로퍼티를 환경설정하는 데 사용하는 카탈로그 아이템 유형입니다. 라이브러리 아이템은 항상 카탈로그 아이템과 연결됩니다.

  • 참고 아티팩트(Artifact)란 게임 클라이언트와 DLC 등과 같은 게임의 다운로드 가능 또는 플레이 가능 콘텐츠를 나타냅니다. 아티팩트는 라이브러리 아이템에 연결됩니다. 어떤 바이너리가 아티팩트에 연결되는지 환경설정하여 에픽게임즈 런처가 다운로드 및 실행하는 콘텐츠를 결정할 수 있습니다. 바이너리는 BuildPatch 툴과 함께 업로드되어 있습니다.

카탈로그 오퍼와 카탈로그 아이템은 에픽 온라인 서비스 SDK Ecom 인터페이스 또는 웹 API를 통해 노출됩니다. 이를 통해 제품에 대해 환경설정된 모든 카탈로그 오퍼 및 아이템을 쿼리하고, 카탈로그 오퍼에 대한 게임 내 체크아웃 플로를 표시하고, 카탈로그 아이템 및 권한에 대한 오너십 정보를 쿼리할 수 있습니다.

이 예시 환경설정에서는 라이브 샌드박스의 제품에 다음과 같은 4개의 오퍼를 구성했습니다.

• 기본 게임 오퍼(Base game offer) : 게임의 기본 에디션에 대한 카탈로그 오퍼입니다. 기본 게임 오퍼는 지속성 구매입니다. 플레이어가 구매 후 영구히 소유한다는 의미입니다. 이 오퍼는 다음 자손 라이브러리 아이템을 갖는 단일 카탈로그 아이템으로 구성됩니다.

  • 기본 게임 아이템(Base game item) : 게임의 기본 에디션에 대한 카탈로그 아이템입니다. 이 카탈로그 아이템은 아래 사용 사례에 설명된 기본 게임의 오너십 검증에 사용됩니다.
  • 기본 게임 라이브러리 아이템(Base game library item) : 기본 게임 아티팩트, 클라우드 세이브 게임 구성, 기타 게임 프로퍼티의 구성에 사용되는 카탈로그 아이템입니다.

• 디럭스 게임 오퍼(Deluxe game offer) : 게임의 디럭스 에디션에 대한 카탈로그 오퍼입니다. 이 오퍼는 지속성 구매이며 다음 카탈로그 아이템으로 구성됩니다.

  • 디럭스 게임 아이템(Deluxe game item) : 게임의 디럭스 에디션에 대한 카탈로그 아이템입니다. 이 에디션의 오너십을 검증하는 데 사용될 수 있습니다. 디럭스 게임 아이템은 라이브러리 아이템과 연결되지 않으며, 그 대신 위에서 설명한 기본 게임 아이템 및 아래에서 설명할 DLC 아이템과 연결됩니다.

• DLC 오퍼(DLC offer) : 게임 DLC에 대한 카탈로그 오퍼입니다. 이 오퍼는 지속성 구매입니다.

  • DLC 아이템(DLC item) : 게임 DLC에 대한 카탈로그 아이템입니다. 이 카탈로그 아이템은 DLC의 오너십을 검증하는 데 사용됩니다.
  • DLC 라이브러리 아이템(DLC library item) : 이 카탈로그 아이템은 DLC 아티팩트 및 기타 프로퍼티를 구성하는 데 사용됩니다.

• 100코인 오퍼(100 coins offer) : 게임 내 화폐 100코인에 대한 카탈로그 오퍼입니다. 이 오퍼는 소모성 구매입니다. 즉, 플레이어가 여러 번 구매하여 게임 내에서 소모성 아이템을 구입하는 데 사용할 수 있습니다.

  • 100코인 아이템(100 coins item) : 100코인 오퍼에 대한 카탈로그 아이템입니다. 이 카탈로그 아이템은 오퍼에 대한 추가 정보를 얻는 데 사용됩니다. 그러나 소모성 구매인 오퍼이므로 오너십 검증에는 사용되지 않습니다.

참고: 다른 오퍼를 구매하여 소모성 아이템을 받을 수는 없습니다. 즉, 디럭스 게임 오퍼를 구매하는 플레이어에게 구매의 일환으로 100코인을 제공하려면 플레이어에게 코인을 제공하는 게임 내 로직을 통합해야 합니다. 100코인 오퍼는 디럭스 게임의 '포함된 오퍼' 섹션에 표시되지 않기 때문입니다.

아래 섹션은 이커머스 API가 게임 내 기능 또는 백엔드 기능 지원에 어떻게 사용되는지 보여주는 일반적 사용 사례를 개괄합니다.

게임 내에서 사용자가 카탈로그 오퍼를 구매할 수 있도록 표시하기 위해 에픽 온라인 서비스 SDK와 함께 다음 절차를 사용합니다.

1. 인증 인터페이스 문서의 설명대로 EOS_Auth_Login을 통해 사용자를 인증합니다. 인증에는 보통 이 문서의 설명대로 에픽게임즈 런처에서 제공하는 ExchangeCode가 사용됩니다.
2. Ecom 인터페이스 문서의 설명대로 EOS_Ecom_QueryOffers API를 사용해 사용 가능한 카탈로그 오퍼의 목록을 가져옵니다. 설명된 패턴을 따라 오퍼 수를 결정하고 SDK 캐시로부터 자체 컬렉션으로 오퍼를 복사합니다.
   • 위 예시 구성에서는 다음 오퍼의 목록을 얻습니다.
     • 기본 게임 오퍼
     • 디럭스 게임 오퍼
     • DLC 오퍼
     • 100코인 오퍼
3. EOS_Ecom_CatalogOffer 컬렉션을 사용하여 현지화된 타이틀 및 설명, 가격, 할인 정보 등 오퍼 세부정보를 얻습니다. 오퍼 정보는 오퍼가 구매 가능한지, 현재 사용자가 이미 구매했는지 여부도 나타냅니다.

이제 보유한 정보를 사용하여 게임 내에서 오퍼를 표시하고, 사용자가 이용 가능한 오퍼를 구매하도록 버튼을 표시할 수 있습니다. 이용 가능한 오퍼는 EOS_Ecom_CatalogOffer 의 bIsAvailableForPurchases 프로퍼티로 결정됩니다. 이 플로를 사용하려면 게임이 에픽 온라인 서비스 소셜 오버레이를 사용하도록 환경설정되어야 합니다.

1. Ecom 인터페이스 문서의 설명대로 EOS_Ecom_Checkout API를 사용해 사용자가 구매하고자 하는 각 오퍼의 카탈로그 오퍼 ID를 전달합니다.
2. Ecom 인터페이스 문서의 설명대로 EOS_Ecom_CheckoutCallbackInfo가 반환한 TransactionId 를 통해 트랜잭션이 성공하였는지 확인합니다.

EOS_Ecom_Checkout API를 사용하는 트랜잭션은 지속성 구매와 소모성 구매 어느 쪽에든 해당할 수 있습니다. 자세한 정보는 필요에 따라 구매를 검증하는 다음 시나리오를 참조하세요.

플레이어 구매를 검증하는 바람직한 방법은 자체 백엔드 서비스를 사용하는 것입니다. 그러면 사용자의 악성 행동에 취약해지지 않습니다. 이 검증을 구현할 커스텀 백엔드 서비스가 없다면, 구매한 지속성 콘텐츠 검증하기 및 소모성 구매 검증 및 처리하기 사용 사례에서 클라이언트 측 검증 디테일을 참고하세요.

자체 백엔드 서비스를 통해 검증을 수행하려면 Ecom 웹 API를 활용하는 다음 메서드 중 하나를 사용합니다.

직접 검증은 액세스 토큰을 직접 사용하여 백엔드 서비스로부터 Ecom 웹 API를 호출하는 것을 말합니다.

1. 인증 웹 API 문서의 설명에 따라 Ecom 웹 API와 함께 사용할 액세스 토큰을 요청합니다.
2. Ecom 웹 API API를 사용해 지속성 구매를 검증합니다. 소모성 구매를 검증 및 등록하려면 권한 열거 및 등록 API를 사용합니다.

토큰 기반 검증은 게임 클라이언트에 의해 생성되고 백엔드 서비스로 전달되는 JSON 웹 토큰(JSON Web Token, JWT)의 진실성을 검증하는 것을 말합니다. 이 방법을 사용하면 백엔드 서비스는 퍼블릭 키를 한 번만, 혹은 키가 유효하지 않게 될 때까지 얻어서 게임 클라이언트에 의해 생성된 다수의 토큰을 검증할 수 있습니다.

• 지속성 콘텐츠(예: DLC)의 경우 : Ecom 인터페이스 문서의 지침을 따라 EOS_Ecom_QueryOwnershipToken API를 사용해 게임 클라이언트 코드에서 JWT를 생성하세요. 이 JWT에는 다수의 카탈로그 아이템에 대한 오너십 정보가 포함될 수 있습니다.
• 소모성 콘텐츠(예: 게임 내 화폐)의 경우 : Ecom 인터페이스 문서의 지침을 따라EOS_Ecom_QueryEntitlementToken API를 사용해 게임 클라이언트 코드에서 JWT를 생성하세요. 이 JWT에는 다수의 권한에 대한 권한 정보가 포함될 수 있습니다.

위 설명대로 JWT를 생성한 뒤, JWT를 백엔드 서비스에 커뮤니케이션합니다. 그런 다음, 토큰을 디코딩하고 Ecom 웹 API 문서에 따라 토큰의 진실성을 검증합니다.

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

게임 클라이언트 내에서 지속성 콘텐츠를 검증하려면 EOS_Ecom_QueryOwnership API를 사용합니다. 이 API는 카탈로그 아이템 ID의 컬렉션을 전달하여 오너십을 검증합니다. 이렇게 오너십을 검증하면 자동으로 카탈로그 아이템 간 관계를 고려합니다.

예시 환경설정에서 사용자는 디럭스 게임 오퍼 또는 기본 게임 오퍼를 구매할 수 있습니다. 각 오퍼는 기본 게임 아이템과 연결되어 있으므로, 둘 중 어느 오퍼를 구매해도 기본 게임 아이템 검증에 성공합니다. 마찬가지로 디럭스 게임 오퍼를 구매하면 DLC 아이템 검증에 성공합니다. 해당 카탈로그 아이템이 디럭스 게임 오퍼에 연결되어 있기 때문입니다.

EOS_Ecom_QueryOwnership API를 통해 지속성 콘텐츠를 검증하려면 다음 절차에 따르세요.

1. 인증 인터페이스 문서의 설명대로 EOS_Auth_Login을 통해 사용자를 인증합니다. 인증에는 보통 이 문서의 설명대로 에픽게임즈 런처에서 제공하는 ExchangeCode가 사용됩니다.

2. Ecom 인터페이스 문서의 설명대로 EOS_Ecom_QueryOffers API를 사용해 사용 가능한 카탈로그 오퍼의 목록을 가져옵니다. 설명된 패턴을 따라 오퍼 수를 결정하고 SDK 캐시로부터 자체 컬렉션으로 오퍼를 복사합니다.

3. Ecom 인터페이스 문서의 지침을 따라 오퍼 컬렉션을 반복 검색해 관련 카탈로그 아이템(EOS_Ecom_CatalogItem)을 찾습니다.

   • 예시 환경설정에서는 각 카탈로그 오퍼에 포함된 카탈로그 아이템을 가져옵니다.
     • 기본 게임 오퍼 → 기본 게임 아이템
     • 디럭스 게임 오퍼 → 디럭스 게임 아이템
     • DLC 오퍼 → DLC 아이템
     • 100코인 오퍼 → 100코인 아이템

   이러한 아이템의 오너십을 검증하는 방법에는 두 가지가 있습니다. 직접 SDK를 사용하는 것과 JSON 웹 토큰(JWT)을 생성하는 것입니다. 두 방식은 Ecom 인터페이스 문서에 각각 '직접' 방식과 '토큰 기반' 방식으로 설명되어 있습니다. 아래는 '직접' 방식을 위한 절차이며, '토큰 기반' 방식에 대한 자세한 내용은 이 가이드의 자체 백엔드 서비스를 사용하여 안전하게 구매 검증하기 섹션에서 볼 수 있습니다.

4. EOS_Ecom_QueryOwnership API를 사용하여 카탈로그 아이템 ID로 사용자의 오너십 정보를 쿼리합니다. 이 콜백은 전달된 각 카탈로그 아이템 ID마다 해당하는 EOS_Ecom_Owned 또는 EOS_Ecom_NotOwned 값과 함께 EOS_Ecom_ItemOwnership 멤버 배열을 포함합니다.

5. 위 예시 구성에서 사용자가 디럭스 게임 오퍼를 구매하면 기본 게임 아이템, 디럭스 게임 아이템, DLC 아이템이 모두 EOS_Ecom_Owned 로 표시됩니다.

소모성 구매는 각각 EOS_Ecom_QueryEntitlements 및 EOS_Ecom_RedeemEntitlements API를 통해 검증 및 소비됩니다. 이 API는 사용자가 아이템을 1회 이상 구매했는지 검증하고 게임 내에서 관련 소모성 아이템이 부여되었는지 여부에 대한 트래킹을 활성화합니다. EOS_Ecom_QueryEntitlements API는 CatalogItem ID와 동일한 EntitlementNames 를 받습니다.

예시 구성에서 사용자는 100코인 오퍼를 1회 이상 구매할 수 있으며, 이 경우 등록을 통해 코인 오퍼를 처리하여 플레이어의 계정에 코인을 추가하는 권한을 갖습니다.

EOS_Ecom_QueryEntitlements API를 지속성 콘텐츠를 검증하는 용도로 사용하면 안 됩니다 . 이 API는 관련 카탈로그 아이템 간의 관계를 고려하지 않기 때문입니다. 예시 환경설정에서 사용자는 기본 게임 아이템과 DLC 아이템 모두로 구성된 디럭스 게임 오퍼를 구매할 수 있습니다. 이 시나리오에서 EOS_Ecom_QueryEntitlements API는 디럭스 게임 아이템에 대한 권한만 반환하며, 기본 게임 아이템이나 DLC 아이템과의 관계는 무시합니다.

1. 인증 인터페이스 문서의 설명대로 EOS_Auth_Login을 통해 사용자를 인증합니다. 인증에는 보통 이 문서의 설명대로 에픽게임즈 런처에서 제공하는 ExchangeCode 가 사용됩니다.
2. 쿼리할 권한 이름을 알면 3단계로 넘어갑니다. 권한 이름을 모른다면 구매한 지속성 콘텐츠(예: DLC) 검증하기 사용 사례의 1단계 및 2단계에 따라 해당 카탈로그 아이템의 ID를 각각 얻습니다. 얻은 카탈로그 아이템 ID는 이 프로세스에 요구되는 권한 이름과 같습니다.
3. Ecom 인터페이스 문서의 지침에 따라 사용자 권한에 맞춰 SDK 캐시를 채우는 EOS_Ecom_QueryEntitlements를 호출합니다. 그런 다음 캐시의 권한을 자체 컬렉션으로 복사합니다.
   • 참고: 기본적으로 EOS_Ecom_QueryEntitlements API는 이미 등록한 권한을 생략합니다.
4. 캐시에서 복사된 EOS_Ecom_Entitlement는 사용자의 구매를 나타내며 고유한 EntitlementId 를 포함합니다. 이 ID를 사용하여 게임 코드에서 구매를 처리할 수 있습니다.
   • 예시 환경설정에서 한 사용자가 100코인 오퍼를 두 번 구매한다면, 해당 사용자에게는 두 개의 EOS_Ecom_Entitlement 사본이 별도로 존재하며 각각 고유한 EntitlementId 를 갖습니다.
5. 플레이어 계정에 코인을 추가하는 등의 게임 내 권한 처리가 완료된 후, Ecom 인터페이스 문서의 지침을 따라 EOS_Ecom_RedeemEntitlements API를 사용해 이커머스 백엔드 서비스에서 권한이 등록되었음을 표시합니다.