에픽 온라인 서비스(Epic Online Services, EOS) 는 계정이 카탈로그 아이템을 소유하고 있는지 검증하는 여러 가지 방법을 제공합니다. 선호되는 방식은 Ecom 인터페이스를 통해 EOS SDK API를 사용하는 것입니다. 이 문서는 RESTful 엔드포인트를 통해 오너십 정보에 액세스하는 편을 선호하는 타이틀 및 서비스를 위해 작성되었습니다. EOS에는 클라이언트와 서비스 간에 전달할 수 있는 오너십 토큰을 생성하고 토큰의 유효성을 검증하는 직접 온라인 오너십 검증을 위한 RESTful 서비스 엔드포인트와 권한 레코드를 쿼리, 열거, 소비하는 권한(Entitlements) 서비스가 있습니다.
오너십 검증의 방식은 사용 사례에 따라 다릅니다. 게임 클라이언트나 게임 서버는 엔드포인트와 직접 통합하여 온라인 방식을 사용할 수 있습니다. 오너십 검증 토큰 방식은 게임 클라이언트, 사용자, 권한에 대한 정보가 포함된 토큰에 더해 게임 클라이언트 또는 기타 모든 서비스에서 검증할 수 있는 서명도 제공합니다. 오너십 검증을 수행하는 서드 파티 서비스와 통합하는 경우 사용자의 데이터에 대한 액세스가 부여되지 않도록 오너십 검증 토큰 확인을 사용하는 것이 좋습니다.
오너십 확인은 전체 트리를 대상으로 사용자가 특정 catalogItemId에 액세스 가능한지 여부를 파악합니다. 권한(Entitlements)은 특정한 트랜잭션이 발생했는지 여부를 검증하는 데 유용합니다. 예를 들어 사용자가 게임의 디럭스 에디션을 구매했는데, 이 디럭스 에디션에 시즌 패스가 포함되고, 시즌 패스에는 DLC1에 대한 액세스가 포함된 경우, 오너십 확인으로는 DLC1에 대해 TRUE가 반환되지만 권한 확인으로는 DLC1에 대해 TRUE가 반환되지 않습니다.
시작하기 전에 인증 서비스와 통합해야 액세스 토큰을 획득할 수 있습니다. 인증에 관한 자세한 내용은 에픽 계정 서비스 시작하기를 참고하세요.
직접 오너십 검증
사용자가 아이템 또는 아이템 목록을 소유했는지 확인하는 엔드포인트입니다.
이 엔드포인트는 SDK 1.5버전 이상 또는 'https://api.epicgames.dev/epic/oauth/v1/.well-known/openid-configuration' 환경설정을 사용하여 구현된 OAuth OpenID Connect 교환을 통해 획득한 인증 토큰에 적용됩니다.
Bearer 인증을 사용하여 인증 헤더로 액세스 토큰을 전달해야 합니다.
이 엔드포인트는 다음 쿼리 파라미터를 지원합니다.
| 파라미터 | 설명 |
|---|---|
nsCatalogItemId | {{sandboxId:catalogItemId}} 형식으로 이 파라미터를 반복하여 여러 sandboxId 와 catalogItem 의 조합을 확인할 수 있습니다. |
sandboxId | 이 파라미터는 특정 샌드박스에서 소유된 catalogItemIds 의 전체 목록을 획득하는 데 사용할 수 있습니다. |
다음 스니펫은 오너십 정보를 얻기 위한 요청의 샘플입니다.
토큰 기반 오너십 검증
오너십 검증 토큰(Ownership Verification Token)은 서명된 JWT이며, 5분간 유효합니다. RS512를 사용하여 서명됩니다. SHA-512를 사용한 RSA PKCS#1 서명이며, RSA 키 크기는 2048입니다.
다음 두 단계를 거쳐 토큰 기반 오너십 검증을 수행할 수 있습니다.
-
오너십 검증 토큰 요청
-
공개 키를 사용하여 토큰의 진위 여부 검증
게임 클라이언트/서버가 오너십 검증 토큰을 획득하면, 오너십 검증을 수행해야 하는 모든 통합으로 토큰이 전달될 수 있습니다. 토큰을 검증하는 통합은 JWT를 압축 해제하여 kid(키 ID)를 추출한 다음 해당 키 ID에 대한 공개 키를 가져와서 서명을 검증해야 합니다.
토큰에는 다음과 같은 클레임이 포함됩니다.
| 클레임 | 설명 |
|---|---|
| jti | 이 토큰의 고유 식별자입니다. |
| sub | 토큰을 요청하는 데 사용된 계정의 계정 ID입니다. |
| clid | 토큰을 요청하는 데 사용된 클라이언트의 클라이언트 ID입니다. |
| ent | 이 토큰에 대해 검증된 권한 오너십의 배열입니다. 이 값이 비어 있으면 요청된 권한이 계정에 부여되지 않습니다. |
| iat | 토큰이 발급된 Unix 타임스탬프 시간입니다. |
| exp | 토큰이 만료되는 Unix 타임스탬프 시간입니다. |
오너십 검증 토큰 요청
오너십 검증 토큰을 요청하려면 클라이언트는 오너십 토큰 엔드포인트에 HTTP POST를 요청해야 합니다.
오너십 검증 토큰을 요청하는 엔드포인트는 다음과 같습니다.
Bearer 인증을 사용하여 인증 헤더로 액세스 토큰을 전달해야 합니다.
이 엔드포인트는 다음 요청 바디 파라미터를 지원합니다.
Note: The Content-Type needs to be "application/x-www-form-urlencoded" and the parameter needs to be in the request body.
| 파라미터 | 설명 |
|---|---|
nsCatalogItemId | {{sandboxId:catalogItemId}} 형식으로 이 파라미터를 반복하여 여러 sandboxId 와 catalogItem 의 조합을 확인할 수 있습니다. |
다음 스니펫은 공개 토큰을 얻기 위한 요청의 샘플입니다.
egoc1~ 은 에픽게임즈 오너십 확인을 나타내는 접두사입니다. 토큰을 디코딩할 때는 제거하세요.
이 토큰에는 JWT 헤더, 페이로드, 서명에 해당하는 base64로 인코딩된 JSON 오브젝트 3개가 포함됩니다. 자세한 내용은 JWT 문서를 참고하세요.
다음은 JWT 헤더의 샘플입니다.
다음은 JWT 바디의 샘플입니다.
오너십 검증 토큰 검증하기
토큰에서 서명을 검증하려면 공개 키를 가져와야 합니다. 키를 가져오려면 키 ID(JWT의 kid 클레임)가 필요합니다. 응답에는 JSON 웹 키(JWK)가 포함되며, 이 키를 사용하여 JWT에서 서명을 검증할 수 있습니다.
공개 키를 요청하려면 클라이언트/서비스가 공개 키 엔드포인트에 HTTP 요청을 보내야 합니다.
공개 키 엔드포인트는 다음과 같습니다.
다음 스니펫은 공개 키를 얻기 위한 요청의 샘플입니다.
직접 권한 열거
계정에 대한 직접 권한의 목록을 얻어야 하는 경우에 확인하는 엔드포인트입니다.
오너십만 확인해야 하는 경우에는 에픽에서 권장하는 위의 오너십 확인 API를 사용하세요.
Bearer 인증을 사용하여 인증 헤더로 액세스 토큰을 전달해야 합니다.
이 엔드포인트는 다음 쿼리 파라미터를 지원합니다.
| 파라미터 | 설명 |
|---|---|
sandboxId | 게임 타이틀을 위한 네임스페이스입니다. |
entitlementName | 선택 사항입니다. 권한의 이름입니다. 이름을 제공하지 않으면 sandboxId 아래의 모든 권한이 반환됩니다. 이 파라미터를 반복하여 여러 권한을 확인할 수 있습니다. |
includeRedeemed | 선택 사항입니다. 이 파라미터는 등록된 권한을 포함할지 여부를 지정합니다. 디폴트는 false 입니다. true 로 설정하지 않으면 등록되지 않은 권한만 결과에 포함됩니다. |
다음 스니펫은 사용자 및 샌드박스에 대한 모든 권한을 얻는 요청의 샘플입니다.
토큰 기반 권한 검증
권한 검증 토큰은 RS512를 사용하여 서명되는 JWT입니다. SHA-512를 사용한 RSA PKCS#1 서명이며, RSA 키 크기는 2048입니다. 생성 후 5분이 지나면 만료됩니다.
다음 두 단계를 거쳐 토큰 기반 권한 검증을 수행할 수 있습니다.
-
권한 검증 토큰 요청
-
공개 키를 사용하여 토큰의 진위 여부 검증
게임 클라이언트/서버가 권한 검증 토큰을 획득하면, 오너십 검증을 수행해야 하는 모든 통합으로 토큰이 전달될 수 있습니다. 토큰을 검증하는 통합은 JWT를 압축 해제하여 kid(키 ID)를 추출한 다음 해당 키 ID에 대한 공개 키를 가져와서 서명을 검증해야 합니다.
토큰에는 다음과 같은 클레임이 포함됩니다.
| 권한 검증 토큰 클레임 | |
|---|---|
| jti | 이 토큰의 고유 식별자입니다. |
| sub | 토큰을 요청하는 데 사용된 계정의 계정 ID입니다. |
| clid | 토큰을 요청하는 데 사용된 클라이언트의 클라이언트 ID입니다. |
| ent | 이 토큰에 대해 검증된 권한의 배열입니다. 이 값이 비어 있으면 요청된 권한 및 sandboxId 에 대한 일체의 권한이 계정에 부여되지 않습니다. |
| iat | 토큰이 발급된 Unix 타임스탬프 시간입니다. |
| exp | 토큰이 만료되는 Unix 타임스탬프 시간입니다. |
권한 검증 토큰 요청
권한 검증 토큰을 요청하려면 클라이언트는 오너십 토큰 엔드포인트에 HTTP POST를 요청해야 합니다.
권한 검증 토큰을 요청하는 엔드포인트는 https://api.epicgames.dev/epic/ecom/v1/platforms/{platform}/identities/{identityId}/entitlementToken입니다.
Bearer 인증을 사용하여 인증 헤더로 액세스 토큰을 전달해야 합니다.
이 엔드포인트는 다음 요청 파라미터를 지원합니다.
| 요청 파라미터 | |
|---|---|
sandboxId | 게임 타이틀을 위한 네임스페이스입니다. |
entitlementName | (선택 사항) 권한의 이름입니다. 이름을 제공하지 않으면 sandboxId 아래의 모든 권한이 반환됩니다. 이 파라미터를 반복하여 여러 권한을 확인할 수 있습니다. |
다음 스니펫은 공개 토큰을 얻기 위한 요청의 샘플입니다.
참고: egoc1~ 은 에픽게임즈 오너십 확인을 나타내는 접두사입니다. 토큰을 디코딩할 때는 제거하세요.
이 토큰에는 JWT 헤더, 페이로드, 서명에 해당하는 base64로 인코딩된 JSON 오브젝트 3개가 포함됩니다. 자세한 내용은 JWT 문서를 참고하세요.
다음은 JWT 헤더의 샘플입니다.
다음은 JWT 바디의 샘플입니다.
권한 검증 토큰 검증하기
토큰에서 서명을 검증하려면 공개 키를 가져와야 합니다. 키를 가져오려면 키 ID(JWT의 kid 클레임)가 필요합니다. 응답에는 JSON 웹 키(JWK)가 포함되며, 이 키를 사용하여 JWT에서 서명을 검증할 수 있습니다.
공개 키를 요청하려면 클라이언트/서비스가 공개 키 엔드포인트에 HTTP 요청을 보내야 합니다.
공개 키 엔드포인트는 https://ecommerceintegration-public-service-ecomprod02.ol.epicgames.com/ecommerceintegration/api/public/publickeys/{kid}입니다.
다음 스니펫은 공개 키를 얻기 위한 요청의 샘플입니다.
오퍼 쿼리
이용 가능한 카탈로그 오퍼의 목록을 사용자에게 요청하려면, 클라이언트는 오퍼 엔드포인트에 HTTP GET 요청을 보내야 합니다.
에픽 온라인 서비스에서 정의된 카탈로그 오퍼의 목록을 요청하기 위한 엔드포인트는 다음과 같습니다.
이 API는 SDK API EOS_Ecom_QueryOffers 와 동일한 데이터를 제공합니다. SDK API 사용에 관한 자세한 내용은 EOS API 레퍼런스 문서를 참고하세요.
Bearer 인증을 사용하여 인증 헤더로 액세스 토큰을 전달해야 합니다.
다음 스니펫은 사용자 및 샌드박스를 위한 오퍼를 요청하는 요청의 샘플입니다.
다음은 가상 화폐 오퍼에 대한 서버 측 응답의 샘플입니다.
priceInfo 구조체의 통화 값을 읽는 방법은 decimals 필드의 값에 따라 달라집니다. decimals 값이 2 인 미국 달러, 캐나다 달러, 유로 등의 경우에는 discountPrice 및 originalPrice 필드의 값이 센트 단위로 제공됩니다. 따라서 값을 달러 액수로 변환하려면 100으로 나누어야 합니다. 예를 들어 이 값이 350이면 3.50달러입니다.
decimals 필드의 값이 0 인 일본 엔, 대한민국 원 등의 경우에는 나머지 필드의 값이 지정된 통화와 완전히 일치합니다. 이 경우 변환할 필요가 없습니다.
권한 등록/소비
권한을 등록/소비하는 엔드포인트입니다. 권한이 등록되면 권한은 비활성 상태로 변경됩니다.
Bearer 인증을 사용하여 인증 헤더로 액세스 토큰을 전달해야 합니다.
이 엔드포인트는 다음 요청 바디를 지원합니다.
다음 스니펫은 사용자 및 샌드박스에 대한 여러 권한을 등록하는 요청의 샘플입니다.